Invoices (beta)

Please note that the following endpoints are in beta and API contract is subject to change.

An invoice is a request for payment for Shippo services. It is a collection of invoice items. You can query your invoice at any time to see your current charges. Shippo sends invoices weekly or when your bill has exceeded $100. Shippo Billing FAQs.

object_id
string

Unique identifier of the given Invoice object

object_created
string <date-time>

Date and time of Invoice creation.

object_updated
string <date-time>

Date and time of last Invoice update.

shippo_account
string

Unique identifier of the user who the Invoice has been issued to.

invoice_number
string

Human readable unique identifier of the given Invoice object that is displayed in the web app.

status
string (InvoiceStatus)

The status of the Invoice.

Enum: "DRAFT" "POSTED" "PAID" "UNCOLLECTIBLE" "VOID"
invoice_closed
string <date-time>

Date and time of when the Invoice was posted and no new Invoice Items were added. Field will be null when invoice is still in the draft status.

invoice_paid_date
string <date-time>

Date and time of when the Invoice was successfully paid. Field will be null when invoice is not in the paid status.

object (AmountAndCurrencyInvoiced)

The amount and currency.

object (AmountAndCurrencyCharged)

The amount and currency that was charged after possible currency conversion occurred.

{
  • "object_id": "ec9f0d3adc9441449c85d315f0997fd5",
  • "object_created": "2019-08-24T14:15:22Z",
  • "object_updated": "2019-08-24T14:15:22Z",
  • "shippo_account": "915d94940ea54c3a80cbfa328722f5a1",
  • "invoice_number": 234167,
  • "status": "POSTED",
  • "invoice_closed": "2019-08-24T14:15:22Z",
  • "invoice_paid_date": "2019-08-24T14:15:22Z",
  • "total_invoiced": {
    },
  • "total_charged": {
    }
}

Invoice Item

Invoice items are the individual amounts owed to Shippo. They can represent a purchased label or a charge for a service. Invoice items also represent refunds. They are the line items in an invoice.

object_id
string

Unique identifier of the given Invoice Item object.

object_created
string <date-time>

Date and time of Invoice Item creation.

object_updated
string <date-time>

Date and time of last Invoice Item update.

shippo_account
string

Unique identifier of the user who the Invoice Item has been issued to.

type
string (InvoiceItemTypes)

The type of the Invoice Item.

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.
Enum: "LABEL_PAYMENT" "LABEL_SURCHARGE" "LABEL_REFUND" "ONE_OFF_CREDIT" "TRACK_FEE" "ADDRESS_VALIDATION_FEE" "SUBSCRIPTION_PLAN_FEE" "PROMO_CODE_CREDIT" "PREAUTH_CAPTURE" "LABEL_PAYMENT_ADJUSTMENT" "LABEL_REFUND_ADJUSTMENT"
description
string

Additional information about what the Invoice Item is for.

amount
string

The money amount that the Invoice Item represents.

currency
string

The currency that 'amount' is in. The official ISO 4217 currency codes are used, e.g. "USD" or "EUR". ISO 4217 Standard.

object (ConversionAmount)

Invoice Item's amount after currency conversion took place.

invoice
string

Unique identifier of the Invoice that the Invoice Item belongs to.

transaction
string

Unique identifier of the Transaction that the Invoice Item represents. Not all Invoice Items are linked to a transaction.

{
  • "object_id": "ec9f0d3adc9441449c85d315f0997fd5",
  • "object_created": "2019-08-24T14:15:22Z",
  • "object_updated": "2019-08-24T14:15:22Z",
  • "shippo_account": "915d94940ea54c3a80cbfa328722f5a1",
  • "type": "LABEL_PAYMENT",
  • "description": "monthly subscription plan fee for 2019-08-24",
  • "amount": "5.54",
  • "currency": "USD",
  • "charge_conversion": {
    },
  • "invoice": "011044d8405e43bd8b1efe1c21f967df",
  • "transaction": "915d94940ea54c3a80cbfa328722f5a1"
}