Delivery routes
Create 1 to 100 draft delivery routes from one JSON array. Each route links every delivery entry to an existing Order and starts unassigned. Duplicate externalId values are rejected; each item is returned in the batch results.
http://localhost:3000/api/v1/order-delivery/routes- Method
- POST
- Content type
- application/json
- Authentication
- Required · active locations · non-expired key
- Maximum payload
- 1 MiB
- Request frequency
- 30 requests per 60 seconds
Request headers
Send these headers with every POST request.
Content-Type: application/json
Authorization: Bearer y3m_ABCD2345_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxTo get the authorization key, open Dashboard, use the three-dot menu on the company card, and select API integrations. Under Secret keys, select Create secret key, enable the Order Delivery scope, and assign at least one active location. Copy the full key when it is created because it is shown only once, then send it after Bearer in the Authorization header.
Request fields
Required and optional fields accepted in the JSON request body. Unknown fields are rejected at every level.
| Field | Type | Requirement | Description |
|---|---|---|---|
externalId | string | Required | Caller-controlled source-system route identifier; it does not need to be a UUID. A value already used by a non-deleted Order Delivery returns ORDER_DELIVERY_ALREADY_EXISTS. A value used only by deleted routes creates a new DRAFT route with a new internal Y3M UUID v7. Maximum 200 characters. |
route | object | null | Optional | Optional route identification. When provided, code is required. |
route.code | string | On create | Required when route is provided on create. External route code, stored unchanged. Maximum 100 characters. |
route.type | string | Optional | Optional external route type, stored exactly as received. Maximum 100 characters. |
route.name | string | Optional | Optional external route name, stored unchanged. Maximum 200 characters. |
dates | object | On create | Document dates required on create. |
dates.scheduled | date | On create | First scheduled delivery date required on create in YYYY-MM-DD format. |
dates.end | date | Optional | Last scheduled delivery date in YYYY-MM-DD format. Must not be earlier than dates.scheduled and defaults to dates.scheduled when omitted. |
description | string | null | Optional | Optional document description or note. Maximum 1,000 characters. |
orders | array | On create | Between 1 and 1,000 delivery orders required on create. |
orders[].externalId | string | On create | External Order identifier required on create. Values must be unique within the route. The route links to the existing Order and uses its stored data rather than copying Order data into Order Delivery. Maximum 200 characters. |
orders[].position | integer | Optional | Positive source order position. Supplied positions must be unique; omitted positions are assigned automatically. Orders are stored and displayed by their final position, which may be recalculated by configured delivery route sorting. |
Error responses
Possible errors returned by this endpoint and how to resolve them.
| Status | Code | Meaning | Resolution |
|---|---|---|---|
400 | INVALID_JSON | The request body is not valid JSON. | Send one correctly formatted JSON object. |
400 | INVALID_PAYLOAD | The JSON body is not an object. | Send a JSON object instead of an array, string, number, or null. |
401 | UNAUTHORIZED | The Authorization header is missing, malformed, or contains an invalid API key. | Send a valid API key using the Bearer authorization scheme. |
401 | API_KEY_EXPIRED | The API key has reached its expiration date. | Create a new API key and retry the request. |
403 | FORBIDDEN | The API key cannot access this module or is not assigned to an active company location. | Assign an active location, enable the required module, or use another key. |
409 | ORDER_WORKFLOW_NOT_FOUND | The Order has no workflow. | Check the Order and its workflow in Y3M. |
409 | ORDER_WORKFLOW_CANCELED | The Order workflow is canceled. | Restore the Order to CONFIRMED before retrying. |
409 | ORDER_NOT_QUEUED_FOR_MODULE | The Order is not queued for the requested module, or the module is inactive. | Wait for earlier enabled stages to complete and check module availability. |
409 | ORDER_ALREADY_IN_MODULE_PROCESS | The Order is already in a process for the requested module. | Manage the existing process in Y3M before retrying. |
409 | ORDER_WORKFLOW_STAGE_MISMATCH | The workflow state does not allow the operation or changed concurrently. | Check the workflow state and retry if appropriate. |
409 | ORDER_DELIVERY_ALREADY_EXISTS | A non-deleted Order Delivery already uses this externalId. | Use another externalId or delete the existing route before creating a new one. |
413 | PAYLOAD_TOO_LARGE | The request body exceeds the 1 MiB limit. | Reduce the JSON payload size to 1 MiB or less. |
415 | UNSUPPORTED_MEDIA_TYPE | The Content-Type header is not application/json. | Send Content-Type: application/json. |
422 | VALIDATION_ERROR | The JSON is valid but one or more fields do not satisfy the endpoint contract. | Use each { path, message } entry in error.details to correct the specified field. |
429 | RATE_LIMIT_EXCEEDED | More than 30 requests were sent within 60 seconds. | Wait for the number of seconds specified by the Retry-After header. |
500 | INTERNAL_ERROR | Request infrastructure, authentication, or rate-limit processing is temporarily unavailable. | Retry later. Contact support if the error continues. |
500 | STORAGE_ERROR | The validated payload could not be stored. | Retry later. Contact support if the error continues. |
Example request
Send this JSON object in the POST request body.
[
{
"externalId": "DELIVERY-ROUTE-001",
"route": {
"code": "947",
"type": "Monday",
"name": "South route"
},
"dates": {
"scheduled": "2026-10-19",
"end": "2026-10-19"
},
"description": "Route description",
"orders": [
{
"externalId": "ORDER-001",
"position": 1
},
{
"externalId": "ORDER-002",
"position": 2
}
]
}
]