Shipments

Create a shipment

Create a shipment and book its label. By default, waits for booking and returns the label as Base64 in data.label. Use wait_for_label=false for asynchronous booking. Check label_status and label_errors even after a 201 response. Requires Idempotency-Key.

post/api/external/v1/shipments

Request

  • Base URL: http://localhost
  • URL: http://localhost/api/external/v1/shipments
  • Auth: HTTP bearer

Query parameters

wait_for_labelboolean

Wait for booking and return the label (default: true). Set false to queue booking and return a pending shipment.

Example:true
label_format'pdf' | 'zpl'

Inline label format. Both formats are Base64-encoded. Defaults to pdf.

Example:pdf

Headers

Idempotency-Keystring required

Request body

external_referencestring required

Your shipment reference, unique within the store.

order_referencestring

Your order reference. This is text, not a link to a fulfillment group.

shipping_method_idstring required

Shipping method (sm_…) or checkout shipping-option (so_…) ID from GET /shipping-methods.

service_point_idstring

Pickup-point ID from search. Required when the method has requires_service_point: true.

metadataobject

Your integration metadata. Do not include secrets.

Example request

{
  "external_reference": "ERP-SHIPMENT-100045",
  "order_reference": "ERP-ORDER-5001",
  "shipping_method_id": "sm_a1b2c3",
  "service_point_id": "sp_xyz789",
  "sender": {
    "name": "architecto",
    "address1": "architecto",
    "address2": "architecto",
    "postal_code": "architecto",
    "city": "architecto",
    "country": "ng",
    "phone": "architecto",
    "email": "zbailey@example.net"
  },
  "recipient": {
    "name": "architecto",
    "address1": "architecto",
    "address2": "architecto",
    "postal_code": "architecto",
    "city": "architecto",
    "country": "ng",
    "phone": "architecto",
    "email": "zbailey@example.net"
  },
  "parcels": [
    []
  ]
}

Response

OR

Example response

{
  "data": {
    "id": "shp_x7Kq9",
    "external_reference": "ERP-SHIPMENT-100045",
    "order_reference": "ERP-ORDER-5001",
    "shipment_status": null,
    "label_status": "created",
    "label_errors": [],
    "shipping_method": {
      "id": "sm_a1b2c3",
      "name": "PostNord Service Point",
      "delivery_type": "pickup_point"
    },
    "carrier": {
      "id": "postnord",
      "name": "PostNord"
    },
    "service_point": {
      "id": "sp_xyz789",
      "name": "PostNord Ombud City"
    },
    "sender": {
      "name": "Merchant Warehouse",
      "address1": "Warehouse Road 10",
      "address2": null,
      "postal_code": "41502",
      "city": "Göteborg",
      "country": "SE",
      "phone": null,
      "email": "warehouse@example.com"
    },
    "recipient": {
      "name": "Anna Andersson",
      "address1": "Drottninggatan 1",
      "address2": null,
      "postal_code": "11151",
      "city": "Stockholm",
      "country": "SE",
      "phone": "+46701234567",
      "email": "anna@example.com"
    },
    "parcels": [
      {
        "weight_grams": 1200,
        "length_cm": 30,
        "width_cm": 20,
        "height_cm": 10
      }
    ],
    "tracking": {
      "number": "PN123456789SE",
      "url": "https://tracking.example/PN123456789SE",
      "status": null,
      "last_event_at": null
    },
    "label": {
      "format": "PDF",
      "encoding": "BASE64",
      "data_base64": "JVBERi0xLjQKJ..."
    },
    "metadata": {
      "source": "erp",
      "warehouse": "gothenburg"
    },
    "links": {
      "self": "/api/external/v1/shipments/shp_x7Kq9",
      "label": "/api/external/v1/shipments/shp_x7Kq9/label",
      "tracking": "/api/external/v1/shipments/shp_x7Kq9/tracking"
    },
    "created_at": "2026-05-27T10:00:00Z",
    "updated_at": "2026-05-27T10:00:00Z"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.