Method POST/partner
Open a B2B order for a distributor, replayable on the order reference. Requires the dispatch:write scope.
You open a B2B order: the order reference from your ERP or your logistics provider, and the distributor who receives it. Units are then added to it as the order is picked. The whole flow is in the guide Tie each unit to its order.
The full address is https://api.sealtrust.io/v1/partner/dispatch/shipments.
This call can be replayed. The same order_ref returns the same shipment, with
code 200 and created set to false. The same order_ref for another
distributor is refused with 409: we never rewrite where units went.
#
API key in the Authorization header, Bearer format, with the
dispatch:write scope. A key without it gets a 403 whose message names the
missing scope. The plan of the key's brand must include API access, and the
shipment's brand must be on the Compliance + Identity offer.
Authorization: Bearer votre_clef#Rate limit
The same as the other partner routes: one counter per key and one for the sum of your brand's keys, 120 calls per 60-second window by default. Every call that writes takes 1 unit of the key's daily quota, whatever the number of units it carries.
#Request body
application/json. Any unknown field gets the request refused with 422.
| Name | Type | Required | Description |
|---|---|---|---|
order_ref | string | yes | Your order number, 1 to 100 characters. Unique within your brand. |
distributor_code | string | yes | The distributor's code, an active retailer of type "Distributor". |
ship_date | string | no | Ship date, YYYY-MM-DD. |
ship_to_country | string | no | Ship-to country, two-letter ISO code. Absent, the distributor's country. |
brand_code | string | no | With a reseller key, the public code of one of your client brands. Absent, the key's brand. |
The territory the alert checks is the distributor's, never ship_to_country,
which is informative only.
#Example request
curl -i -X POST "https://api.sealtrust.io/v1/partner/dispatch/shipments" \
-H "Authorization: Bearer st_live_0000000000000000000000000000000000000000000000" \
-H "Content-Type: application/json" \
-d '{"order_ref": "SO-2026-1042", "distributor_code": "DIST-DE", "ship_date": "2026-10-09"}'#Example response
HTTP 201 on creation, 200 when the order already existed.
{
"id": 318,
"brand_id": 42,
"order_ref": "SO-2026-1042",
"status": "open",
"ship_date": "2026-10-09",
"ship_to_country": "DE",
"distributor": {
"id": 77,
"code": "DIST-DE",
"name": "Acme Distribution GmbH",
"country": "DE",
"territory_countries": ["DE", "AT"]
},
"units_allocated": 0,
"created_by": "api-key:st_live_000",
"created_at": "2026-10-09T07:12:44.120391+00:00",
"closed_at": null,
"created": true
}#Errors
| Code | Condition | What to do |
|---|---|---|
| 401 | Key missing, malformed or unknown. | Send Authorization: Bearer <your key> with the whole key. |
| 403 | The key lacks the dispatch:write scope. Message Missing required scopes: dispatch:write. | Create a key that carries this scope. |
| 403 | The brand is on the Compliance offer. detail.code is OFFER_EXCLUDES_IDENTITY and detail.feature is dispatch. Nothing is recorded. | Move to the Compliance + Identity offer. Retrying changes nothing. |
| 429 | Rate limit or daily quota reached. | Wait the number of seconds in Retry-After, or midnight UTC for the quota. |
| 404 | No active distributor of your brand has this code. detail.code is distributor_not_found. | Create the distributor in the console, Retailers tab. |
| 409 | This order_ref already exists for another distributor. detail.code is order_ref_other_distributor. | Check the order reference. |
| 422 | The retailer exists but is not of type distributor (retailer_is_not_a_distributor), or the body is invalid: a control character, or an order_ref starting with =, +, - or @, which a spreadsheet would run as a formula. | Change its type in the console, or fix the body. |
Was this page helpful?
Your answer opens a pre-filled email in your mail app, addressed to contact@sealtrust.io. You read it over before sending it.