Order preparation
The method is available for models: FBS, Express and DBS.
If you are using an API Key token, one of the accesses in the list is required to call the method
- inventory-and-order-processing — Order processing and inventory
- all-methods — Full account management
It is also suitable for DBS
The request is designed to work with FBS-orders, but you can use it for processing DBS- orders, if it is convenient.
Allows you to perform three operations:
- send information about the distribution of goods by boxes to the Market;
- send the labeling codes for the products to the Market;
- remove an item from the order if it is not in stock.
If you need to fix something in the transmitted data, just repeat the request. — This can be done as many times as you want before the order status is changed. Ready for shipment. ⚠️ If you change the layout after printing and pasting the labels, do not forget to reprint them and paste them again.
How to send information about the distribution of goods
In this request, you need to send the Market a list of boxes and specify which products are in each of them. There are two types of boxes:
-
Containing the entire product. Such a box can contain any number of items of any kind.
-
Containing a part of the product. Such boxes contain one part of one product. For example, one contains an external air conditioner unit, and the other — the indoor unit.
⚠️ One box cannot contain both the whole goods and parts of the goods.
How to transfer marking codes and get their verification status
Labeling of goods in the system «Честный ЗНАК» optional for orders from individuals
For business orders, you still need to send the labeling codes.
If the order contains products subject to labeling, the corresponding unique codes must be provided in the request. What is labeling?
The following types of codes are accepted:
- Codes in the system «Честный ЗНАК» or «ASL BELGISI» (for sellers Market Yandex Go).
- WIN for jewelry.
- RNPT and GTD for imported traceable goods.
For each item in the order that requires labeling, you need to provide a list of codes. — one for each item. For example, if there are two pairs of slippers and one pair of shoes in the order, you will get a list of two codes for the first position and a list of one code for the second.
If the product is traveling in several boxes, the labeling code must be transmitted for each of them.
If you work according to the model FBS, EXPRESS
For orders that contain jewelry or products marked in the system «Честный ЗНАК», conversion to the status READY_TO_SHIP becomes available only when:
- You will transfer it to Yandex.Market УИНы for each piece of jewelry in the order and the codes in the system «Честный ЗНАК» for all products in the order that require this marking.
- All marking codes will be successfully verified. How to get verification statuses
How to remove an item from an order
To remove an item from an order:
- Add to the request
allowRemove: true. - Transfer the distribution to boxes without the item to be removed.
Deletion cannot be undone
This operation is irreversible: the buyer will immediately receive a notification, and the order composition will change.
To delete an entire position, do not pass the corresponding OrderBoxLayoutItemDTO. To reduce the quantity of the product, pass the reduced value in the field fullCount.
You cannot delete or reduce the quantity of an item if it:
- added by special offer;
- amounts to 99% of the order value;
- the only product in the order.
If you cannot ship such an item, cancel the order. To do this, send a request using the method PUT v2/campaigns/{campaignId}/orders/{orderId}/status and send the order status CANCELLED with the reason for cancellation SHOP_FAILED.
You cannot increase the order
You cannot use a query to increase the number of identical items, add new items to an order, or replace one item with another.
Examples
The product fits in a box
This is what the request will look like if they are traveling in the same box:
- three units of the same product that require labeling;
- one unit of another product that does not require labeling.
{
"boxes": [
{
"items": [
{
"id": 123456,
"fullCount": 3,
"instances": [
{
"cis": "01030410947874432155Qbag!\u001d93Zjqw"
},
{
"cis": "010304109478gftJ14545762!\u001dhGt264"
},
{
"cis": "010304109478fRs28323ks23!\u001dhet201"
}
]
},
{
"id": 654321,
"fullCount": 1
}
]
}
]
}
The goods are traveling in different boxes
This is what the request will look like if the product comes in two boxes:
{
"boxes": [
{
"items": [
{
"id": 123456,
"partialCount": {
"current": 1,
"total": 2
},
"instances": [
{
"cis": "01030410947874432155Qbag!\u001d93Zjqw"
}
]
}
]
},
{
"items": [
{
"id": 123456,
"partialCount": {
"current": 2,
"total": 2
},
"instances": [
{
"cis": "01030410947874432155Qbag!\u001d93Zjqw"
}
]
}
]
}
]
}
Identical goods, where everyone travels in several boxes
This is what the request will look like if each of the two identical products travels in two boxes:
{
"boxes": [
{
"items": [
{
"id": 123456,
"partialCount": {
"current": 1,
"total": 2
},
"instances": [
{
"cis": "01030410947874432155Qbag!\u001d93Zjqw"
}
]
}
]
},
{
"items": [
{
"id": 123456,
"partialCount": {
"current": 2,
"total": 2
},
"instances": [
{
"cis": "01030410947874432155Qbag!\u001d93Zjqw"
}
]
}
]
},
{
"items": [
{
"id": 123456,
"partialCount": {
"current": 1,
"total": 2
},
"instances": [
{
"cis": "01030410947874432155Qbag!\u001d93Zjqw"
}
]
}
]
},
{
"items": [
{
"id": 123456,
"partialCount": {
"current": 2,
"total": 2
},
"instances": [
{
"cis": "01030410947874432155Qbag!\u001d93Zjqw"
}
]
}
]
}
]
}
Different products in different boxes
This is what the request will look like if two different products are placed in different boxes:
{
"boxes": [
{
"items": [
{
"id": 123456,
"fullCount": 1
}
]
},
{
"items": [
{
"id": 654321,
"fullCount": 1
}
]
}
]
}
| ⚙️ Limit: 100,000 requests per hour |
|---|
Request
PUT
https://api.partner.market.yandex.ru/v2/campaigns/{campaignId}/orders/{orderId}/boxes
Path parameters
|
Name |
Description |
|
campaignId* |
Type: integer<int64> The store's campaign ID. You can find it using a query GET v2/campaigns or find it in the seller's office on the Market — click on your account icon → Settings and in the menu on the left, select APIs and modules:
⚠️ It does not match the store's identifier (which is indicated in the merchant's account on the Market next to the store's name and in some reports). It is linked to the store one-to-one. Does not apply to advertising campaigns.
Min value: |
|
orderId* |
Type: integer<int64> The order ID. |
Body
application/json
{
"boxes": [
{
"items": [
{
"id": 0,
"fullCount": 0,
"partialCount": {
"current": 0,
"total": 0
},
"instances": [
{
"cis": "string",
"uin": "string",
"rnpt": "string",
"gtd": "string",
"countryCode": "RU"
}
]
}
]
}
],
"allowRemove": false
}
|
Name |
Description |
|
boxes* |
Type: object[] A list of boxes. Min items: |
|
allowRemove |
Type: boolean Pass it on Default: |
Responses
200 OK
In response, you will receive the transmitted layout with the box IDs. — you will need them to request shortcuts.
Body
application/json
{
"status": "OK",
"result": {
"boxes": [
{
"items": [
{
"id": 0,
"fullCount": 0,
"partialCount": {
"current": 0,
"total": 0
},
"instances": [
{
"cis": "string",
"uin": "string",
"rnpt": "string",
"gtd": "string",
"countryCode": "RU"
}
]
}
],
"boxId": 0
}
]
}
}
|
Name |
Description |
||
|
status* |
Type: string The type of response. Possible values:
Enum: |
||
|
result |
Type: object
Distribution of goods by boxes. |
400 Bad Request
The request contains incorrect data. More information about the error
Body
application/json
{
"status": "OK",
"errors": [
{
"code": "string",
"message": "string"
}
]
}
|
Name |
Description |
|
errors |
Type: object[] A list of errors. Min items: |
|
status |
Type: string The type of response. Possible values:
Enum: |
401 Unauthorized
The authorization data is not specified in the request. More information about the error
Body
application/json
{
"status": "OK",
"errors": [
{
"code": "string",
"message": "string"
}
]
}
|
Name |
Description |
|
errors |
Type: object[] A list of errors. Min items: |
|
status |
Type: string The type of response. Possible values:
Enum: |
403 Forbidden
The authorization data is incorrect or access to the resource is prohibited. More information about the error
Body
application/json
{
"status": "OK",
"errors": [
{
"code": "string",
"message": "string"
}
]
}
|
Name |
Description |
|
errors |
Type: object[] A list of errors. Min items: |
|
status |
Type: string The type of response. Possible values:
Enum: |
404 Not Found
The requested resource was not found. More information about the error
Body
application/json
{
"status": "OK",
"errors": [
{
"code": "string",
"message": "string"
}
]
}
|
Name |
Description |
|
errors |
Type: object[] A list of errors. Min items: |
|
status |
Type: string The type of response. Possible values:
Enum: |
420 Method Failure
The resource access limit has been exceeded. More information about the error
Body
application/json
{
"status": "OK",
"errors": [
{
"code": "string",
"message": "string"
}
]
}
|
Name |
Description |
|
errors |
Type: object[] A list of errors. Min items: |
|
status |
Type: string The type of response. Possible values:
Enum: |
500 Internal Server Error
Internal error of the Market. More information about the error
Body
application/json
{
"status": "OK",
"errors": [
{
"code": "string",
"message": "string"
}
]
}
|
Name |
Description |
|
errors |
Type: object[] A list of errors. Min items: |
|
status |
Type: string The type of response. Possible values:
Enum: |
No longer supported, please use an alternative and newer version.
Meaning cis must match the regular expression ^(?=.{1,256}$)\u001D?(\(?01\)?\d{14}\(?21\)?([!-~]{6,8}|[!-~]{13}|[!-~]{20})(\u001D\(?240\)?.{1,30})?\u001D\(?9[1,3]\)?.+)$.
Without the cryptotail — ^(?=[!-~]{1,256}$)(\(?01\)?\d{14}\(?21\)?(.{6,8}|.{13}|.{20}))$.