Skip to main content
POST
/
team
/
{team}
/
shipments
/
{shipment}
/
booking
Book a shipment
curl --request POST \
  --url https://app.smartsend.io/api/v2/team/{team}/shipments/{shipment}/booking \
  --header 'Authorization: Bearer <token>'
{
  "data": {
    "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "currency": "<string>",
    "weight_unit": "g",
    "dimension_unit": "cm",
    "invoice_number": "<string>",
    "reference": "<string>",
    "identifier": "<string>",
    "uri": "<string>",
    "delivery": {
      "carrier_code": "<string>",
      "carrier_name": "<string>",
      "carrier_logo_url": "<string>",
      "carrier_icon_url": "<string>",
      "service_code": "<string>",
      "service_name": "<string>",
      "is_pickup": true,
      "is_return": true,
      "addons": [
        {
          "code": "<string>",
          "name": "<string>"
        }
      ]
    },
    "parties": {
      "receiver": {
        "reference": "<string>",
        "identifier": "<string>",
        "uri": "<string>",
        "address": {
          "address_lines": [
            "<string>"
          ],
          "postal_code": "<string>",
          "city": "<string>",
          "country": "<string>",
          "administrative_area": "<string>"
        },
        "contact": {
          "name_lines": [
            "<string>"
          ],
          "company": "<string>",
          "email": "jsmith@example.com",
          "phone": "<string>"
        },
        "identifiers": {
          "vat": "<string>",
          "eori": "<string>",
          "gb_eori": "<string>",
          "tax_id": "<string>",
          "voec": "<string>"
        }
      },
      "pickup": {
        "service_point_code": "<string>",
        "company": "<string>",
        "address": {
          "address_lines": [
            "<string>"
          ],
          "postal_code": "<string>",
          "city": "<string>",
          "country": "<string>",
          "administrative_area": "<string>"
        },
        "reference": "<string>",
        "identifier": "<string>",
        "uri": "<string>"
      }
    },
    "parcels": [
      {
        "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "reference": "<string>",
        "identifier": "<string>",
        "tracking_code": "<string>",
        "tracking_url": "<string>",
        "freetext": "<string>",
        "gross_weight": 1,
        "length": 1,
        "width": 1,
        "height": 1,
        "total_net_amount": 123,
        "tax_amount": 123,
        "duty_amount": 123,
        "items": [
          {
            "reference": "<string>",
            "identifier": "<string>",
            "uri": "<string>",
            "image_url": "<string>",
            "sku": "<string>",
            "location": "<string>",
            "name": "<string>",
            "description": "<string>",
            "tariff_code": "<string>",
            "country_of_origin": "<string>",
            "quantity": 1,
            "total_net_amount": 123,
            "tax_amount": 123,
            "duty_amount": 123,
            "net_weight": 1,
            "cost_amount": 123
          }
        ],
        "documents": [
          {
            "url": "<string>"
          }
        ]
      }
    ],
    "total_net_amount": 123,
    "tax_amount": 123,
    "duty_amount": 123,
    "shipping_net_amount": 123,
    "shipping_tax_amount": 123,
    "created_at": "2023-11-07T05:31:56Z",
    "booked_at": "2023-11-07T05:31:56Z"
  }
}

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

Any value passed in this request will be returned in the same header. This can be used to correlate requests between client and server.

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

Optional key that makes a write request idempotent so it can be safely retried. Reusing the key with an identical payload within 24 hours returns the original response without re-executing the operation (with an Idempotency-Replayed: true response header); reusing it with a different payload returns 422, and retrying while the original is still processing returns 409 with a Retry-After header. Use a client-generated, case-sensitive string of 16–128 characters (letters, digits, ., _, -). Deriving it deterministically from the request — for example the order ID combined with a hash of the payload — lets retries reuse the same key without storing it. See https://docs.smartsend.io/api-reference/idempotency.

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

Set to 'respond-async' to request asynchronous processing. When set, the API returns 202 Accepted with an Operation object for polling instead of waiting for completion.

Available options:
respond-async

Path Parameters

​
team
string
required

Team identifier. All resources are scoped to this team.

Minimum string length: 1
Example:

"ad9546c1-393e-49a5-9a72-5cc146c9bec5"

​
shipment
string<uuid>
required

Unique identifier of the shipment to book

Example:

"550e8400-e29b-41d4-a716-446655440000"

Response

Shipment booked successfully

​
data
object
required

A shipment for booking