Shipments — List, Label & Cancel
Every shipment is identified by its tracking number (LDV), returned as trackingNumber when you create it.
List shipments
GET /shipments — paginated
| Query parameter | Type | Description |
|---|---|---|
from, to | date | Creation date range. Default: the last 30 days |
status | string | Status key or code, or a comma-separated list (delivered,held_at_depot or 5,6) — see statuses |
carrierCode | string | e.g. brt |
serviceType | string | Contract code |
trackingNumber | string | Exact LDV |
reference | string | Your order reference (exact match) |
city | string | Partial, case-insensitive |
countryCode | string (2) | Destination country |
hasCod, hasInsurance | boolean | Shipments with (or without) cash on delivery / insurance |
storeId | integer | Shipments created from the orders of a store |
per_page, page | integer | Pagination |
The recipientName and postalCode filters are reserved to the Spedisci.online apps and answer 422 validation_failed — see Recipient personal data.
curl "https://<subdomain>.spedisci.online/api/2026-09/shipments?from=2026-09-01&status=in_transit,out_for_delivery&per_page=100" \
-H "Authorization: Bearer <access_token>" \
-H "Accept: application/json"The response is a paginated list of Shipment objects (without label).
Shipment detail
GET /shipments/{ldv}
Returns the Shipment object. 404 not_found when the LDV does not exist or belongs to another client.
Shipment object
| Field | Type | Description |
|---|---|---|
id | integer | Internal shipment id (used by POST /manifests as shipmentIds) |
trackingNumber | string | LDV / carrier tracking number |
returnTrackingNumber | string|null | LDV of the Poste return issued with or booked on the shipment — see Poste Returns |
shipmentKey | string|null | Public key of the shipment (tracking page) |
reference | string|null | Your order reference |
bda | string|null | BDA |
status | Status | { code, key, label } |
carrier | Carrier | { code, name, contractCode, contractName } |
warehouseId | integer|null | Pickup point the shipment left from (Settings → Pickup points) |
shipper | Party | Sender address as stored — your own address, returned in full |
recipient | Destination | Where the shipment goes: { "address": { "city", "province", "countryCode" } } only — see Recipient personal data |
packages[] | object[] | One entry per package: number, trackingNumber (per-package LDV), incrementId (carrier parcel id), reference, weight, dimensions |
parcels | integer | Number of packages |
weight, volumetricWeight, billableWeight | Weight | Real, volumetric and billed weight |
cod | object|null | { amount, currency, type, status } — status: 0 pending, 1 processing, 2 paid out |
insurance | Money|null | |
cost | object | { total, currency, breakdown: { weight, insurance, cod, services, extra } } |
accessoryServices | integer[] | Service ids applied |
contentDescription | string|null | |
customsDetail | object|null | The customs declaration as stored, without the importer block |
deliveryPoint | object|null | The Poste / BRT point the shipment is delivered to — see Delivery Points |
labelFormat | string | Native label format |
deliveryDepot | string|null | Destination depot (BRT) |
manifestId | integer|null | Id of the manifest the shipment was closed in |
hasWarning | boolean | The carrier raised a warning when the shipment was created |
createdAt, shippedAt, collectedAt, deliveredAt, trackingUpdatedAt | datetime|null | Lifecycle timestamps |
Get the label
GET /shipments/{ldv}/label?format=pdf|zpl&returnLabel=merged|separate
Returns the label of an existing shipment in base64. Without format both formats are returned where available. A Poste return label issued with the shipment follows the outbound label in the same file (returnLabel=merged, default) or comes apart in returnLabel with returnLabel=separate — see Poste Returns.
Request
curl "https://<subdomain>.spedisci.online/api/2026-09/shipments/DEMO05407027/label?format=pdf" \
-H "Authorization: Bearer <access_token>" \
-H "Accept: application/json"| Field | Type | Description |
|---|---|---|
format | "PDF" | "ZPL" | Native format of the stored label |
pdf | string|null | Base64 PDF (null when format=zpl) |
zpl | string|null | Base64 ZPL (null when format=pdf or the carrier cannot provide ZPL) |
returnLabel | object|null | Only with returnLabel=separate: { trackingNumber, pdf, zpl, code } of the return label, null when there is none |
Cancel a shipment
DELETE /shipments/{ldv}
Cancels the shipment with the carrier and refunds the cost to the account credit. Possible only while the shipment is not yet in a manifest or in transit.
Request
curl -X DELETE https://<subdomain>.spedisci.online/api/2026-09/shipments/DEMO05407027 \
-H "Authorization: Bearer <access_token>" \
-H "Accept: application/json"| HTTP | code | When |
|---|---|---|
404 | not_found | Unknown LDV or shipment of another client |
409 | invalid_state | The shipment is already in a manifest or in transit |
502 | carrier_error | The carrier did not accept the cancellation |
Cancelling is final: to ship again create a new shipment. The label of a cancelled shipment must not be used.