Custody & shipping

Called with brand account keys. A key only sees its own account's data. Every example uses the same sample brand, order and item, so you can follow one item from call to call.

Base URL http://62.169.23.239:8001/api/v1Auth Bearer token5 endpoints

Endpoints

GET/brands/qr-wizard/orders/{order_id}/destinationsList order destinations
GET/brands/qr-wizard/orders/{order_id}/warehouse-destinationsList your warehouses
POST/brands/production-orders/{order_id}/shipmentsSend a shipping notice
GET/brands/hierarchyList boxes, pallets and containers
GET/brands/hierarchy/{token_id}Retrieve a packing chain

List order destinations#

GET/brands/qr-wizard/orders/{order_id}/destinations

Requires scope custody:read

Get the current logistics destinations for an order (step-4 view).

Parameters

order_idstringpathRequired
Skannit's id for the production order. Use it in every /production-orders/{order_id} and QR call.

Returns

HTTP 200

order_idstringRequired
Skannit's id for the production order. Use it in every /production-orders/{order_id} and QR call.
qr_batch_idstringRequired
The QR batch created for this order — one per production order.
destinationsarray of objects
+Show 8 child attributesHide child attributes
- idstringRequired
- namestringRequired
- citystring | null
- countrystringRequired
- arrival_datestring | null
- prioritystring
  One oflowstandardurgent
  Defaults to standard
- box_idsarray of strings
  Ids of the boxes this call acts on.
- instructionsstring
  Defaults to

GET /brands/qr-wizard/orders/{order_id}/destinations

curl

curl http://62.169.23.239:8001/api/v1/brands/qr-wizard/orders/ord_8c2f4e1a9b7d3c60/destinations \
  -H "Authorization: Bearer $SKANNIT_TOKEN"

200Response

json

{
  "order_id": "ord_8c2f4e1a9b7d3c60",
  "qr_batch_id": "qb_3e9a1c7f2b40",
  "destinations": [
    "in_store"
  ]
}

List your warehouses#

GET/brands/qr-wizard/orders/{order_id}/warehouse-destinations

Requires scope custody:read

Get the brand's registered warehouse destinations for the logistics allocation picker.

Parameters

order_idstringpathRequired
Skannit's id for the production order. Use it in every /production-orders/{order_id} and QR call.

Returns

HTTP 200

order_idstringRequired
Skannit's id for the production order. Use it in every /production-orders/{order_id} and QR call.
destinationsarray of objects
+Show 8 child attributesHide child attributes
- idstringRequired
- namestringRequired
- address_linestring | null
- citystringRequired
- state_provincestring | null
- countrystringRequired
- postal_codestring | null
- is_primaryboolean
  Defaults to false

GET /brands/qr-wizard/orders/{order_id}/warehouse-destinations

curl

curl http://62.169.23.239:8001/api/v1/brands/qr-wizard/orders/ord_8c2f4e1a9b7d3c60/warehouse-destinations \
  -H "Authorization: Bearer $SKANNIT_TOKEN"

200Response

json

{
  "order_id": "ord_8c2f4e1a9b7d3c60",
  "destinations": [
    "in_store"
  ]
}

Send a shipping notice#

POST/brands/production-orders/{order_id}/shipments

Requires scope shipments:write

For brands that book their own carrier or 3PL (e.g. through their ERP): tell Skannit which sealed boxes left the factory, with whom, and the tracking reference. Skannit links the carrier's tracking; the warehouse's or shop's scan on arrival is the proof of delivery and moves custody.

Parameters

order_idstringpathRequired
Skannit's id for the production order. Use it in every /production-orders/{order_id} and QR call.

Request body

box_idsarray of strings
Sealed box ids to ship. Empty = every sealed box of the order not already on a shipment.
ship_to_namestringRequired
Receiving warehouse or shop name
ship_to_detailstring | null
Address or dock
retail_idstring | null
Receiving shop account, if known
carrierobjectRequired
Carrier name, for example PostNL or DHL.
+Show 3 child attributesHide child attributes
- namestringRequired
  Carrier or 3PL, e.g. DHL Express, Maersk, a local courier
- tracking_numberstringRequired
  Consignment / waybill / tracking reference
- tracking_urlstring | null
  Carrier's public tracking page for live location
expected_deliverydate | null
Date the goods should leave the factory.
transport_modestring
One oflocalinternational
Defaults to local
notesstring | null

Returns

HTTP 201

dispatch_idstringRequired
The shipment to a shop.
order_idstringRequired
Skannit's id for the production order. Use it in every /production-orders/{order_id} and QR call.
order_display_idstringRequired
Order number formatted for display (#PO-YYYY-XXXX).
brand_namestring | null
statusstringRequired
Current state of the object. See the allowed values.
One ofdraftassignedin_transitdeliveredcancelled
transport_modestring
One oflocalinternational
Defaults to local
estimated_deliverydate | null
eta_labelstring | null
is_delayedboolean
Defaults to false
journey_progress_percentinteger
Defaults to 0
journey_progress_labelstring
Defaults to
conversation_idstring | null
origin_station_namestring | null
origin_station_detailstring | null
destination_hub_namestring | null
destination_hub_detailstring | null
origin_gps_latnumber | null
Fixed endpoints, so the journey map can plot where the shipment runs between rather than only the legs the driver pinned.
origin_gps_lngnumber | null
destination_gps_latnumber | null
destination_gps_lngnumber | null
retail_idstring | null
The shop (retail account) id.
retail_namestring | null
dispatch_notesstring | null
carrier_typestringRequired
One ofskannit_riderexternal_carrierbrand_fleet
carrier_providerstring | null
One ofdhlglspostnlother
carrier_tracking_numberstring | null
carrier_namestring | null
carrier_tracking_urlstring | null
transporter_idstring | null
transporter_namestring | null
driver_namestring | null
vehicle_platestring | null
driver_contactstring | null
total_boxesinteger
Defaults to 0
total_quantityinteger
Defaults to 0
total_weight_kgstring | null
itemsarray of objects
The objects on this page.
+Show 2 child attributesHide child attributes
- product_namestringRequired
- quantityintegerRequired
  Number of units.
boxesarray of objects
+Show 7 child attributesHide child attributes
- box_idstringRequired
  Id printed on the box label. Scanning the box resolves to this id.
- box_labelstringRequired
- unit_countintegerRequired
- unit_tokensarray of strings
  Tokens of the items involved.
- statusstringRequired
  Current state of the object. See the allowed values.
  One ofnormalflaggeddelayedin_transitdelivered
- last_locationstring | null
- last_location_attimestamp | null
milestonesarray of objects
+Show 23 child attributesHide child attributes
- milestone_idstringRequired
- event_typestringRequired
- titlestringRequired
- detailstring | null
- occurred_attimestamp | null
  Null until the leg is reached — arrival time.
- is_currentboolean
  Defaults to false
- statusstring
  Current state of the object. See the allowed values.
  One ofpendingplannedin_transitreachedskipped
  Defaults to reached
- sequence_positioninteger | null
- modestring | null
  One ofroadseaairrailother
- location_namestring | null
- planned_attimestamp | null
- gps_latnumber | null
- gps_lngnumber | null
- departed_attimestamp | null
  Departure side of the leg — null until the driver taps Depart.
- departed_gps_latnumber | null
- departed_gps_lngnumber | null
- place_namestring | null
  Human-readable places, resolved on-device at capture time. The UI shows these instead of coordinates.
- departed_place_namestring | null
- transporter_idstring | null
- transporter_namestring | null
- estimated_arrival_attimestamp | null
  Projection from the driver's own observed speed across completed legs. Null until at least one leg has been completed — before that there is no measured speed and any figure would be invented.
- is_delayedboolean
  Server-computed so two clients can't disagree; the device clock belongs to the driver and is not trustworthy for this.
  Defaults to false
- delay_minutesinteger | null
  Signed minutes late (positive) or early (negative) vs planned_at.
alertobject | null
+Show 5 child attributesHide child attributes
- titlestringRequired
- detailstringRequired
- severitystring
  One ofcriticalwarninginfo
  Defaults to warning
- acknowledgedboolean
  Defaults to false
- route_deviation_kmnumber | null
dispatched_attimestamp | null
picked_up_attimestamp | null
delivered_attimestamp | null
When the parcel was reported delivered — the moment ownership moved.
pod_photo_urlstring | null
created_attimestampRequired
When the object was created (ISO 8601, UTC).
updated_attimestampRequired
When the object last changed (ISO 8601, UTC).
last_updated_labelstring | null
repair_request_idinteger | null
Set on a repair leg (consumer <-> repair shop); the transporter may decline it before pickup.
repair_legstring | null
logistics_planobject | null
+Show 2 child attributesHide child attributes
- boxesarray of objects
  +Show 6 child attributesHide child attributes
  - idstringRequired
  - modestringRequired
    One ofsamemixed
  - capacityintegerRequired
  - regionstring | null
  - linesarray of objectsRequired
    Line items, one per variant.
    +Show 5 child attributesHide child attributes
    colorstringRequired
    Colour name, exactly as on the product's variants.
    sizestringRequired
    Size name, exactly as on the product's variants.
    batch_skustring | null
    SKU printed on the label for this variant in this batch.
    quantityintegerRequired
    Number of units.
    volume_lstring | null
    Packaged volume of one unit, in litres. Used to size boxes.
  - created_atstring | null
    When the object was created (ISO 8601, UTC).
- destinationsarray of objects
  +Show 8 child attributesHide child attributes
  - idstringRequired
  - namestringRequired
  - citystring | null
  - countrystringRequired
  - arrival_datestring | null
  - prioritystring
    One oflowstandardurgent
    Defaults to standard
  - box_idsarray of strings
    Ids of the boxes this call acts on.
  - instructionsstring
    Defaults to
custody_tx_queuedinteger | null
Number of custody-transfer chain transactions successfully queued for this status change (factory->transporter on take-custody, transporter->retail on delivery). Null when the action taken didn't trigger a custody transfer (e.g. plain detail fetch).

POST /brands/production-orders/{order_id}/shipments

curl

curl -X POST http://62.169.23.239:8001/api/v1/brands/production-orders/ord_8c2f4e1a9b7d3c60/shipments \
  -H "Authorization: Bearer $SKANNIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ship_to_name": "Ship to",
    "retail_id": "4974bf7c-8314-5bb9-9f74-8c1497523eb5",
    "carrier": "PostNL",
    "notes": "Received at dock 3"
  }'

201Response

json

{
  "dispatch_id": "b42d4ac7-4d7d-544e-99d3-941dad44d03a",
  "order_id": "ord_8c2f4e1a9b7d3c60",
  "order_display_id": "#PO-2026-7F3A",
  "brand_name": "Northwind Apparel",
  "status": "draft",
  "transport_mode": "local",
  "estimated_delivery": "2026-11-20",
  "eta_label": "Arrives Sat 11 Oct",
  "is_delayed": false,
  "journey_progress_percent": 72,
  "journey_progress_label": "",
  "conversation_id": "14b1be4a-c85b-528b-bb05-270ec6fea314",
  "origin_station_name": "Rotterdam DC",
  "origin_station_detail": "Waalhaven 12, Rotterdam",
  "destination_hub_name": "Northwind Amsterdam",
  "destination_hub_detail": "Kalverstraat 1, Amsterdam",
  "origin_gps_lat": 51.9244,
  "origin_gps_lng": 4.4777,
  "destination_gps_lat": 51.9244,
  "destination_gps_lng": 4.4777,
  "retail_id": "4974bf7c-8314-5bb9-9f74-8c1497523eb5",
  "retail_name": "Northwind Amsterdam",
  "dispatch_notes": "Deliver before 10:00",
  "carrier_type": "skannit_rider",
  "carrier_provider": "PostNL",
  "carrier_tracking_number": "3SNWD1234567890",
  "carrier_name": "Carrier",
  "carrier_tracking_url": "https://files.skannit.example/carrier_tracking.png",
  "transporter_id": "f74f2d3e-d02f-58f6-b03b-795142c1e5d9",
  "transporter_name": "FastFreight BV",
  "driver_name": "Jan de Vries",
  "vehicle_plate": "VX-123-B",
  "driver_contact": "+31687654321",
  "total_boxes": 24,
  "total_quantity": 24,
  "total_weight_kg": 11.6,
  "items": [
    {
      "product_name": "Trail Tee",
      "quantity": 1
    }
  ],
  "boxes": [
    {
      "box_id": "BOX-F4E1A9-0003",
      "box_label": "Box",
      "unit_count": 24,
      "unit_tokens": [
        "Qm7xK2pL9vR4tY8wZ1nB3c"
      ],
      "status": "normal",
      "last_location": "A15 near Rotterdam",
      "last_location_at": null
    }
  ],
  "milestones": [
    {
      "milestone_id": "9e787ca7-0de0-5952-bc10-0063d6ab12de",
      "event_type": "picked_up",
      "title": "Delayed at depot",
      "detail": "Box BOX-F4E1A9-0003 manifest says 48 units",
      "occurred_at": null,
      "is_current": false,
      "status": "pending",
      "sequence_position": 1,
      "mode": "road",
      "location_name": "Rotterdam DC",
      "planned_at": null,
      "gps_lat": 51.9244,
      "gps_lng": 4.4777,
      "departed_at": null,
      "departed_gps_lat": 51.9244,
      "departed_gps_lng": 4.4777,
      "place_name": "Rotterdam",
      "departed_place_name": "Departed place",
      "transporter_id": "f74f2d3e-d02f-58f6-b03b-795142c1e5d9",
      "transporter_name": "FastFreight BV",
      "estimated_arrival_at": null,
      "is_delayed": false,
      "delay_minutes": 1
    }
  ],
  "alert": {
    "title": "Delayed at depot",
    "detail": "Box BOX-F4E1A9-0003 manifest says 48 units",
    "severity": "critical",
    "acknowledged": false,
    "route_deviation_km": 1
  },
  "dispatched_at": null,
  "picked_up_at": null,
  "delivered_at": null,
  "pod_photo_url": "https://files.skannit.example/pod_photo.png",
  "created_at": "2026-10-09T09:30:00Z",
  "updated_at": "2026-10-09T09:30:00Z",
  "last_updated_label": "2 minutes ago",
  "repair_request_id": 1,
  "repair_leg": "repair leg",
  "logistics_plan": {
    "boxes": [
      {
        "id": "SKN-CRT-00402-9A1C3E7F",
        "mode": "same",
        "capacity": 1,
        "region": "EU",
        "lines": [
          {
            "color": "White",
            "size": "M",
            "batch_sku": "TT-100-WHT-M",
            "quantity": 1,
            "volume_l": 0.5
          }
        ],
        "created_at": "2026-10-09T09:30:00Z"
      }
    ],
    "destinations": [
      "in_store"
    ]
  },
  "custody_tx_queued": 1
}

List boxes, pallets and containers#

GET/brands/hierarchy

Requires scope custody:read

List hierarchy nodes belonging to the authenticated brand.

Parameters

node_typestringquery
Filter by ITEM | BOX | PALLET | CONTAINER
limitintegerquery
Defaults to 50
offsetintegerquery
Defaults to 0

Returns

HTTP 200

token_idintegerRequired
The item's on-chain token id.
node_typestringRequired
One ofITEMBOXPALLETCONTAINER
parent_token_idinteger | nullRequired
child_token_idsarray of integersRequired
brand_idstring | nullRequired
The brand that owns the product.
chain_statusstringRequired
Where the item's on-chain record is: minted, activated, in_transit, at_retail, with_consumer, recalled, stolen, recycled.
tx_idstring | nullRequired
on_chain_tx_hashstring | nullRequired
created_atstringRequired
When the object was created (ISO 8601, UTC).
confirmed_atstring | nullRequired
unpacked_atstring | nullRequired
metaobject | nullRequired

GET /brands/hierarchy

curl

curl http://62.169.23.239:8001/api/v1/brands/hierarchy \
  -H "Authorization: Bearer $SKANNIT_TOKEN"

200Response

json

[
  {
    "token_id": 41207,
    "node_type": "ITEM",
    "parent_token_id": 51001,
    "child_token_ids": [
      1
    ],
    "brand_id": "8ea3462c-426c-5cc1-84d7-db99868bca1c",
    "chain_status": "minted",
    "tx_id": "c5817760-f02d-5c02-8d6f-6fe6af3412d4",
    "on_chain_tx_hash": "0x9f2c4e1a7b3d5c8e0f6a2b4c6d8e0f1a3b5c7d9e1f2a4b6c8d0e2f4a6b8c0d2e",
    "created_at": "2026-10-09T09:30:00Z",
    "confirmed_at": null,
    "unpacked_at": null,
    "meta": {}
  }
]

Retrieve a packing chain#

GET/brands/hierarchy/{token_id}

Requires scope custody:read

Fetch a hierarchy node by its on-chain token ID.

Parameters

token_idintegerpathRequired
The item's on-chain token id.

Returns

HTTP 200

token_idintegerRequired
The item's on-chain token id.
node_typestringRequired
One ofITEMBOXPALLETCONTAINER
parent_token_idinteger | nullRequired
child_token_idsarray of integersRequired
brand_idstring | nullRequired
The brand that owns the product.
chain_statusstringRequired
Where the item's on-chain record is: minted, activated, in_transit, at_retail, with_consumer, recalled, stolen, recycled.
tx_idstring | nullRequired
on_chain_tx_hashstring | nullRequired
created_atstringRequired
When the object was created (ISO 8601, UTC).
confirmed_atstring | nullRequired
unpacked_atstring | nullRequired
metaobject | nullRequired

GET /brands/hierarchy/{token_id}

curl

curl http://62.169.23.239:8001/api/v1/brands/hierarchy/41207 \
  -H "Authorization: Bearer $SKANNIT_TOKEN"

200Response

json

{
  "token_id": 41207,
  "node_type": "ITEM",
  "parent_token_id": 51001,
  "child_token_ids": [
    1
  ],
  "brand_id": "8ea3462c-426c-5cc1-84d7-db99868bca1c",
  "chain_status": "minted",
  "tx_id": "c5817760-f02d-5c02-8d6f-6fe6af3412d4",
  "on_chain_tx_hash": "0x9f2c4e1a7b3d5c8e0f6a2b4c6d8e0f1a3b5c7d9e1f2a4b6c8d0e2f4a6b8c0d2e",
  "created_at": "2026-10-09T09:30:00Z",
  "confirmed_at": null,
  "unpacked_at": null,
  "meta": {}
}

NextDeclarations & certificates→