openapi: 3.1.0
info:
title: Invoice Items API
version: 3.0.0
contact:
name: Sendcloud API Support
url: https://www.sendcloud.dev
email: contact@sendcloud.com
description: The Invoice Items API lets you retrieve the billable line items charged to your Sendcloud account, including pending items that have not yet been consolidated onto an invoice.
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://panel.sendcloud.sc/api/v3
description: Sendcloud Production
tags:
- name: Invoice Items
description: A single billable line — for example a parcel fee, a pickup fee, or a subscription charge.
paths:
/invoice-items:
get:
summary: Retrieve a list of invoice items
tags:
- Invoice Items
operationId: sc-public-v3-scp-get-invoice_items
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds:
- read:invoice
x-sendcloud-paginated: true
x-sendcloud-paginated-discriminator: data
x-mint:
href: /api/v3/invoice-items/retrieve-a-list-of-invoice-items
content: |-
OAuth2 scopes required: `read:invoice`. See [Scopes for OAuth apps](/api/v3/scopes).
description: |-
Retrieve a paginated list of invoice items for your organization.
The response includes both **invoiced** items (where `invoice_id` is set) and **pending** items that have been billed but not yet consolidated onto an invoice (where `invoice_id` is `null` and `tax` / `tax_rate` are `null`). Use the date filters to scope the result set, and the cursor in the `Link` response header to page through results.
This endpoint uses cursor-based pagination via `Link` headers. See [Pagination](/api/v3/pagination) for details.
Pending invoice items (where `invoice_id` is `null`) 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.
parameters:
- schema:
type: string
format: date-time
in: query
name: created_after
description: Return invoice items dated on or after this timestamp (inclusive). ISO 8601 with timezone.
example: '2026-01-01T00:00:00Z'
- schema:
type: string
format: date-time
in: query
name: created_before
description: Return invoice items dated on or before this timestamp (inclusive). ISO 8601 with timezone.
example: '2026-01-31T23:59:59Z'
- schema:
type: integer
in: query
name: parcel_id
description: Return only invoice items linked to this parcel id.
- schema:
type: integer
in: query
name: invoice_id
description: Return only invoice items belonging to this invoice id.
- schema:
type: string
enum:
- addon
- addon_refund
- carrier_impl_fee
- carrier_parcel_fee
- claim
- coulance
- customer_impl_fee
- earned_credit
- fuel_refund
- fuel_surcharge
- import_adm_fee
- import_duties
- import_vat
- insurance
- insurance_refund
- invoice_check_fee
- invoice_check_fee_refund
- notification
- overcharge_fee
- parcel_cancelled
- parcel_fee
- parcel_fee_refund
- pickup
- pickup_cancelled
- pickup_subscription
- refund
- shipment
- subscription
- subscription_refund
- surcharge
- surcharge_refund
- unblock
- validation
in: query
name: type
description: Return only invoice items of this type. Returns 400 if the value is not a recognized public type.
example: shipment
- $ref: '#/components/parameters/Cursor'
- schema:
type: integer
minimum: 1
maximum: 500
default: 100
in: query
name: page_size
description: The size of the page to fetch. Defaults to 100, max 500.
example: 100
responses:
'200':
description: OK
content:
application/json:
schema:
description: Retrieve invoice items
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/invoice-item'
required:
- data
examples:
RetrieveInvoiceItems:
summary: Retrieve a list of invoice items
value:
data:
- id: 1042
type: shipment
subtype: null
description: Parcel 99887766 — NL → DE
created_at: '2026-05-14T08:21:00Z'
updated_at: '2026-05-14T08:21:00Z'
price:
value: '5.4200'
currency: EUR
tax:
value: '1.1382'
currency: EUR
tax_rate: '0.21'
vat_code: NL_STANDARD
reference: '99887766'
parcel_id: 99887766
brand:
id: 3021
name: Acme
integration:
id: 48210
name: Acme Webshop
pickup_id: null
carrier_id: 17
from_country: NL
invoice_id: 5501
- id: 1043
type: surcharge
subtype: dimensional
description: Dimensional surcharge — parcel 99887767 (pending invoice)
created_at: '2026-06-02T14:05:00Z'
updated_at: null
price:
value: '4.1000'
currency: EUR
tax: null
tax_rate: null
vat_code: null
reference: '99887767'
parcel_id: 99887767
brand:
id: 3021
name: Acme
integration:
id: 48210
name: Acme Webshop
pickup_id: null
carrier_id: 17
from_country: NL
invoice_id: null
headers:
Link:
description: The pagination links, according to the web linking specification (RFC8288).
schema:
type: string
example: ; rel="prev", ; rel="next"
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
examples:
BadRequest:
summary: Unknown invoice item type
value:
errors:
- detail: Unknown invoice item type `foo`.
status: '400'
code: invalid
source:
parameter: type
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
examples:
Unauthorized:
summary: Missing or invalid credentials
value:
errors:
- detail: Authentication credentials were not provided.
status: '401'
code: not_authenticated
'429':
description: Throttled
/invoice-items/{invoice_item_id}:
parameters:
- schema:
type: integer
in: path
name: invoice_item_id
description: The id of the invoice item.
required: true
get:
summary: Retrieve an invoice item
tags:
- Invoice Items
operationId: sc-public-v3-scp-get-invoice_item
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds:
- read:invoice
x-mint:
href: /api/v3/invoice-items/retrieve-an-invoice-item
content: |-
OAuth2 scopes required: `read:invoice`. See [Scopes for OAuth apps](/api/v3/scopes).
description: |-
Retrieve a single invoice item by id.
The item may be **invoiced** (`invoice_id` set, `tax` and `tax_rate` populated) or **pending** (`invoice_id`, `tax`, and `tax_rate` are `null`).
Pending invoice items (where `invoice_id` is `null`) 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.
responses:
'200':
description: OK
content:
application/json:
schema:
description: Retrieve invoice item
type: object
properties:
data:
$ref: '#/components/schemas/invoice-item'
required:
- data
examples:
RetrieveInvoiceItem:
summary: Retrieve an invoice item
value:
data:
id: 1042
type: shipment
subtype: null
description: Parcel 99887766 — NL → DE
created_at: '2026-05-14T08:21:00Z'
updated_at: '2026-05-14T08:21:00Z'
price:
value: '5.4200'
currency: EUR
tax:
value: '1.1382'
currency: EUR
tax_rate: '0.21'
vat_code: NL_STANDARD
reference: '99887766'
parcel_id: 99887766
brand:
id: 3021
name: Acme
integration:
id: 48210
name: Acme Webshop
pickup_id: null
carrier_id: 17
from_country: NL
invoice_id: 5501
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
examples:
Unauthorized:
summary: Missing or invalid credentials
value:
errors:
- detail: Authentication credentials were not provided.
status: '401'
code: not_authenticated
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
examples:
NotFound:
summary: Invoice item not found
value:
errors:
- detail: Not found.
status: '404'
code: not_found
'429':
description: Throttled
components:
securitySchemes:
HTTPBasicAuth:
type: http
description: Basic Authentication using API key and secrets is currently the main authentication mechanism.
scheme: basic
OAuth2ClientCreds:
type: oauth2
description: OAuth2 is a standardized protocol for authorization that allows users to share their private resources stored on one site with another site without having to provide their credentials. OAuth2 Client Credentials Grant workflow. This workflow is typically used for server-to-server interactions that require authorization to access specific resources.
flows:
clientCredentials:
tokenUrl: https://account.sendcloud.com/oauth2/token/
scopes:
read:analytics: View your shipping analytics
read:audit-log: View your account's audit log
read:brand: View your brands
write:brand: Manage your brands
write:carrier: Configure carriers and contracts
read:checkout: View your dynamic checkout configurations and templates
read:event-subscription: View your event subscriptions
write:event-subscription: Create and manage your event subscriptions
read:integration: View your integrations
write:integration: Connect and manage integrations
read:invoice: View your invoices
read:notification: View your notifications
write:notification: Manage your notifications
read:operational-settings: View your warehouses, shipping lanes, and other operational settings
write:operational-settings: Manage your warehouses, shipping lanes, and other operational settings
read:order: View your orders
write:order: Import and process your orders
read:organization: View organization settings
write:organization: Change organization settings
read:parcel: View your shipments and their tracking status
write:parcel: Create, announce, and cancel shipments
read:pickup: View carrier pickups and the options available for scheduling them
write:pickup: Schedule and manage carrier pickups
read:price: View shipping prices
write:product: Manage your product catalog
read:return: View your returns
write:return: Create and manage returns
read:return-settings: View your return settings
write:return-settings: Configure your return settings
read:service-point: View carrier service points
read:shipping-method: View shipping methods, products and prices
read:shipping-rule: View your shipping rules
write:shipping-rule: Create and manage shipping rules
read:support-ticket: View your support tickets
write:support-ticket: Manage your support tickets
read:tracking-message: View your tracking notifications
write:tracking-message: Manage your tracking notifications
read:tracking-page: View your tracking page
write:tracking-page: Customize your tracking page
read:user: Read your basic account information
parameters:
Cursor:
in: query
name: cursor
description: |-
The cursor query string is used as the pivot value to filter results. If no value is provided, the first page of results will be returned. To get this value, you must encode the offset, reverse and position into a base64 string.
There are 3 possible parameters to encode:
- `o`: Offset
- `r`: Reverse
- `p`: Position
For example, `r=1&p=300` encoded as a base64 string would be `cj0xJnA9MzAw`. The query string would then be `cursor=cj0xJnA9MzAw`.
schema:
type: string
example: cj0xJnA9MzAw
schemas:
price:
title: Price
description: |-
A money amount exposed at full database precision (up to 4 decimal places).
Note: this representation uses 4-decimal precision (unlike the canonical
2-decimal Price model used elsewhere in the v3 API) because invoice items
store amounts at the precision used by Sendcloud's billing engine.
type: object
properties:
value:
type: string
description: Monetary amount as a decimal string, with up to 4 decimal places.
example: '12.3456'
currency:
type: string
description: ISO 4217 currency code.
example: EUR
required:
- value
- currency
invoice-item:
title: InvoiceItem
description: A single billable line on an invoice (or a pending, not-yet-invoiced item).
type: object
properties:
id:
type: integer
format: int64
minimum: 1
description: Unique identifier of the invoice item.
type:
type: string
description: The type of the invoice item.
enum:
- addon
- addon_refund
- carrier_impl_fee
- carrier_parcel_fee
- claim
- coulance
- customer_impl_fee
- earned_credit
- fuel_refund
- fuel_surcharge
- import_adm_fee
- import_duties
- import_vat
- insurance
- insurance_refund
- invoice_check_fee
- invoice_check_fee_refund
- notification
- overcharge_fee
- parcel_cancelled
- parcel_fee
- parcel_fee_refund
- pickup
- pickup_cancelled
- pickup_subscription
- refund
- shipment
- subscription
- subscription_refund
- surcharge
- surcharge_refund
- unblock
- validation
example: shipment
subtype:
type:
- string
- 'null'
description: |-
Subtype of the invoice item, when the type is further specified. For
`surcharge` and `surcharge_refund` items this identifies which surcharge was
applied (for example `dimensional` or `drop_off_surcharge`). Null when the
item has no subtype. The set of values is managed by Sendcloud and may
grow over time, so treat it as an open string rather than a fixed list. See
the [Invoice Items API overview](/api/v3/invoice-items) for the current
list of subtypes and their meaning.
example: dimensional
description:
type: string
description: Human-readable description of the invoice item.
created_at:
type: string
format: date-time
description: Date the invoice item was created (the billing date of the item).
updated_at:
type:
- string
- 'null'
format: date-time
description: Date the invoice item was last updated. Null if it has never been updated.
price:
$ref: '#/components/schemas/price'
tax:
oneOf:
- $ref: '#/components/schemas/price'
- type: 'null'
description: |-
Tax amount for this item. Null for pending items: the tax rate is only
populated when the item is invoiced.
tax_rate:
type:
- string
- 'null'
description: Tax rate applied to the price (e.g. '0.21' for 21%). Null until the item is invoiced.
example: '0.21'
vat_code:
type:
- string
- 'null'
description: VAT code applied to this item. Null if no VAT code applies.
reference:
type: string
description: External reference for this invoice item.
parcel_id:
type:
- integer
- 'null'
description: Identifier of the parcel this item relates to, when applicable.
brand:
oneOf:
- type: object
properties:
id:
type: integer
description: Identifier of the brand.
example: 3021
name:
type: string
description: Name of the brand at the time the parcel was announced.
example: Acme
required:
- id
- name
- type: 'null'
description: |-
The brand the parcel was announced with. All items of the parcel carry
it, so you can split costs per brand. Null when the item has no parcel or
no brand was recorded for the parcel.
integration:
oneOf:
- type: object
properties:
id:
type: integer
description: Identifier of the integration (shop).
example: 48210
name:
type: string
description: Name of the integration at the time the parcel was announced.
example: Acme Webshop
required:
- id
- name
- type: 'null'
description: |-
The integration (shop) the parcel was announced with. All items of the
parcel carry it, so you can split costs per integration. Null when the
item has no parcel or no integration was recorded for the parcel.
pickup_id:
type:
- integer
- 'null'
description: Identifier of the pickup this item relates to, when applicable.
carrier_id:
type:
- integer
- 'null'
description: Identifier of the carrier this item relates to, when applicable.
from_country:
type: string
description: Origin country of the item, as an ISO 3166-1 alpha-2 code.
example: NL
invoice_id:
type:
- integer
- 'null'
description: Identifier of the invoice this item belongs to. Null for pending items that have not yet been invoiced.
required:
- id
- type
- subtype
- description
- created_at
- updated_at
- price
- tax
- tax_rate
- vat_code
- reference
- parcel_id
- brand
- integration
- pickup_id
- carrier_id
- from_country
- invoice_id
ErrorObject:
title: Error
type: object
description: Error in a JSON:API error format
properties:
id:
type: string
description: A unique identifier for the error.
links:
type: object
description: A set of hyperlinks that provide additional information about the error.
properties:
about:
type: string
description: A URL that provides additional information about the error.
status:
type: string
format: int32
description: The HTTP status code of the error.
minLength: 1
code:
type: string
description: A unique error code for the error, in snake case format.
minLength: 1
enum:
- unknown_field
- invalid
- forbidden
- invalid_choice
- min_value
- 'null'
- not_found
- required
- not_a_list
- non_field_errors
- authentication_failed
- validation_error
- parcel_announcement_error
title:
type: string
description: A short, human-readable summary of the error.
minLength: 1
detail:
type: string
description: A human-readable explanation of the error.
minLength: 1
source:
type: object
description: An object that identifies the source of the error within the request payload.
properties:
pointer:
type: string
description: A `JSON` pointer to the location of the error within the request payload.
parameter:
type: string
description: The name of the `query` parameter that caused the error.
header:
type: string
description: The name of the `header` parameter that caused the error.
meta:
type: object
description: Additional metadata about the error.
errors:
title: Errors
type: object
description: A standardized format for errors in JSON:API responses.
properties:
errors:
type:
- array
- object
items:
type: object
allOf:
- $ref: '#/components/schemas/ErrorObject'
required:
- status
- code
- detail