Create Shipment

POST /shipments — rate limit 30 / min · requires an active subscription

Creates the shipment with the carrier, charges the account credit and returns the shipment together with its label. The shipment is quoted first: the contract must be available for the destination and packages, exactly as in Get Rates.

Request body

Field	Type	Required	Description
`reference`	`string` (100)	No	Your order reference. Returned as `reference`, searchable in `GET /shipments?reference=`, sent in webhooks as `order_id`
`serviceType`	`string`	No	`contractCode` from `/carriers` or `/rates`. Omitted: the first contract of the quote is used
`carrierCode`	`string`	No	Optional consistency check: must match the carrier of `serviceType`, otherwise `422`
`shipper`	`Party`	No	Sender. Default: the operational address of the account
`recipient`	`Party`	Yes	Recipient; `name`, `address.street`, `address.city`, `address.postalCode`, `address.countryCode` are required
`packages[]`	`Package[]`	Yes	1 to 50 packages, each with its own `weight` and `dimensions` (multi-parcel only on contracts with `multiParcel: true`)
`packages[].description`	`string`	No	Content of the package
`packages[].value`	`number`	No	Value of the package
`options`	`object`	No	See below
`customsDetail`	`object`	Conditional	Required when the destination is outside the EU customs territory. See Customs Declaration

Party object

Field	Type	Required	Description
`name`	`string` (100)	Yes	Full name
`company`	`string` (100)	No	Company name
`address.street`	`string` (150)	Yes	Street and number
`address.street2`	`string` (100)	No	Second address line
`address.city`	`string` (80)	Yes
`address.province`	`string` (10)	No	2-letter province code for Italy
`address.postalCode`	`string` (15)	Yes
`address.countryCode`	`string` (2)	Yes	ISO 3166-1 alpha-2
`phone`	`string` (30)	No	Recommended: carriers use it for delivery notifications
`email`	`string`	No
`reference`	`string` (50)	No	Recipient reference printed on the label

Options object

Field	Type	Description
`notes`	`string` (255)	Notes for the carrier
`contentDescription`	`string` (255)	Description of the content
`labelFormat`	`"PDF"` \| `"ZPL"`	Native format of the label to generate (default `PDF`)
`cod`	`Money` + `method` / `type`	Cash on delivery. `method` is a key of `cashOnDeliveryMethods` (from `/carriers` or `/rates`); `type` is the raw carrier code, alternative to `method`
`insurance`	`Money`	Insured value
`accessoryServices`	`integer[]`	`serviceId` values from `/carriers`
`pickupFromAddress`	`boolean`	Apply the pickup surcharge

Example

Request


{
  "reference": "ORD-1234",
  "serviceType": "brt-standard",
  "carrierCode": "brt",
  "shipper": {
    "name": "Mario Rossi",
    "company": "ACME Srl",
    "address": { "street": "Via Roma 1", "city": "Milano", "province": "MI", "postalCode": "20100", "countryCode": "IT" },
    "phone": "+39 333 1234567",
    "email": "mario@acme.it"
  },
  "recipient": {
    "name": "Giulia Bianchi",
    "address": { "street": "Via Garibaldi 10", "street2": "Scala B", "city": "Roma", "province": "RM", "postalCode": "00100", "countryCode": "IT" },
    "phone": "+39 333 7654321",
    "email": "giulia@example.com",
    "reference": "DEST-9"
  },
  "packages": [
    { "weight": { "value": 1.5, "units": "KG" }, "dimensions": { "length": 30, "width": 20, "height": 10, "units": "CM" } }
  ],
  "options": {
    "notes": "Fragile",
    "contentDescription": "Abbigliamento",
    "labelFormat": "PDF",
    "cod": { "amount": 25.5, "currency": "EUR", "method": "CONT" },
    "insurance": { "amount": 0, "currency": "EUR" },
    "accessoryServices": []
  }
}

Response (201)


{
  "id": 4454058,
  "trackingNumber": "DEMO05407027",
  "returnTrackingNumber": null,
  "shipmentKey": "a1b2c3d4",
  "reference": "ORD-1234",
  "bda": null,
  "status": { "code": 0, "key": "processing", "label": "In lavorazione" },
  "carrier": { "code": "brt", "name": "BRT", "contractCode": "brt-standard", "contractName": "BRT Standard" },
  "shipper": {
    "name": "Mario Rossi", "company": "ACME Srl",
    "address": { "street": "Via Roma 1", "city": "Milano", "province": "MI", "postalCode": "20100", "countryCode": "IT" },
    "phone": "+39 333 1234567", "email": "mario@acme.it"
  },
  "recipient": {
    "name": "Giulia Bianchi",
    "address": { "street": "Via Garibaldi 10", "city": "Roma", "province": "RM", "postalCode": "00100", "countryCode": "IT" },
    "phone": "+39 333 7654321", "email": "giulia@example.com", "reference": "DEST-9"
  },
  "packages": [
    {
      "number": 1,
      "trackingNumber": "DEMO05407027",
      "incrementId": null,
      "reference": null,
      "weight": { "value": 1.5, "units": "KG" },
      "dimensions": { "length": 30, "width": 20, "height": 10, "units": "CM" }
    }
  ],
  "parcels": 1,
  "weight": { "value": 1.5, "units": "KG" },
  "volumetricWeight": { "value": 1.2, "units": "KG" },
  "billableWeight": { "value": 1.5, "units": "KG" },
  "cod": { "amount": 25.5, "currency": "EUR", "type": "CONT", "status": 0 },
  "insurance": null,
  "cost": {
    "total": 7.0,
    "currency": "EUR",
    "breakdown": { "weight": 4.0, "insurance": 0, "cod": 3.0, "services": 0, "extra": 0 }
  },
  "accessoryServices": [],
  "notes": "Fragile",
  "contentDescription": "Abbigliamento",
  "customsDetail": null,
  "labelFormat": "PDF",
  "deliveryDepot": null,
  "manifestId": null,
  "warning": null,
  "createdAt": "2026-09-03T10:26:54+02:00",
  "shippedAt": null,
  "collectedAt": null,
  "deliveredAt": null,
  "trackingUpdatedAt": null,
  "label": {
    "format": "PDF",
    "pdf": "JVBERi0xLjcKMyAwIG9iago8PC9Ue...",
    "zpl": null
  }
}

Response

201 Created with the Shipment object plus label:

Field	Type	Description
`label.format`	`"PDF"` \| `"ZPL"`	Native format of the stored label
`label.pdf`	`string\|null`	Base64-encoded PDF
`label.zpl`	`string\|null`	Base64-encoded ZPL, when `labelFormat` was `ZPL` and the carrier supports it

The label can be fetched again at any time with GET /shipments/{ldv}/label.

Rules

recipient and packages are required; shipper is optional.
Without serviceType the first contract of the quote is used. To choose, call POST /rates first.
Contract codes of level-1 reseller contracts are encrypted: pass them exactly as returned by /carriers or /rates.
Weights in KG or G, dimensions in CM or MM; every package carries its own weight.
customsDetail is mandatory for destinations outside the EU customs territory and optional elsewhere — see Customs Declaration.
The shipment is charged to the account credit (cost.total). Cancelling it with DELETE /shipments/{ldv} refunds the credit.

Errors

HTTP	`code`	When
`402`	`subscription_required` · `subscription_payment_failed` · `plan_limit_reached`	Subscription missing / unpaid / monthly limit reached; also when a reseller contract requires a subscription
`403`	`forbidden`	Encrypted contract code issued to another account
`404`	`not_found`	No contract available for this shipment, contract code unknown, no price list on the account
`422`	`validation_failed`	Invalid payload; `details` lists the fields. Also `serviceType` not available for this shipment, `carrierCode` mismatch, missing `customsDetail`, or `customsValue` not matching the commodities
`422`	`shipment_rejected`	The carrier or the business rules refused the shipment; the reason is in `message`
`429`	`rate_limited`	More than 30 requests per minute

Decoding the label

Node.js


const fs = require('fs')
fs.writeFileSync('label.pdf', Buffer.from(shipment.label.pdf, 'base64'))

Python


import base64
with open('label.pdf', 'wb') as f:
    f.write(base64.b64decode(shipment['label']['pdf']))

PHP


file_put_contents('label.pdf', base64_decode($shipment['label']['pdf']));

cURL


echo "<base64-string>" | base64 --decode > label.pdf

Store trackingNumber (the LDV): it is the identifier of every shipment endpoint (/shipments/{ldv}, label, tracking, cancellation) and of the webhook events.