Orders
Create an array of 1 to 100 CONFIRMED Orders atomically. If any order fails, none are stored. Every order requires at least one service* or at least one product*; both arrays cannot be empty or omitted. * At least one of products or services must be provided; one of the two is required. When active Picking is included in the confirmed workflow, every product must have a positive quantity. Orders and workflows are created in the same transaction. An externalId already used by a non-deleted Order returns ORDER_ALREADY_EXISTS; the repeated request does not update the existing Order.
http://localhost:3000/api/v1/orders- 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 Orders 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 identifier; it does not need to be a UUID. A value already used by a non-deleted Order returns ORDER_ALREADY_EXISTS. A value used only by deleted Orders creates a new Order with a new internal Y3M UUID v7. |
order | object | null | Optional | Optional external order identity. |
order.code | string | On create | Required when order is provided on create. |
order.type | string | Optional | Optional external order type. |
order.name | string | Optional | Optional external order name. |
dates | object | null | Optional | Optional document dates. |
dates.invoice | date | On create | Required when dates is provided on create. |
packages | object | null | Optional | Optional package count and type. |
packages.type | "box" | "pallet" | On create | Package type. Required when packages is provided on create. |
packages.value | integer | On create | Non-negative package count. Required when packages is provided on create. |
discount | object | null | Optional | Optional percentage or fixed-amount discount. |
discount.type | "percent" | "amount" | On create | Discount type. Required when discount is provided on create. |
discount.value | decimal string | On create | Non-negative discount value with up to three decimal places. Required when discount is provided on create. |
description | string | null | Optional | Optional order note. |
amount | object | null | Optional | Optional subtotal, total and currency amounts. |
amount.subtotal | decimal string | Optional | Subtotal amount. |
amount.total | decimal string | On create | Required when amount is provided on create. |
amount.currency | "UAH" | "EUR" | "USD" | "PLN" | Optional | Optional amount currency. Allowed values: UAH, EUR, USD, PLN. |
weight | object | null | Optional | Optional weight in kilograms. |
weight.type | "kg" | On create | Weight unit. Required when weight is provided on create. |
weight.value | decimal string | On create | Weight value. Required when weight is provided on create. |
volume | object | null | Optional | Optional volume in cubic metres. |
volume.type | "m3" | On create | Volume unit. Required when volume is provided on create. |
volume.value | decimal string | On create | Volume value. Required when volume is provided on create. |
customer | object | null | Optional | Optional customer reference resolved by externalId. |
customer.externalId | string | On create | Required when customer is provided on create. |
products | array | On create* | * At least one of products or services must be provided on create; one of the two is required. |
products[].externalId | string | On create | Product external identifier required on create. |
products[].position | integer | Optional | Optional line position. |
products[].quantity | object | null | Optional | Required with a positive value for every product when active Picking is included in the confirmed workflow; otherwise optional. |
products[].quantity.value | decimal string | On create | Quantity value required on create when quantity is provided. |
products[].quantity.unit | "pcs" | On create | Quantity unit required on create when quantity is provided. |
products[].price | decimal string | Optional | Optional unit price. |
products[].amount | decimal string | Optional | Optional line amount. |
products[].storage | array | Optional | Optional storage locations. |
products[].storage[].type | "shelf" | "pallet" | On create | Storage type required on create when storage is provided. |
products[].storage[].value | string | On create | Storage identifier required on create when storage is provided. |
services | array | On create* | * At least one of products or services must be provided on create; one of the two is required. |
services[].externalId | string | On create | Service external identifier required on create. |
services[].position | integer | Optional | Optional line position. |
services[].quantity | object | null | Optional | Service quantity. |
services[].quantity.value | decimal string | On create | Quantity value required on create when quantity is provided. |
services[].quantity.unit | "service" | On create | Quantity unit required on create when quantity is provided. |
services[].price | decimal string | Optional | Optional unit price. |
services[].amount | decimal string | Optional | Optional line amount. |
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 array. |
400 | INVALID_PAYLOAD | The JSON body is not an array. | Send a root JSON array containing between 1 and 100 objects. |
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 | CUSTOMER_DELETED | A customer referenced by externalId is deleted. | Restore the customer in Y3M, then retry the request. |
409 | ORDER_ALREADY_EXISTS | A non-deleted Order already uses this externalId. | Use another externalId or delete the existing Order before creating a new one. |
409 | ORDER_WORKFLOW_CANCELED | The Order workflow is canceled. | Restore the Order to CONFIRMED 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 | PRODUCT_DELETED | A product referenced by externalId is deleted. | Restore the product in Y3M, then retry the request. |
409 | SERVICE_DELETED | A service referenced by externalId is deleted. | Restore the service in Y3M, then retry the request. |
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 array in the POST request body.
[
{
"externalId": "ORDER-001",
"order": {
"code": "962",
"type": "Пн",
"name": "МПП Черкаси-Кропивницький"
},
"dates": {
"invoice": "2026-10-26"
},
"packages": {
"type": "box",
"value": 3
},
"discount": {
"type": "percent",
"value": "5.000"
},
"description": "Order note",
"amount": {
"subtotal": "225.830",
"total": "214.540",
"currency": "UAH"
},
"weight": {
"type": "kg",
"value": "17.493"
},
"volume": {
"type": "m3",
"value": "0.079"
},
"customer": {
"externalId": "CUSTOMER-123"
},
"products": [
{
"externalId": "PRODUCT-001",
"position": 1,
"quantity": {
"value": "2.000",
"unit": "pcs"
},
"price": "150.000",
"amount": "300.000",
"storage": [
{
"type": "shelf",
"value": "A-01-02"
}
]
}
],
"services": [
{
"externalId": "SERVICE-001",
"position": 1,
"quantity": {
"value": "1.000",
"unit": "service"
},
"price": "50.000",
"amount": "50.000"
}
]
}
]