Shipments
Shipments
Carrier shipments for orders. Create a DPD parcel from an order, download its label and track its delivery status.
The Shipment object
Attributes
Shipment identifier (shp_ prefix).
{
"id": "shp_6595a27b5d35015c3ef0c601",
"entity_id": "ent_6595a27b5d35015c3ef0c3fc",
"order_id": "ord_6595a27b5d35015c3ef0c701",
"shipping_connection_id": "shc_6595a27b5d35015c3ef0c501",
"carrier": "dpd_si",
"status": "created",
"carrier_status": null,
"carrier_status_checked_at": null,
"tracking_numbers": [
"16972000336597"
],
"tracking_urls": [
"https://www.dpdgroup.com/si/mydpd/my-parcels/incoming?parcelNumber=16972000336597"
],
"parcel_type": "home",
"parcel_count": 1,
"weight_kg": 2.5,
"cod": {
"amount": 49.9,
"currency": "EUR",
"reference": "1001"
},
"recipient": {
"name": "Ana Novak",
"street": "Slovenska cesta",
"house_number": "12a",
"city": "Ljubljana",
"post_code": "1000",
"country": "SI",
"phone": "38640123456",
"email": "ana@example.com"
},
"reference": "1001",
"remark": null,
"label_format": "pdf_a6",
"label_available": true,
"printed_at": "2026-11-02T10:00:05.000Z",
"error": null,
"tracking_pushed_at": "2026-11-02T10:00:06.000Z",
"tracking_push_error": null,
"created_at": "2026-11-02T10:00:00.000Z",
"updated_at": "2026-11-02T10:00:06.000Z"
}Create a shipment
/shipmentsRegister a parcel with the carrier and print its label. With order_id, every omitted field comes from the order's shipment draft; without it recipient and parcel_type are required. Values are validated against the carrier's limits before any carrier call (422 with field errors).
The response is 201 with the shipment. If the label cannot be printed or stored, or another request is printing it at the same moment, the shipment is still created with 201: label_available is false, error says why when printing failed, and GET /shipments/{id}/label (downloadShipmentLabel) fetches or retries the label.
Errors: 409 shipment_exists when the order already has a live shipment (send allow_additional to override); 409 shipment_request_in_progress with the shipment_id when a shipment without an order, or an additional one, was already created, or is still being created, under the same x-request-id (the carrier is not called again); 422 with the carrier's code and field when the carrier rejects the parcel (nothing is created); 422 invalid_carrier_credentials; 502 carrier_outcome_unknown with a shipment_id when the carrier did not answer and a parcel may exist (the shipment is kept with status unknown).
For a WooCommerce order and a connection with push_tracking_to_store, the tracking number is added to the store order as a customer note; a failure there is recorded on the shipment and never fails the request.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Body parameters
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.shipments.create({
order_id: "ord_6595a27b5d35015c3ef0c701"
}, {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
Shipment identifier (shp_ prefix).
{
"id": "shp_6595a27b5d35015c3ef0c601",
"entity_id": "ent_6595a27b5d35015c3ef0c3fc",
"order_id": "ord_6595a27b5d35015c3ef0c701",
"shipping_connection_id": "shc_6595a27b5d35015c3ef0c501",
"carrier": "dpd_si",
"status": "created",
"carrier_status": null,
"carrier_status_checked_at": null,
"tracking_numbers": [
"16972000336597"
],
"tracking_urls": [
"https://www.dpdgroup.com/si/mydpd/my-parcels/incoming?parcelNumber=16972000336597"
],
"parcel_type": "home",
"parcel_count": 1,
"weight_kg": 2.5,
"cod": {
"amount": 49.9,
"currency": "EUR",
"reference": "1001"
},
"recipient": {
"name": "Ana Novak",
"street": "Slovenska cesta",
"house_number": "12a",
"city": "Ljubljana",
"post_code": "1000",
"country": "SI",
"phone": "38640123456",
"email": "ana@example.com"
},
"reference": "1001",
"remark": null,
"label_format": "pdf_a6",
"label_available": true,
"printed_at": "2026-11-02T10:00:05.000Z",
"error": null,
"tracking_pushed_at": "2026-11-02T10:00:06.000Z",
"tracking_push_error": null,
"created_at": "2026-11-02T10:00:00.000Z",
"updated_at": "2026-11-02T10:00:06.000Z"
}Download several labels as one PDF
/shipments/labelsMerge the labels of 1-50 shipments into one PDF, in the order given. A shipment without a stored label is printed once more; if any shipment still has no label (or is being printed by another request) the response is 409 labels_unavailable with the shipment_ids concerned. Unknown shipment ids answer 404.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Body parameters
Shipments whose labels to merge, in the order they should appear (1-50).
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const blob = await sdk.shipments.downloadShipmentLabels({
shipment_ids: [
"shp_6595a27b5d35015c3ef0c601",
"shp_6595a27b5d35015c3ef0c602"
]
}, {
entity_id: "YOUR_ENTITY_ID"
});
const arrayBuffer = await blob.arrayBuffer();
const { writeFile } = await import('node:fs/promises');
await writeFile('download.bin', Buffer.from(arrayBuffer));
console.log('Saved download.bin');List shipments
/shipmentsRetrieve the entity's shipments, newest first, with cursor-based pagination. Filter by order_id and status.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Query parameters
Number of results per request.
Default: 10
Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.
Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response.
Whether to include the total count of items in pagination.total.
Default is true.
When false, pagination.total returns -1 for better performance.
Only shipments of this order.
Only shipments in this status.
Possible values: "creating", "created", "cancelled", "failed", "unknown"
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.shipments.listShipments(undefined, {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
Pagination metadata including cursors and result counts
{
"data": [
{
"id": "shp_6595a27b5d35015c3ef0c601",
"entity_id": "ent_6595a27b5d35015c3ef0c3fc",
"order_id": "ord_6595a27b5d35015c3ef0c701",
"shipping_connection_id": "shc_6595a27b5d35015c3ef0c501",
"carrier": "dpd_si",
"status": "created",
"carrier_status": null,
"carrier_status_checked_at": null,
"tracking_numbers": [
"16972000336597"
],
"tracking_urls": [
"https://www.dpdgroup.com/si/mydpd/my-parcels/incoming?parcelNumber=16972000336597"
],
"parcel_type": "home",
"parcel_count": 1,
"weight_kg": 2.5,
"cod": {
"amount": 49.9,
"currency": "EUR",
"reference": "1001"
},
"recipient": {
"name": "Ana Novak",
"street": "Slovenska cesta",
"house_number": "12a",
"city": "Ljubljana",
"post_code": "1000",
"country": "SI",
"phone": "38640123456",
"email": "ana@example.com"
},
"reference": "1001",
"remark": null,
"label_format": "pdf_a6",
"label_available": true,
"printed_at": "2026-11-02T10:00:05.000Z",
"error": null,
"tracking_pushed_at": "2026-11-02T10:00:06.000Z",
"tracking_push_error": null,
"created_at": "2026-11-02T10:00:00.000Z",
"updated_at": "2026-11-02T10:00:06.000Z"
}
],
"pagination": {
"total": 1,
"next_cursor": null,
"prev_cursor": null,
"has_more": false
}
}Get a shipment
/shipments/{id}Get a shipment
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Path parameters
Shipment identifier (shp_ prefix).
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.shipments.getShipment("shp_6595a27b5d35015c3ef0c601", {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
Shipment identifier (shp_ prefix).
{
"id": "shp_6595a27b5d35015c3ef0c601",
"entity_id": "ent_6595a27b5d35015c3ef0c3fc",
"order_id": "ord_6595a27b5d35015c3ef0c701",
"shipping_connection_id": "shc_6595a27b5d35015c3ef0c501",
"carrier": "dpd_si",
"status": "created",
"carrier_status": null,
"carrier_status_checked_at": null,
"tracking_numbers": [
"16972000336597"
],
"tracking_urls": [
"https://www.dpdgroup.com/si/mydpd/my-parcels/incoming?parcelNumber=16972000336597"
],
"parcel_type": "home",
"parcel_count": 1,
"weight_kg": 2.5,
"cod": {
"amount": 49.9,
"currency": "EUR",
"reference": "1001"
},
"recipient": {
"name": "Ana Novak",
"street": "Slovenska cesta",
"house_number": "12a",
"city": "Ljubljana",
"post_code": "1000",
"country": "SI",
"phone": "38640123456",
"email": "ana@example.com"
},
"reference": "1001",
"remark": null,
"label_format": "pdf_a6",
"label_available": true,
"printed_at": "2026-11-02T10:00:05.000Z",
"error": null,
"tracking_pushed_at": "2026-11-02T10:00:06.000Z",
"tracking_push_error": null,
"created_at": "2026-11-02T10:00:00.000Z",
"updated_at": "2026-11-02T10:00:06.000Z"
}Get an order's shipment draft
/orders/{id}/shipment-draftDerive the shipment values for an order: recipient (from the shipping address, falling back to billing), parcel type, parcel count, weight, cash on delivery and reference. warnings lists values that need attention; over-long values are kept, never truncated. Uses the entity's single active shipping connection unless shipping_connection_id is given; none answers 422 shipping_connection_required.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Path parameters
Order identifier (ord_ prefix).
Query parameters
Connection to derive the draft for. Defaults to the entity's single active connection.
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.shipments.getOrderShipmentDraft("ord_6595a27b5d35015c3ef0c701", undefined, {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
{
"shipping_connection_id": "shc_6595a27b5d35015c3ef0c501",
"recipient": {
"name": "Ana Novak",
"street": "Slovenska cesta",
"house_number": "12a",
"city": "Ljubljana",
"post_code": "1000",
"country": "SI",
"phone": "38640123456",
"email": "ana@example.com"
},
"parcel_type": "home",
"parcel_count": 1,
"weight_kg": 2.5,
"cod": {
"amount": 49.9,
"currency": "EUR",
"reference": "1001"
},
"reference": "1001",
"remark": null,
"warnings": []
}Download a shipment label
/shipments/{id}/labelDownload the label PDF. A stored label is available to every reader. When the label was never stored it is printed at the carrier once more, which needs the same permission as creating a shipment (403 Insufficient permissions for a read-only user; nothing is sent to the carrier). 409 label_unavailable when the carrier will not print it again (download it from the carrier portal); 409 shipment_busy while another request is printing this shipment's label or cancelling it (try again in a moment); 409 for a cancelled, failed or unconfirmed shipment.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Path parameters
Shipment identifier (shp_ prefix).
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const blob = await sdk.shipments.downloadShipmentLabel("shp_6595a27b5d35015c3ef0c601", {
entity_id: "YOUR_ENTITY_ID"
});
const arrayBuffer = await blob.arrayBuffer();
const { writeFile } = await import('node:fs/promises');
await writeFile('download.bin', Buffer.from(arrayBuffer));
console.log('Saved download.bin');Cancel a shipment
/shipments/{id}/cancelCancel the parcel at the carrier: deleted when its label was never printed, cancelled otherwise. 409 shipment_already_cancelled for a cancelled shipment. A shipment in status unknown is refused with 409 shipment_outcome_unknown unless the body has local_only: true, which marks it cancelled without calling the carrier (use it after checking the carrier portal that no parcel exists). 409 shipment_busy while the shipment's label is being printed (try again in a moment). The carrier refusing the cancellation answers 422.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Path parameters
Shipment identifier (shp_ prefix).
Body parameters
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.shipments.cancelShipment("shp_6595a27b5d35015c3ef0c601", {}, {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
Shipment identifier (shp_ prefix).
{
"id": "shp_6595a27b5d35015c3ef0c601",
"entity_id": "ent_6595a27b5d35015c3ef0c3fc",
"order_id": "ord_6595a27b5d35015c3ef0c701",
"shipping_connection_id": "shc_6595a27b5d35015c3ef0c501",
"carrier": "dpd_si",
"status": "cancelled",
"carrier_status": null,
"carrier_status_checked_at": null,
"tracking_numbers": [
"16972000336597"
],
"tracking_urls": [
"https://www.dpdgroup.com/si/mydpd/my-parcels/incoming?parcelNumber=16972000336597"
],
"parcel_type": "home",
"parcel_count": 1,
"weight_kg": 2.5,
"cod": {
"amount": 49.9,
"currency": "EUR",
"reference": "1001"
},
"recipient": {
"name": "Ana Novak",
"street": "Slovenska cesta",
"house_number": "12a",
"city": "Ljubljana",
"post_code": "1000",
"country": "SI",
"phone": "38640123456",
"email": "ana@example.com"
},
"reference": "1001",
"remark": null,
"label_format": "pdf_a6",
"label_available": true,
"printed_at": "2026-11-02T10:00:05.000Z",
"error": null,
"tracking_pushed_at": "2026-11-02T10:00:06.000Z",
"tracking_push_error": null,
"created_at": "2026-11-02T10:00:00.000Z",
"updated_at": "2026-11-02T10:00:06.000Z"
}