Skip to main content
The Invoice Items API lets you retrieve the billable line items charged to your Sendcloud account. An invoice item is a single billable line — for example a parcel fee, a pickup fee, or a subscription charge.

Pending vs invoiced items

Invoice items are returned before they are consolidated onto an invoice, so you can reconcile expected spend in near real-time.
  • Invoiced items have invoice_id set, along with tax and tax_rate.
  • Pending items have invoice_id, tax, and tax_rate set to null. Tax is only computed when the item is invoiced.
Pending invoice items are not final. Amounts and types can still change, and Sendcloud may remove items, up until they are consolidated onto an invoice. Treat pending items as a preview, not a guarantee.

Items in another currency

An item charged in another currency than the one you are billed in has a conversion object. Its price is in your billed currency, and conversion shows how it was converted:
  • original_price is the price before conversion, in the currency it was charged in.
  • exchange_rate is the rate price was converted at. It includes the currency conversion fee.
  • reference_rate is the rate before the currency conversion fee.
  • currency_conversion_fee is the part of price the fee adds, with the fee rate as a fraction (0.0200 is 2%). Its rate and value are 0.0000 when no fee applies, and it is null when it is not available for the item.
Items charged in your billed currency have conversion set to null. The Exchange Rates API returns the rate for each day.

Item types and subtypes

Every item has a type (for example shipment, surcharge, or subscription). Some types are further specified by a subtype: surcharge and surcharge refund items carry the surcharge that was applied (for example dimensional), so you can tell surcharges apart without parsing the description. Items without a subtype have subtype set to null.

Subtype values

The subtypes below are the values you can expect today. Sendcloud maintains this list and adds new subtypes when carriers introduce new surcharges or new services are launched, so treat subtype as an open string: handle values you do not recognize gracefully rather than rejecting them. Surcharges come in pairs. The refund of a surcharge is a surcharge_refund item whose subtype is the surcharge’s subtype with a _refund suffix (for example dimensional and dimensional_refund). Each of the above also exists with a _refund suffix. Items for add-ons and services (for example addon, notification or subscription items) use these subtypes:

Brands and integrations

Items that relate to a parcel carry the brand and the integration the parcel was announced with, each as an object with an id and a name. All items of the parcel carry the same values, also surcharges, refunds and insurance. Use them to split your costs per brand or per integration. The names are the names at the time the parcel was announced. brand and integration are null when the item has no parcel, or when no brand or integration was recorded for the parcel.

Filtering

Filter the list with created_after / created_before (compared against the item’s billing date, both inclusive), parcel_id, invoice_id, or type. See the Retrieve a list of invoice items endpoint for the full list of supported parameters.

Pagination

This endpoint uses cursor-based pagination via Link response headers. See Pagination for details.