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.

Overview

Get started

AI & agents

Guides

Concepts

View all invoices

View all invoices items

​View all invoices

​View all invoices items

View all invoices

View all invoices items