Skip to main content
POST
Book and follow Location

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Accept-Language
string
default:en

Preferred language(s) for translatable content using BCP 47 language tags. Supports quality values (q-factors) for priority ordering. The API negotiates the best available language based on this header, the team's configured language, and available translations. If omitted, the team's default language is used.

Example:

"da-DK, da;q=0.9, en;q=0.8"

Request-ID
string

Optional client-supplied request identifier. When provided and matching the validation pattern, the value is echoed back in the Request-ID response header. Otherwise the server generates one. Use this to correlate requests between client and server when reporting issues.

Required string length: 1 - 64
Pattern: ^[A-Za-z0-9._-]{1,64}$
Idempotency-Key
string

Optional, case-sensitive key for one intended action. Scope: team, HTTP method and canonical path. Retained for at least 24 hours and while processing. Same key and payload reuses the stored outcome without repeating side effects; the resource representation is current. Changed payload: 422 with an Idempotency-Key entry in errors. Concurrent duplicate: 409 with Retry-After and Location when known. Without a key there is no deduplication. Use GET at Location after 202.

Required string length: 16 - 128
Pattern: ^[A-Za-z0-9._-]{16,128}$

Path Parameters

teamUuid
string<uuid>
required

Team uuid. All resources are scoped to this team.

Body

application/json

Immutable input for one logical booking. currency, weight_unit and dimension_unit must be supplied explicitly for every shipment, including each member added to a batch. Missing or null values fail upfront validation with 422; team defaults are never used for these fields. Optional fields may be omitted. No per-booking document/print preference overrides.

currency
string
required

Required ISO 4217 currency code for all submitted shipment, parcel and item amounts. Amounts use currency minor units. No fallback to team defaults.

Required string length: 3
Pattern: ^[A-Z]{3}$
Example:

"EUR"

weight_unit
enum<string>
required

Required common unit for all submitted parcel and item weights. No per-value overrides or fallback to team defaults.

Available options:
g,
kg,
lb,
oz
Example:

"g"

dimension_unit
enum<string>
required

Required common unit for all submitted parcel and item dimensions. No per-value overrides or fallback to team defaults.

Available options:
mm,
cm,
m,
in
Example:

"cm"

delivery
object
required

Selected delivery product and shipment-specific options. A requested delivery window must be supported by that product; an estimate from discovery is not a reservation.

parties
object
required

Omit merchant to use the appropriate team address. Pickup points belong to delivery.

parcels
object[]
required

Parcels in stable input order.

Minimum array length: 1
invoice_number
null | string

Customs invoice number when applicable. Use reference for the public order reference.

Example:

"INV-1001121"

reference
null | string

Public reference, e.g. order number or SKU, which may be forwarded to the carrier or printed. Not necessarily unique.

Example:

"Order-5521"

identifier
null | string

Private integration reference, e.g. a database ID. Not used for deduplication and not forwarded to carrier labels. Not necessarily unique.

uri
null | string<uri>

URI linking to the source of this shipment (webshop order URL, deep link, or any URI scheme)

total_net_amount
null | integer

Total goods value in minor units (cents) excluding tax

Example:

15920

tax_amount
null | integer

Total goods tax in minor units (cents)

Example:

3980

duty_amount
null | integer

Total goods duty in minor units (cents)

Example:

5572

shipping_net_amount
null | integer

Shipping cost in minor units (cents) excluding tax

Example:

3920

shipping_tax_amount
null | integer

Shipping tax in minor units (cents)

Example:

980

content_type
enum<string>

Type of contents in the shipment

Available options:
commercial_goods,
returned_goods,
gift,
commercial_sample,
documents,
other

Response

Shipment booked with all required documents and codes ready.

data
object
required

Current immutable booking input plus evolving lifecycle and results. Each shipment has one logical booking. Full event and print histories are retrieved through their own paginated endpoints. A failed document workflow may still have a carrier booking; never blindly rebook such a result.