Invoices
An invoice is a request for payment for Shippo services. It is a collection of invoice items. If you created your Shippo account before 11/15/2022, Shippo will generate a new invoice if your accumulated bill is greater than $100 or if it’s been seven days since your last invoice. If you created your Shippo account after 11/15/2022, Shippo will generate an invoice for each purchase you make. For more details, see this article.
To learn more about Shippo invoices, see our Billing FAQ.
Normally, invoices are emailed to you and are stored in your Shippo account. If you would prefer to access your invoice information programmatically, we also provide access using the endpoints
https://api.goshippo.com/invoices and https://api.goshippo.com/invoice-items.
View all invoices
The invoice object is the total amount you are charged. To see all your invoices, follow this example. Results are paginated and can be filtered.
curl https://api.goshippo.com/invoices?results=20&page=2 \
-H "Authorization: ShippoToken <API_TOKEN>" \
-H "Content-Type: application/json"The response will look like this.
{
"next": "baseurl?page=3&results=10",
"previous": "baseurl?page=1&results=10",
"results": [
{
"object_id": "ec9f0d3adc9441449c85d315f0997fd5",
"object_created": "2023-05-24T14:15:22Z",
"object_updated": "2023-05-24T14:15:22Z",
"shippo_account": "915d94940ea54c3a80cbfa328722f5a1",
"invoice_number": 234167,
"status": "POSTED",
"invoice_closed": "2023-05-24T14:15:22Z",
"invoice_paid_date": "2023-05-24T14:15:22Z",
"total_invoiced": {
"amount": "5.52",
"currency": "USD"
},
"total_charged": {
"amount": "5.52",
"currency": "USD"
}
}
]
}To see an individual invoice, you can pass the object ID of an individual invoice
https://https://api.goshippo.com/invoices/{InvoiceObjectId}
View all invoices items
Invoice items are the individual items that make up an invoice. For example, label payment, surcharges, subscription plan fee, etc. There are a number of ways to select which invoice items you see. Using the query parameters you can select by invoiceObjectId , invoiceNumber, and shippoAccountId (if you have Shippo managed accounts).
https://api.goshippo.com/invoice-items?results=20&page=2&invoiceObjectId="ec9f0d3adc9441449c85d315f0997fd5" \
-H "Authorization: ShippoToken <API_TOKEN>" \
-H "Content-Type: application/json"The response will look like this.
{
"next": "baseurl?page=3&results=10",
"previous": "baseurl?page=1&results=10",
"results": [
{
"object_created": "2023-05-24T14:15:22Z",
"object_updated": "2023-05-24T14:15:22Z",
"shippo_account": "915d94940ea54c3a80cbfa328722f5a1",
"type": "LABEL_PAYMENT",
"description": "monthly subscription plan fee for 2023-05-24",
"amount": "5.54",
"currency": "USD",
"charge_conversion": {
"rate": "0.89",
"time": "2023-05-24T14:15:22Z",
"amount": "4.91",
"currency": "USD"
},
"invoice": "011044d8405e43bd8b1efe1c21f967df",
"transaction": "915d94940ea54c3a80cbfa328722f5a1"
}
]
}The key value pair type shows the classification of the type of invoice item.
See the table below for a list of possible types of invoice items.
| Type | Description |
|---|---|
| LABEL_PAYMENT | Invoice Item for the payment of a label. |
| LABEL_SURCHARGE | Invoice Item for a surcharge of a label. See here for more information. |
| LABEL_REFUND | Invoice Item for a refund of a label. |
| ONE_OFF_CREDIT | Invoice Item for credit given by Shippo. |
| TRACK_FEE | Invoice Item for fees associated with tracking services. |
| ADDRESS_VALIDATION_FEE | Invoice Item for fees associated with global address validation services. |
| SUBSCRIPTION_PLAN_FEE | Invoice Item for subscription plan fees. |
| PROMO_CODE_CREDIT | Invoice Item for promotional code related credits. |
| PREAUTH_CAPTURE | Invoice Item for preauthorization capture. Represents a credit. See here for more information. |
| LABEL_PAYMENT_ADJUSTMENT | Invoice Item for adjustments on label purchases. |
| LABEL_REFUND_ADJUSTMENT | Invoice Item for adjustments on label refunds. |