Delivery Routes API documentation

POST/api/v1/delivery/routes

Method: POST
Content type: application/json
Authentication: Required
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_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Request fields

Required and optional fields accepted in the JSON request body.

Field	Type	Requirement	Description
`number`	string	Required	Unique number used to prevent duplicates.
`route`	object	Required	Route identification.
`route.code`	string	Optional	External route code.
`route.type`	string	Required	Route type or weekday.
`route.name`	string	Required	Route name.
`scheduledDate`	date	Required	Start date in YYYY-MM-DD format.
`endDate`	date	Optional	End date in YYYY-MM-DD format. Defaults to scheduledDate.
`currency`	string	Required	Three-letter uppercase currency code.
`orders`	array	Required	Between 1 and 1,000 delivery orders.
`orders[].position`	integer	Optional	Positive order position. Supplied positions must be unique.
`orders[].customer`	string	Required	Customer name.
`orders[].invoiceNumber`	string	Required	Invoice number.
`orders[].invoiceDate`	date	Required	Invoice date in YYYY-MM-DD format.
`orders[].phones`	string[]	Optional	Customer phone numbers. The array may be empty.
`orders[].city`	string	Required	Delivery city.
`orders[].address`	string	Required	Delivery address.
`orders[].comment`	string \| null	Optional	Delivery comment.
`orders[].productAmount`	decimal string	Optional	Product amount without delivery.
`orders[].deliveryAmount`	decimal string	Optional	Delivery amount.
`orders[].totalAmount`	decimal string	Optional	Total order amount.
`orders[].itemQuantity`	integer	Optional	Non-negative item quantity.
`orders[].placeQuantity`	integer	Optional	Non-negative place quantity.

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.
`403`	`FORBIDDEN`	The API key is valid but does not have access to this module.	Enable the required module for the key or use another key.
`409`	`DUPLICATE_NUMBER`	A payload with the same number has already been received for this module and resource.	Send a new unique number or do not resend the existing payload.
`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 error.details to correct the specified field paths.
`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`	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.

{
  "number": "947",
  "route": {
    "code": "947",
    "type": "Пн",
    "name": "МОЮ Біляєвка"
  },
  "scheduledDate": "2026-10-19",
  "endDate": "2026-10-19",
  "currency": "UAH",
  "orders": [
    {
      "position": 1,
      "customer": "Кобилянський Віталій Валентинович",
      "invoiceNumber": "947/27144",
      "invoiceDate": "2026-10-19",
      "phones": [
        "+380502281669"
      ],
      "city": "Велика Михайлівка",
      "address": "Шкільна вул., 1а",
      "comment": "Біляївка",
      "productAmount": "50.00",
      "deliveryAmount": "3.00",
      "totalAmount": "53.00",
      "itemQuantity": 12,
      "placeQuantity": 2
    },
    {
      "position": 2,
      "customer": "Радіонов Сергій Володимирович",
      "invoiceNumber": "947/28428",
      "invoiceDate": "2026-10-19",
      "phones": [
        "0667603071",
        "+380667603071"
      ],
      "city": "Роздільна",
      "address": "Малиновського вул., 1",
      "comment": null,
      "productAmount": "150.00",
      "deliveryAmount": "9.95",
      "totalAmount": "159.95",
      "itemQuantity": 5,
      "placeQuantity": 1
    }
  ]
}

Delivery routes

Request headers

Request fields

Error responses

Example request