Create or update an order by external id
const url = 'https://example.com/api/v1/integration/orders/sync';const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"externalId":"example","customId":"example","price":1,"planDeliveryPeriod":{"startDate":"2026-04-15T12:00:00Z","endDate":"2026-04-15T12:00:00Z"},"planPickupPeriod":{"startDate":"2026-04-15T12:00:00Z","endDate":"2026-04-15T12:00:00Z"},"addressFrom":{"line":"example","lat":1,"long":1,"details":"example","commentary":"example","domofon":"example","flat":"example","floor":"example","porch":"example"},"addressTo":{"line":"example","lat":1,"long":1,"details":"example","commentary":"example","domofon":"example","flat":"example","floor":"example","porch":"example"},"appType":"example","volume":1,"weight":1,"priority":1,"deliveryPrice":1,"additionalDetails":"example","details":"example","assembled":true,"statusGroup":"example","type":"Delivery","relatedToOrderId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","lines":[{"code":"example","name":"example","productId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","warehouseId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","requiredSkills":["example"],"weight":1,"volume":1,"dimensions":{"length":1,"width":1,"height":1},"priority":1,"requestedQty":1,"unitPrice":1,"role":"Deliver"}],"client":{"name":"example","phone":"example","email":"example"},"assignedDriverId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","assignedVehicleId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/api/v1/integration/orders/sync \ --header 'Content-Type: application/json' \ --data '{ "externalId": "example", "customId": "example", "price": 1, "planDeliveryPeriod": { "startDate": "2026-04-15T12:00:00Z", "endDate": "2026-04-15T12:00:00Z" }, "planPickupPeriod": { "startDate": "2026-04-15T12:00:00Z", "endDate": "2026-04-15T12:00:00Z" }, "addressFrom": { "line": "example", "lat": 1, "long": 1, "details": "example", "commentary": "example", "domofon": "example", "flat": "example", "floor": "example", "porch": "example" }, "addressTo": { "line": "example", "lat": 1, "long": 1, "details": "example", "commentary": "example", "domofon": "example", "flat": "example", "floor": "example", "porch": "example" }, "appType": "example", "volume": 1, "weight": 1, "priority": 1, "deliveryPrice": 1, "additionalDetails": "example", "details": "example", "assembled": true, "statusGroup": "example", "type": "Delivery", "relatedToOrderId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "lines": [ { "code": "example", "name": "example", "productId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "warehouseId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "requiredSkills": [ "example" ], "weight": 1, "volume": 1, "dimensions": { "length": 1, "width": 1, "height": 1 }, "priority": 1, "requestedQty": 1, "unitPrice": 1, "role": "Deliver" } ], "client": { "name": "example", "phone": "example", "email": "example" }, "assignedDriverId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "assignedVehicleId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }'Answers 201 when the external id is new and 200 when an existing order was updated. Re-sending an order that was archived or cancelled brings it back: the outcome is Restored, the order keeps its original id and short id, and its status returns to New.
Authorizations
Заголовок раздела «Authorizations»Request Bodyrequired
Заголовок раздела «Request Bodyrequired»An order as a source system sends it. The external id decides whether this creates a new order or updates the one already carrying that id.
object
The id your system knows this order by. Required, and the key the platform matches on: sending the same id again updates the same order.
Your own reference for the order. Stored and returned unchanged, and available as a filter on the order list.
Price of the goods. Cannot be negative.
The window the order should be delivered in. The end must not be before the start.
object
Start of the window. Stored exactly as sent.
End of the window. Must not be before the start. Stored exactly as sent.
The window the goods should be collected in. The end must not be before the start.
object
Start of the window. Stored exactly as sent.
End of the window. Must not be before the start. Stored exactly as sent.
Where the goods come from. The operative address for a Pickup or a Return.
object
The whole address on one line.
Latitude in WGS 84 degrees. A latitude and a longitude that are both exactly 0 read as “no coordinates”; an order pushed through the API whose addresses all read that way is refused with 400.
Longitude in WGS 84 degrees.
Free-text extra detail about the address.
Free-text comment about the address.
Free-text door-phone (intercom) code for the entrance.
Free-text flat or apartment.
Free-text floor.
Free-text entrance, or porch, of the building.
Where the goods go. The operative address for a Delivery or a Rebox.
object
The whole address on one line.
Latitude in WGS 84 degrees. A latitude and a longitude that are both exactly 0 read as “no coordinates”; an order pushed through the API whose addresses all read that way is refused with 400.
Longitude in WGS 84 degrees.
Free-text extra detail about the address.
Free-text comment about the address.
Free-text door-phone (intercom) code for the entrance.
Free-text flat or apartment.
Free-text floor.
Free-text entrance, or porch, of the building.
Free-form classification from your system. Stored and returned unchanged; the platform does not interpret it.
Volume of the whole order. Leave it out to have the platform derive it from the lines instead.
Weight of the whole order. Leave it out to have the platform derive it from the lines instead.
Relative priority of the order.
What the delivery itself costs, apart from the goods. Stored and returned unchanged.
Free-form notes from your system.
Free-form notes from your system.
Whether the goods are already assembled. Stored and returned unchanged.
Free-form grouping from your system. Stored and returned unchanged; it is not the order’s status.
The order this one is raised against, for a Return or a Rebox.
The OrderLines the order is made of. Defaults to none.
One OrderLine of an order sent in from a source system.
object
Your code for the goods.
Human-readable name of the goods.
Id of the product this line refers to.
Id of the Warehouse the goods are taken from.
Skills a Driver must hold to handle this line. Defaults to none.
Weight of ONE unit, not of the whole line.
Volume of ONE unit, not of the whole line.
Relative priority of the line.
How many units are asked for.
Price of one unit.
Driver this order must go to. Send it together with the vehicle: planning then keeps that pair and only routes the stops. Leave both out to let planning choose.
Vehicle this order must go on, sent together with the Driver.
Responses
Заголовок раздела «Responses»OK
What a single order sync did.
object
Id of the order the external id resolved to.
Created when the external id was new, Updated when an existing active order was changed, Restored when the sync brought an order back that was archived or cancelled. A restored order keeps its original id and short id, and returns to the New status.
Human-readable identifier of the form ORD-XXXXX, unique within the tenant.
Kind of order: Delivery, Pickup, Return or Rebox.
Example
{ "outcome": "Created", "type": "Delivery"}Created
What a single order sync did.
object
Id of the order the external id resolved to.
Created when the external id was new, Updated when an existing active order was changed, Restored when the sync brought an order back that was archived or cancelled. A restored order keeps its original id and short id, and returns to the New status.
Human-readable identifier of the form ORD-XXXXX, unique within the tenant.
Kind of order: Delivery, Pickup, Return or Rebox.
Example
{ "outcome": "Created", "type": "Delivery"}Validation failed
The body of a 400 response, served as application/problem+json. It follows the RFC 9457 problem-details shape: type, title, status and detail are the standard members, and errors is an extension that lists the offending fields.
object
A stable, machine-readable code for the error. Branch on this rather than on the wording of the title or the detail.
A short label for the kind of failure, such as Validation failed.
The HTTP status code of the response, which for this body is 400.
A human-readable explanation of this particular failure, or null.
The fields the request was rejected over, one entry each. Omitted entirely when the failure carries no field-level context, so a 400 can arrive without this member.
One field the request was rejected over.
object
The name of the offending field, spelled as the request body spells it.
A stable, machine-readable code for this field’s failure.
The rejected value. Always present, and null when it was not safe to echo back.
A human-readable explanation of what is wrong with the field.
Set only by the dispatcher application’s manual planning operations — integration endpoints never set it. True when every problem in this refusal is a tenant-policy refusal the operator may override by re-sending the same request with force: true. Omitted otherwise.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": [ { "field": "example", "code": "example", "value": "example", "message": "example" } ], "overridable": true}Missing or invalid credentials
Authenticated, but the role or scope does not allow this
Not found
RFC 9457 problem body returned on every failure. type carries a stable machine-readable error code (see docs/api/error-codes.yaml), title a short human summary, status the HTTP status, detail the specific message.
object
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example"}Conflict
RFC 9457 problem body returned on every failure. type carries a stable machine-readable error code (see docs/api/error-codes.yaml), title a short human summary, status the HTTP status, detail the specific message.
object
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example"}Rate limit exceeded, or an Idempotency-Key request is still in flight; retry after the Retry-After header
RFC 9457 problem body returned on every failure. type carries a stable machine-readable error code (see docs/api/error-codes.yaml), title a short human summary, status the HTTP status, detail the specific message.
object
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example"}Unexpected error
RFC 9457 problem body returned on every failure. type carries a stable machine-readable error code (see docs/api/error-codes.yaml), title a short human summary, status the HTTP status, detail the specific message.
object
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example"}