Synchronizing a catalog from your own site
The item key
The platform tells your items apart by the article number you already use in your own system. The first submission of an article creates a listing, a repeated one updates it. No second identifier is needed.
A batch
Items are submitted as a batch to POST /rest/v1/advertisement/seller/ads/sync. Every request carries an Idempotency-Key header — any value unique to the run: repeating an interrupted request with the same key returns the previous response and does not duplicate listings. While the earlier submission with that key is still running the answer is 409 with the IDEMPOTENCY_REQUEST_IN_FLIGHT marker and a Retry-After header — wait the stated time and repeat with the same key. An interrupted submission does not lock the key for good: once that time passes, a repeat takes the key over. The ceiling on items per batch and on image addresses per item is stated in the operation reference, and a batch above it is rejected whole with SELLER_SYNC_BATCH_TOO_LARGE or SELLER_SYNC_IMAGES_TOO_MANY. The platform fetches images by your links, so a batch takes seconds per item: keep the client timeout to a few minutes.
{
"publish": true,
"items": [
{
"sku": "KR-5T-12",
"title": "Overhead crane 5 t",
"description": "Span 12 m, lifting height 8 m",
"categoryId": "0192f0c0-0000-7000-8000-000000000001",
"offerType": "PRODUCT",
"price": 1850000,
"currency": "RUB",
"quantity": 3,
"attributes": { "loadCapacity": "5", "span": "12" },
"imageUrls": ["https://example.org/img/kr-5t-12.jpg", "https://example.org/img/kr-5t-12-side.jpg"],
"secondImageUrl": "https://example.org/img/kr-5t-12-side.jpg"
}
]
}
The platform fetches the images by the given addresses itself; submitting the same link again does not re-upload the picture. Photos uploaded with the key to the MAIN gallery are named by the item as imageFileIds — they go before the imageUrls addresses. The first image is the card cover, the second card photo in search results is secondImageFileId or secondImageUrl: one of the item images other than the first, in only one of the two fields. An item without a second photo keeps the previous second photo mark. The publish flag sends the created and updated items for publication. The model3dUrl field gives the listing a viewer model in GLB: there is one model, and another address replaces it.
Digital delivery
In a category with payment on the platform an item carries variants: a name, a price and the delivery files — either as fileUrls addresses or as fileIds of already uploaded files. A file is uploaded in two steps — POST /rest/v1/file/seller/upload/initiate and POST /rest/v1/file/seller/upload/complete — under the file upload permission; the initiation names the gallery (gallery) and the category of the item (categoryId), and the platform picks the storage itself. The category the item will land in is returned by POST /rest/v1/advertisement/seller/ads/sync/categories — the body is the same as for a batch, the response is per item: sku and categoryId or the refusal error, and no listings are created; an item the platform already knows stays in its category. A variant marked includes3dModel requires model3dUrl on the item, otherwise publication is rejected with VARIANT_REQUIRES_3D_MODEL.
The response
The response is per item in the order of the request: sku, the listing advertisementId and publicNumber, the created flag or the refusal reason error. A refusal of one item does not cancel the others — read results and resubmit only the rejected ones.
Withdrawing an item
GET /rest/v1/advertisement/seller/ads?sku={article} returns the listing identifier for your own article, and DELETE /rest/v1/advertisement/seller/ads/{id} withdraws it — the listing goes to the archive.
Categories and attributes
The category identifier comes from the category tree, attribute keys and allowed values come from the attributes of a category:
GET /rest/v1/catalog/public/categories
GET /rest/v1/catalog/public/categories/{id}/attributes
GET /rest/v1/catalog/public/categories/{id}/attributes/{attributeKey}/values
The reference is readable without a key as well, and a request with a key counts against its quota. Map your catalog onto the platform categories once and keep the mapping on your side.
Your own shop categories
Instead of categoryId an item can pass its own shop category in the shopCategoryPath field — level names from the root. The item lands in the platform category mapped to that shop category in the “Developers” section — the same mapping applies to files and feeds. A new shop category appears in the mapping list, and an item of an unmapped category is rejected with VALIDATION_ERROR carrying the category path in errorDetails.category; resubmit the item after mapping it.
Did not find the answer to your question?
Create a request