Order Picking API documentation

POST/api/v1/order-picking/orders

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.
`date`	date	Required	Date in YYYY-MM-DD format.
`totalProductCount`	integer	Required	Non-negative total product count.
`subtotalAmount`	decimal string	Optional	Amount before discount.
`discountPercent`	decimal string	Optional	Discount percentage.
`discountAmount`	decimal string	Optional	Discount amount.
`totalAmount`	decimal string	Required	Final document amount.
`currency`	string	Required	Three-letter uppercase currency code.
`packages`	integer	Optional	Non-negative package count.
`weightKg`	decimal string	Optional	Document weight in kilograms.
`volumeM3`	decimal string	Optional	Document volume in cubic metres.
`comment`	string \| null	Optional	Document comment.
`route`	object	Required	Route identification.
`route.code`	string	Required	External route code.
`route.type`	string	Required	Route type or weekday.
`route.name`	string	Required	Route name.
`supplier`	object	Required	Supplier information.
`supplier.name`	string	Required	Supplier name.
`supplier.city`	string	Optional	Supplier city.
`recipient`	object	Required	Recipient information.
`recipient.name`	string	Required	Recipient name.
`recipient.city`	string	Optional	Recipient city.
`destination`	string	Optional	Document destination.
`products`	array	Required	Between 1 and 1,000 products.
`products[].positionNumber`	integer	Optional	Positive product position. Supplied positions must be unique.
`products[].productCode`	string	Required	Product code.
`products[].barcodeNumber`	string	Optional	Product barcode.
`products[].name`	string	Required	Product name.
`products[].description`	string \| null	Optional	Product description.
`products[].quantity`	number	Required	Positive product quantity.
`products[].price`	decimal string	Required	Price per product unit.
`products[].amount`	decimal string	Required	Product line amount.
`products[].storageLocations`	array	Optional	Storage locations. The array may be empty.
`products[].storageLocations[].storageType`	string	Required	shelf, pallet, rack, bin, floor, cold-storage, or other.
`products[].storageLocations[].locationCode`	string	Required	Storage location code.

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": "28906",
  "date": "2026-10-20",
  "totalProductCount": 18,
  "subtotalAmount": "225.83",
  "discountPercent": "5.00",
  "discountAmount": "11.29",
  "totalAmount": "214.54",
  "currency": "UAH",
  "packages": 3,
  "weightKg": "17.493",
  "volumeM3": "0.079",
  "comment": "",
  "route": {
    "code": "962",
    "type": "Вт",
    "name": "МШП Черкаси-Кропивницький"
  },
  "supplier": {
    "name": "O&L Sanitary",
    "city": "Одеса"
  },
  "recipient": {
    "name": "Бабаєв Арсен",
    "city": "Черкаси"
  },
  "destination": "Черкаси",
  "products": [
    {
      "positionNumber": 1,
      "productCode": "PM0008",
      "barcodeNumber": "4820008000019",
      "name": "PLAMIX Kub 001 умивальник White",
      "description": "Матеріал — пластик, без підводки",
      "quantity": 1,
      "storageLocations": [
        {
          "storageType": "shelf",
          "locationCode": "05-11-1-1"
        },
        {
          "storageType": "pallet",
          "locationCode": "PL-02-17"
        },
        {
          "storageType": "rack",
          "locationCode": "RK-03-04"
        },
        {
          "storageType": "bin",
          "locationCode": "BN-012"
        },
        {
          "storageType": "floor",
          "locationCode": "FL-A-07"
        },
        {
          "storageType": "cold-storage",
          "locationCode": "CS-01-05"
        },
        {
          "storageType": "other",
          "locationCode": "OTHER-01"
        }
      ],
      "price": "5.000",
      "amount": "5.00"
    },
    {
      "positionNumber": 2,
      "productCode": "PM0671",
      "barcodeNumber": "4820067100019",
      "name": "PLAMIX KUBUS-001 SET White",
      "description": "Змішувач для умивальника з підводкою, 20 шт/ящ",
      "quantity": 1,
      "storageLocations": [],
      "price": "8.500",
      "amount": "8.50"
    }
  ]
}

Order Picking orders

Request headers

Request fields

Error responses

Example request