Warehouse Operations
Atomically create up to 100 Warehouse Operations with caller-controlled external IDs. If any operation fails, none are stored. Each operation is created as CONFIRMED, assigned to every active company location available to the API key, and stored together with its product lines and storage values as historical snapshots. Products must reference active catalogue products visible at those locations. operationType accepts RECEIVING or TRANSFER, while operation.code, operation.type, and operation.name carry the external operation identity. Monetary, discount, package, weight, volume, and product-line values follow the same validation rules as Orders. An externalId already used by a non-deleted Warehouse Operation returns WAREHOUSE_OPERATION_ALREADY_EXISTS; the repeated request does not update the existing Warehouse Operation. Every Warehouse Operation requires at least one product line.
http://localhost:3000/api/v1/warehouse/operations- 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 Warehouse 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 Warehouse Operation returns WAREHOUSE_OPERATION_ALREADY_EXISTS. Maximum 200 characters. |
operation | object | null | Optional | Optional external operation identity. |
operation.code | string | On create | Required when operation is provided on create. |
operation.type | string | Optional | Optional external operation type. |
operation.name | string | Optional | Optional external operation name. |
operationType | "RECEIVING" | "TRANSFER" | On create | System operation type required on create. |
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 operation 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. |
products | array | On create | At least one product line item is required on create. |
products[].externalId | string | On create | Product external identifier required on create. |
products[].position | integer | Optional | Optional line position. |
products[].quantity | object | null | Optional | Optional product quantity. |
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. |
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 | PRODUCT_DELETED | A product referenced by externalId is deleted. | Restore the product in Y3M, then retry the request. |
409 | WAREHOUSE_TASK_ALREADY_EXISTS | A Warehouse task already uses this externalId, including a deleted task. | Use another externalId. |
409 | WAREHOUSE_OPERATION_ALREADY_EXISTS | A non-deleted Warehouse Operation already uses this externalId. | Use another externalId or delete the existing Warehouse Operation before creating a new one. |
409 | WAREHOUSE_UNAVAILABLE | Warehouse is inactive. | Activate Warehouse, 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": "OPERATION-001",
"operation": {
"code": "RCV-001",
"type": "supplier_delivery",
"name": "Receive supplier shipment"
},
"operationType": "RECEIVING",
"dates": {
"invoice": "2026-11-18"
},
"packages": {
"type": "box",
"value": 3
},
"discount": {
"type": "percent",
"value": "5.000"
},
"description": "Receiving note",
"amount": {
"subtotal": "225.830",
"total": "214.540",
"currency": "UAH"
},
"weight": {
"type": "kg",
"value": "17.493"
},
"volume": {
"type": "m3",
"value": "0.079"
},
"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"
}
]
}
]
}
]