// Persist one key per intended booking if you need safe network-error recovery.
async function bookShipment(url, token, input, idempotencyKey, signal) {
const headers = { Authorization: 'Bearer ' + token, 'Content-Type': 'application/json' };
if (idempotencyKey) headers['Idempotency-Key'] = idempotencyKey;
let response = await fetch(url, { method: 'POST', headers, body: JSON.stringify(input), signal });
let body = await response.json();
// Non-2xx can still contain a persisted shipment, e.g. 424 or a booking timeout.
if (!response.ok) throw Object.assign(new Error(body.message ?? body.data?.error?.message ?? 'Booking failed'), { status: response.status, body });
if (response.status === 202) {
const location = response.headers.get('Location');
if (!location) throw new Error('Missing shipment Location');
while (['queued', 'booking', 'cancelling'].includes(body.data.state)) {
await new Promise(resolve => setTimeout(resolve, 1000 * Number(response.headers.get('Retry-After') ?? 5)));
response = await fetch(location, { headers: { Authorization: 'Bearer ' + token }, signal });
body = await response.json();
if (!response.ok) throw Object.assign(new Error(body.message ?? 'Polling failed'), { status: response.status, body });
}
}
if (body.data.state === 'failed') throw Object.assign(new Error(body.data.error.message), { shipment: body.data });
return body.data;
}curl --request POST \
--url https://api.smartsend.io/v2/teams/{teamUuid}/shipments \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"identifier": "shop-order-1042",
"reference": "ORDER-1042",
"currency": "DKK",
"weight_unit": "g",
"dimension_unit": "cm",
"delivery": {
"service_code": "postnord_agent",
"pickup_point": {
"uuid": "99999999-9999-4999-8999-999999999999"
}
},
"parties": {
"customer": {
"address": {
"address_lines": [
"Eksempelvej 10"
],
"postal_code": "8000",
"city": "Aarhus C",
"country": "DK"
},
"contact": {
"name_lines": [
"Example Customer"
],
"email": "customer@example.com",
"phone": "+4512345678"
}
}
},
"parcels": [
{
"identifier": "shop-parcel-1",
"reference": "ORDER-1042-1",
"gross_weight": 1500,
"length": 30,
"width": 20,
"height": 15
}
]
}
'import requests
url = "https://api.smartsend.io/v2/teams/{teamUuid}/shipments"
payload = {
"identifier": "shop-order-1042",
"reference": "ORDER-1042",
"currency": "DKK",
"weight_unit": "g",
"dimension_unit": "cm",
"delivery": {
"service_code": "postnord_agent",
"pickup_point": { "uuid": "99999999-9999-4999-8999-999999999999" }
},
"parties": { "customer": {
"address": {
"address_lines": ["Eksempelvej 10"],
"postal_code": "8000",
"city": "Aarhus C",
"country": "DK"
},
"contact": {
"name_lines": ["Example Customer"],
"email": "customer@example.com",
"phone": "+4512345678"
}
} },
"parcels": [
{
"identifier": "shop-parcel-1",
"reference": "ORDER-1042-1",
"gross_weight": 1500,
"length": 30,
"width": 20,
"height": 15
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.smartsend.io/v2/teams/{teamUuid}/shipments",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'identifier' => 'shop-order-1042',
'reference' => 'ORDER-1042',
'currency' => 'DKK',
'weight_unit' => 'g',
'dimension_unit' => 'cm',
'delivery' => [
'service_code' => 'postnord_agent',
'pickup_point' => [
'uuid' => '99999999-9999-4999-8999-999999999999'
]
],
'parties' => [
'customer' => [
'address' => [
'address_lines' => [
'Eksempelvej 10'
],
'postal_code' => '8000',
'city' => 'Aarhus C',
'country' => 'DK'
],
'contact' => [
'name_lines' => [
'Example Customer'
],
'email' => 'customer@example.com',
'phone' => '+4512345678'
]
]
],
'parcels' => [
[
'identifier' => 'shop-parcel-1',
'reference' => 'ORDER-1042-1',
'gross_weight' => 1500,
'length' => 30,
'width' => 20,
'height' => 15
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.smartsend.io/v2/teams/{teamUuid}/shipments"
payload := strings.NewReader("{\n \"identifier\": \"shop-order-1042\",\n \"reference\": \"ORDER-1042\",\n \"currency\": \"DKK\",\n \"weight_unit\": \"g\",\n \"dimension_unit\": \"cm\",\n \"delivery\": {\n \"service_code\": \"postnord_agent\",\n \"pickup_point\": {\n \"uuid\": \"99999999-9999-4999-8999-999999999999\"\n }\n },\n \"parties\": {\n \"customer\": {\n \"address\": {\n \"address_lines\": [\n \"Eksempelvej 10\"\n ],\n \"postal_code\": \"8000\",\n \"city\": \"Aarhus C\",\n \"country\": \"DK\"\n },\n \"contact\": {\n \"name_lines\": [\n \"Example Customer\"\n ],\n \"email\": \"customer@example.com\",\n \"phone\": \"+4512345678\"\n }\n }\n },\n \"parcels\": [\n {\n \"identifier\": \"shop-parcel-1\",\n \"reference\": \"ORDER-1042-1\",\n \"gross_weight\": 1500,\n \"length\": 30,\n \"width\": 20,\n \"height\": 15\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.smartsend.io/v2/teams/{teamUuid}/shipments")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"identifier\": \"shop-order-1042\",\n \"reference\": \"ORDER-1042\",\n \"currency\": \"DKK\",\n \"weight_unit\": \"g\",\n \"dimension_unit\": \"cm\",\n \"delivery\": {\n \"service_code\": \"postnord_agent\",\n \"pickup_point\": {\n \"uuid\": \"99999999-9999-4999-8999-999999999999\"\n }\n },\n \"parties\": {\n \"customer\": {\n \"address\": {\n \"address_lines\": [\n \"Eksempelvej 10\"\n ],\n \"postal_code\": \"8000\",\n \"city\": \"Aarhus C\",\n \"country\": \"DK\"\n },\n \"contact\": {\n \"name_lines\": [\n \"Example Customer\"\n ],\n \"email\": \"customer@example.com\",\n \"phone\": \"+4512345678\"\n }\n }\n },\n \"parcels\": [\n {\n \"identifier\": \"shop-parcel-1\",\n \"reference\": \"ORDER-1042-1\",\n \"gross_weight\": 1500,\n \"length\": 30,\n \"width\": 20,\n \"height\": 15\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.smartsend.io/v2/teams/{teamUuid}/shipments")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"identifier\": \"shop-order-1042\",\n \"reference\": \"ORDER-1042\",\n \"currency\": \"DKK\",\n \"weight_unit\": \"g\",\n \"dimension_unit\": \"cm\",\n \"delivery\": {\n \"service_code\": \"postnord_agent\",\n \"pickup_point\": {\n \"uuid\": \"99999999-9999-4999-8999-999999999999\"\n }\n },\n \"parties\": {\n \"customer\": {\n \"address\": {\n \"address_lines\": [\n \"Eksempelvej 10\"\n ],\n \"postal_code\": \"8000\",\n \"city\": \"Aarhus C\",\n \"country\": \"DK\"\n },\n \"contact\": {\n \"name_lines\": [\n \"Example Customer\"\n ],\n \"email\": \"customer@example.com\",\n \"phone\": \"+4512345678\"\n }\n }\n },\n \"parcels\": [\n {\n \"identifier\": \"shop-parcel-1\",\n \"reference\": \"ORDER-1042-1\",\n \"gross_weight\": 1500,\n \"length\": 30,\n \"width\": 20,\n \"height\": 15\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"data": {
"currency": "DKK",
"weight_unit": "g",
"dimension_unit": "cm",
"invoice_number": null,
"reference": "ORDER-1042",
"identifier": "shop-order-1042",
"uri": null,
"delivery": {
"carrier": {
"code": "postnord",
"name": "PostNord",
"logo_url": null,
"icon_url": null
},
"last_mile_carrier": {
"code": "postnord",
"name": "PostNord",
"logo_url": null,
"icon_url": null
},
"service_code": "postnord_agent",
"service_name": "Service point",
"is_pickup": true,
"is_return": false,
"addons": [],
"pickup_point": {
"uuid": "99999999-9999-4999-8999-999999999999",
"carrier_code": "postnord",
"code": "12345",
"name": "Example Parcel Shop",
"address": {
"address_lines": [
"Eksempelvej 20"
],
"postal_code": "8000",
"city": "Aarhus C",
"country": "DK",
"administrative_area": null
}
},
"delivery_window": null,
"incoterm": null
},
"parties": {
"merchant": {
"reference": null,
"identifier": null,
"uri": null,
"address": {
"address_lines": [
"Eksempelgade 1"
],
"postal_code": "2100",
"city": "Copenhagen",
"country": "DK",
"administrative_area": null
},
"contact": {
"name_lines": [
"Example Shop"
],
"company": "Example Shop",
"email": "shop@example.com",
"phone": "+4587654321"
},
"identifiers": null
},
"customer": {
"reference": null,
"identifier": null,
"uri": null,
"address": {
"address_lines": [
"Eksempelvej 10"
],
"postal_code": "8000",
"city": "Aarhus C",
"country": "DK",
"administrative_area": null
},
"contact": {
"name_lines": [
"Example Customer"
],
"company": null,
"email": "customer@example.com",
"phone": "+4512345678"
},
"identifiers": null
}
},
"parcels": [
{
"reference": "ORDER-1042-1",
"identifier": "shop-parcel-1",
"freetext": null,
"gross_weight": 1500,
"length": 30,
"width": 20,
"height": 15,
"total_net_amount": null,
"tax_amount": null,
"duty_amount": null,
"items": [],
"uuid": "33333333-3333-4333-8333-333333333333",
"tracking_number": "00340434161094015749",
"tracking_url": "https://track.smartsend.io/example",
"tracking": {
"uuid": "66666666-6666-4666-8666-666666666666",
"tracking_number": "00340434161094015749",
"tracking_url": "https://track.smartsend.io/example",
"state": "InfoReceived",
"description": "Shipment information received.",
"estimated_delivery": null,
"delivered_at": null,
"returned_at": null,
"last_updated_at": "2026-09-16T10:00:02Z"
}
}
],
"total_net_amount": null,
"tax_amount": null,
"duty_amount": null,
"shipping_net_amount": null,
"shipping_tax_amount": null,
"content_type": null,
"uuid": "22222222-2222-4222-8222-222222222222",
"state": "booked",
"documents": [
{
"uuid": "44444444-4444-4444-8444-444444444444",
"name": "Shipping label",
"filename": "ORDER-1042-label.pdf",
"types": [
"label"
],
"format": "pdf",
"mime_type": "application/pdf",
"size_bytes": 18342,
"width": {
"value": 210,
"unit": "mm"
},
"height": {
"value": 297,
"unit": "mm"
},
"page_count": 1,
"url": "https://downloads.example.com/documents/label.pdf",
"url_expires_at": "2026-09-16T10:15:02Z",
"description": "Print and attach the label.",
"source": {
"type": "shipment",
"uuid": "22222222-2222-4222-8222-222222222222"
},
"print_status": null,
"created_at": "2026-09-16T10:00:02Z",
"updated_at": "2026-09-16T10:00:02Z"
}
],
"qr_codes": [],
"drop_off_codes": [],
"batch_uuid": null,
"error": null,
"created_at": "2026-09-16T10:00:00Z",
"updated_at": "2026-09-16T10:00:02Z",
"booked_at": "2026-09-16T10:00:02Z",
"cancelled_at": null,
"voided_at": null
}
}Create and book a shipment
Require explicit currency, weight_unit and dimension_unit, validate all input before persistence, snapshot applicable team booking settings, then start one carrier booking. Return 201 only when the carrier booking and every required document/QR/drop-off code are ready. Wait up to 10 seconds, otherwise return 202 and poll the ordinary shipment GET. No separate create-draft or rebooking operation exists. Carrier rejection is 424; upfront validation is 422 with no persisted shipment. Idempotency is optional; identical requests without a key can book separate shipments.
// Persist one key per intended booking if you need safe network-error recovery.
async function bookShipment(url, token, input, idempotencyKey, signal) {
const headers = { Authorization: 'Bearer ' + token, 'Content-Type': 'application/json' };
if (idempotencyKey) headers['Idempotency-Key'] = idempotencyKey;
let response = await fetch(url, { method: 'POST', headers, body: JSON.stringify(input), signal });
let body = await response.json();
// Non-2xx can still contain a persisted shipment, e.g. 424 or a booking timeout.
if (!response.ok) throw Object.assign(new Error(body.message ?? body.data?.error?.message ?? 'Booking failed'), { status: response.status, body });
if (response.status === 202) {
const location = response.headers.get('Location');
if (!location) throw new Error('Missing shipment Location');
while (['queued', 'booking', 'cancelling'].includes(body.data.state)) {
await new Promise(resolve => setTimeout(resolve, 1000 * Number(response.headers.get('Retry-After') ?? 5)));
response = await fetch(location, { headers: { Authorization: 'Bearer ' + token }, signal });
body = await response.json();
if (!response.ok) throw Object.assign(new Error(body.message ?? 'Polling failed'), { status: response.status, body });
}
}
if (body.data.state === 'failed') throw Object.assign(new Error(body.data.error.message), { shipment: body.data });
return body.data;
}curl --request POST \
--url https://api.smartsend.io/v2/teams/{teamUuid}/shipments \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"identifier": "shop-order-1042",
"reference": "ORDER-1042",
"currency": "DKK",
"weight_unit": "g",
"dimension_unit": "cm",
"delivery": {
"service_code": "postnord_agent",
"pickup_point": {
"uuid": "99999999-9999-4999-8999-999999999999"
}
},
"parties": {
"customer": {
"address": {
"address_lines": [
"Eksempelvej 10"
],
"postal_code": "8000",
"city": "Aarhus C",
"country": "DK"
},
"contact": {
"name_lines": [
"Example Customer"
],
"email": "customer@example.com",
"phone": "+4512345678"
}
}
},
"parcels": [
{
"identifier": "shop-parcel-1",
"reference": "ORDER-1042-1",
"gross_weight": 1500,
"length": 30,
"width": 20,
"height": 15
}
]
}
'import requests
url = "https://api.smartsend.io/v2/teams/{teamUuid}/shipments"
payload = {
"identifier": "shop-order-1042",
"reference": "ORDER-1042",
"currency": "DKK",
"weight_unit": "g",
"dimension_unit": "cm",
"delivery": {
"service_code": "postnord_agent",
"pickup_point": { "uuid": "99999999-9999-4999-8999-999999999999" }
},
"parties": { "customer": {
"address": {
"address_lines": ["Eksempelvej 10"],
"postal_code": "8000",
"city": "Aarhus C",
"country": "DK"
},
"contact": {
"name_lines": ["Example Customer"],
"email": "customer@example.com",
"phone": "+4512345678"
}
} },
"parcels": [
{
"identifier": "shop-parcel-1",
"reference": "ORDER-1042-1",
"gross_weight": 1500,
"length": 30,
"width": 20,
"height": 15
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.smartsend.io/v2/teams/{teamUuid}/shipments",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'identifier' => 'shop-order-1042',
'reference' => 'ORDER-1042',
'currency' => 'DKK',
'weight_unit' => 'g',
'dimension_unit' => 'cm',
'delivery' => [
'service_code' => 'postnord_agent',
'pickup_point' => [
'uuid' => '99999999-9999-4999-8999-999999999999'
]
],
'parties' => [
'customer' => [
'address' => [
'address_lines' => [
'Eksempelvej 10'
],
'postal_code' => '8000',
'city' => 'Aarhus C',
'country' => 'DK'
],
'contact' => [
'name_lines' => [
'Example Customer'
],
'email' => 'customer@example.com',
'phone' => '+4512345678'
]
]
],
'parcels' => [
[
'identifier' => 'shop-parcel-1',
'reference' => 'ORDER-1042-1',
'gross_weight' => 1500,
'length' => 30,
'width' => 20,
'height' => 15
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.smartsend.io/v2/teams/{teamUuid}/shipments"
payload := strings.NewReader("{\n \"identifier\": \"shop-order-1042\",\n \"reference\": \"ORDER-1042\",\n \"currency\": \"DKK\",\n \"weight_unit\": \"g\",\n \"dimension_unit\": \"cm\",\n \"delivery\": {\n \"service_code\": \"postnord_agent\",\n \"pickup_point\": {\n \"uuid\": \"99999999-9999-4999-8999-999999999999\"\n }\n },\n \"parties\": {\n \"customer\": {\n \"address\": {\n \"address_lines\": [\n \"Eksempelvej 10\"\n ],\n \"postal_code\": \"8000\",\n \"city\": \"Aarhus C\",\n \"country\": \"DK\"\n },\n \"contact\": {\n \"name_lines\": [\n \"Example Customer\"\n ],\n \"email\": \"customer@example.com\",\n \"phone\": \"+4512345678\"\n }\n }\n },\n \"parcels\": [\n {\n \"identifier\": \"shop-parcel-1\",\n \"reference\": \"ORDER-1042-1\",\n \"gross_weight\": 1500,\n \"length\": 30,\n \"width\": 20,\n \"height\": 15\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.smartsend.io/v2/teams/{teamUuid}/shipments")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"identifier\": \"shop-order-1042\",\n \"reference\": \"ORDER-1042\",\n \"currency\": \"DKK\",\n \"weight_unit\": \"g\",\n \"dimension_unit\": \"cm\",\n \"delivery\": {\n \"service_code\": \"postnord_agent\",\n \"pickup_point\": {\n \"uuid\": \"99999999-9999-4999-8999-999999999999\"\n }\n },\n \"parties\": {\n \"customer\": {\n \"address\": {\n \"address_lines\": [\n \"Eksempelvej 10\"\n ],\n \"postal_code\": \"8000\",\n \"city\": \"Aarhus C\",\n \"country\": \"DK\"\n },\n \"contact\": {\n \"name_lines\": [\n \"Example Customer\"\n ],\n \"email\": \"customer@example.com\",\n \"phone\": \"+4512345678\"\n }\n }\n },\n \"parcels\": [\n {\n \"identifier\": \"shop-parcel-1\",\n \"reference\": \"ORDER-1042-1\",\n \"gross_weight\": 1500,\n \"length\": 30,\n \"width\": 20,\n \"height\": 15\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.smartsend.io/v2/teams/{teamUuid}/shipments")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"identifier\": \"shop-order-1042\",\n \"reference\": \"ORDER-1042\",\n \"currency\": \"DKK\",\n \"weight_unit\": \"g\",\n \"dimension_unit\": \"cm\",\n \"delivery\": {\n \"service_code\": \"postnord_agent\",\n \"pickup_point\": {\n \"uuid\": \"99999999-9999-4999-8999-999999999999\"\n }\n },\n \"parties\": {\n \"customer\": {\n \"address\": {\n \"address_lines\": [\n \"Eksempelvej 10\"\n ],\n \"postal_code\": \"8000\",\n \"city\": \"Aarhus C\",\n \"country\": \"DK\"\n },\n \"contact\": {\n \"name_lines\": [\n \"Example Customer\"\n ],\n \"email\": \"customer@example.com\",\n \"phone\": \"+4512345678\"\n }\n }\n },\n \"parcels\": [\n {\n \"identifier\": \"shop-parcel-1\",\n \"reference\": \"ORDER-1042-1\",\n \"gross_weight\": 1500,\n \"length\": 30,\n \"width\": 20,\n \"height\": 15\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"data": {
"currency": "DKK",
"weight_unit": "g",
"dimension_unit": "cm",
"invoice_number": null,
"reference": "ORDER-1042",
"identifier": "shop-order-1042",
"uri": null,
"delivery": {
"carrier": {
"code": "postnord",
"name": "PostNord",
"logo_url": null,
"icon_url": null
},
"last_mile_carrier": {
"code": "postnord",
"name": "PostNord",
"logo_url": null,
"icon_url": null
},
"service_code": "postnord_agent",
"service_name": "Service point",
"is_pickup": true,
"is_return": false,
"addons": [],
"pickup_point": {
"uuid": "99999999-9999-4999-8999-999999999999",
"carrier_code": "postnord",
"code": "12345",
"name": "Example Parcel Shop",
"address": {
"address_lines": [
"Eksempelvej 20"
],
"postal_code": "8000",
"city": "Aarhus C",
"country": "DK",
"administrative_area": null
}
},
"delivery_window": null,
"incoterm": null
},
"parties": {
"merchant": {
"reference": null,
"identifier": null,
"uri": null,
"address": {
"address_lines": [
"Eksempelgade 1"
],
"postal_code": "2100",
"city": "Copenhagen",
"country": "DK",
"administrative_area": null
},
"contact": {
"name_lines": [
"Example Shop"
],
"company": "Example Shop",
"email": "shop@example.com",
"phone": "+4587654321"
},
"identifiers": null
},
"customer": {
"reference": null,
"identifier": null,
"uri": null,
"address": {
"address_lines": [
"Eksempelvej 10"
],
"postal_code": "8000",
"city": "Aarhus C",
"country": "DK",
"administrative_area": null
},
"contact": {
"name_lines": [
"Example Customer"
],
"company": null,
"email": "customer@example.com",
"phone": "+4512345678"
},
"identifiers": null
}
},
"parcels": [
{
"reference": "ORDER-1042-1",
"identifier": "shop-parcel-1",
"freetext": null,
"gross_weight": 1500,
"length": 30,
"width": 20,
"height": 15,
"total_net_amount": null,
"tax_amount": null,
"duty_amount": null,
"items": [],
"uuid": "33333333-3333-4333-8333-333333333333",
"tracking_number": "00340434161094015749",
"tracking_url": "https://track.smartsend.io/example",
"tracking": {
"uuid": "66666666-6666-4666-8666-666666666666",
"tracking_number": "00340434161094015749",
"tracking_url": "https://track.smartsend.io/example",
"state": "InfoReceived",
"description": "Shipment information received.",
"estimated_delivery": null,
"delivered_at": null,
"returned_at": null,
"last_updated_at": "2026-09-16T10:00:02Z"
}
}
],
"total_net_amount": null,
"tax_amount": null,
"duty_amount": null,
"shipping_net_amount": null,
"shipping_tax_amount": null,
"content_type": null,
"uuid": "22222222-2222-4222-8222-222222222222",
"state": "booked",
"documents": [
{
"uuid": "44444444-4444-4444-8444-444444444444",
"name": "Shipping label",
"filename": "ORDER-1042-label.pdf",
"types": [
"label"
],
"format": "pdf",
"mime_type": "application/pdf",
"size_bytes": 18342,
"width": {
"value": 210,
"unit": "mm"
},
"height": {
"value": 297,
"unit": "mm"
},
"page_count": 1,
"url": "https://downloads.example.com/documents/label.pdf",
"url_expires_at": "2026-09-16T10:15:02Z",
"description": "Print and attach the label.",
"source": {
"type": "shipment",
"uuid": "22222222-2222-4222-8222-222222222222"
},
"print_status": null,
"created_at": "2026-09-16T10:00:02Z",
"updated_at": "2026-09-16T10:00:02Z"
}
],
"qr_codes": [],
"drop_off_codes": [],
"batch_uuid": null,
"error": null,
"created_at": "2026-09-16T10:00:00Z",
"updated_at": "2026-09-16T10:00:02Z",
"booked_at": "2026-09-16T10:00:02Z",
"cancelled_at": null,
"voided_at": null
}
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
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.
"da-DK, da;q=0.9, en;q=0.8"
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.
1 - 64^[A-Za-z0-9._-]{1,64}$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.
16 - 128^[A-Za-z0-9._-]{16,128}$Path Parameters
Team uuid. All resources are scoped to this team.
Body
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.
Required ISO 4217 currency code for all submitted shipment, parcel and item amounts. Amounts use currency minor units. No fallback to team defaults.
3^[A-Z]{3}$"EUR"
Required common unit for all submitted parcel and item weights. No per-value overrides or fallback to team defaults.
g, kg, lb, oz "g"
Required common unit for all submitted parcel and item dimensions. No per-value overrides or fallback to team defaults.
mm, cm, m, in "cm"
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.
Show child attributes
Show child attributes
Omit merchant to use the appropriate team address. Pickup points belong to delivery.
Show child attributes
Show child attributes
Parcels in stable input order.
1Show child attributes
Show child attributes
Customs invoice number when applicable. Use reference for the public order reference.
"INV-1001121"
Public reference, e.g. order number or SKU, which may be forwarded to the carrier or printed. Not necessarily unique.
"Order-5521"
Private integration reference, e.g. a database ID. Not used for deduplication and not forwarded to carrier labels. Not necessarily unique.
URI linking to the source of this shipment (webshop order URL, deep link, or any URI scheme)
Total goods value in minor units (cents) excluding tax
15920
Total goods tax in minor units (cents)
3980
Total goods duty in minor units (cents)
5572
Shipping cost in minor units (cents) excluding tax
3920
Shipping tax in minor units (cents)
980
Type of contents in the shipment
commercial_goods, returned_goods, gift, commercial_sample, documents, other Response
Shipment booked with all required documents and codes ready.
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.
Show child attributes
Show child attributes
Was this page helpful?