Products
Create or update an array of 1 to 300 products atomically. If any item fails, none are stored. product.name is required when creating a new product; product.code, product.type, barcodes, unit, description, price, weight, and volume are optional. For a new product, barcode.value, price.value, and the type and value of supplied weight or volume are required. Price currency is optional. Omitted existing data is preserved.
http://localhost:3000/api/v1/products- 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 Products 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 Product identifier from the source system; it does not need to be a UUID. It is unique within the company; the internal Y3M identifier is a UUID v7. Maximum 200 characters. |
product | object | null | Optional | Optional product identity. Name is required here when creating a new product. |
product.code | string | Optional | Optional visible product code or SKU. Maximum 100 characters. |
product.type | string | Optional | Optional external product type. Maximum 100 characters. |
product.name | string | On create | Required when externalId does not match an existing product. When omitted for an existing product, the stored name is used. Maximum 200 characters. |
barcodes | array | Optional | Optional list of up to 20 unique product barcode objects. Each object contains value and may include position; new values are appended, and the first new barcode in the payload becomes the default. |
barcodes[].value | string | Optional | Barcode value, up to 100 characters. Required when a barcode is provided for a new product. |
barcodes[].position | integer | Optional | Optional positive display position. Positions must be unique within the barcode array; omitted positions follow array order. |
description | string | null | Optional | Optional product description. Maximum 2,000 characters. |
unit | "pcs" | Optional | Optional case-sensitive catalog unit. The only allowed value is pcs; new products default to pcs when omitted. |
price | object | null | Optional | Optional base catalog price. |
price.value | decimal string | On create | Required when price is provided for a new catalog item; omitted values preserve the existing price. Non-negative value with up to three decimal places. |
price.currency | "UAH" | "EUR" | "USD" | "PLN" | Optional | Optional price currency. Allowed values: UAH, EUR, USD, PLN. |
weight | object | null | Optional | Optional product weight. An omitted value preserves the existing value; null clears it. |
weight.type | "kg" | On create | Weight unit. Required when weight is provided for a new product. |
weight.value | decimal string | On create | Non-negative product weight in kilograms, required when weight is provided for a new product. |
volume | object | null | Optional | Optional product volume. An omitted value preserves the existing value; null clears it. |
volume.type | "m3" | On create | Volume unit. Required when volume is provided for a new product. |
volume.value | decimal string | On create | Non-negative product volume in cubic metres, required when volume is provided for a new product. |
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 300 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 | BARCODE_IN_USE | A product barcode already belongs to another product. | Send a unique barcode or correct the product externalId. |
409 | PRODUCT_DELETED | A product referenced by externalId is deleted. | Restore the product 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": "PRODUCT-001",
"product": {
"code": "SKU-001",
"type": "Goods",
"name": "Example product"
},
"barcodes": [
{
"value": "4820000000001",
"position": 1
}
],
"description": "Product description",
"unit": "pcs",
"price": {
"value": "8.500",
"currency": "EUR"
},
"weight": {
"type": "kg",
"value": "1.250"
},
"volume": {
"type": "m3",
"value": "0.035"
}
}
]