product_id and combination_id. Then run a few scheduled jobs: none of them replaces the daily full price refresh. You need the catalog:read scope.
What to store
"product_id": 9597, "combination_id": 41206.
Import the catalogue once
- Read
GET /api/v1/products?page=1&limit=500.limitis 500 by default, at most 1000. - Upsert each row on
product_id. Never insert a second row, and never delete and re-insert. - Read the next
pageuntilmeta.pagination.has_nextisfalse.
include=description on this first import only, for description and description_short. On routine polls it wastes your budget. An unknown include answers 422.
Keep it fresh
Suggested starting points; tune them, but never drop the full price refresh.
Request limits shows how this fits your daily ceiling.
Stock
- A sale or a restock does not edit the product, so
updated_afternever shows stock. Poll full pages. - A product with variants carries
available_quantityper variant.in_stock: truecan hide a variant at zero, so check the variant. - Products at zero stay in the feed with
in_stock: false. - Reading reserves nothing. Stock is checked live when the order is created; one short line refuses the whole order with
422 insufficient_stock(details.index,requested,available).
Status
GET /products returns active and inactive products by default (status=all). An inactive product cannot be ordered: 422 product_not_orderable refuses the whole order.
Never treat a product missing from a
status=active read as deleted: it was deactivated, and products come back.
The updated_after cursor
- Send the highest
updated_atyou received, verbatim. Never build it from your own clock: a few seconds of skew loses rows for good. - Always include an explicit offset, for example
2026-07-01T09:15:00+03:00. Without one it is read in Mart’s server time zone, not UTC. - URL-encode it:
+travels as%2B. A value that is not ISO 8601 answers422 invalid_parameter.
Keep only what you are offered
You may be offered all of the catalogue or only part of it. A product you are not offered is absent fromGET /products, answers 404 product_not_found on GET /products/{product_id}, and is refused in an order with 422 product_not_offered.
- Read
GET /api/v1/products/idson a schedule, and again whenevermeta.offer_changed_atmoves. That field is present only when your account has an offer of its own. - Drop what is no longer listed.
- Fetch what is new with
GET /api/v1/products?product_ids=9597,12402: 1 to 100 positive ids. Anything else answers422 invalid_parameter.
Troubleshooting
The same sync in six languages: Sync the catalogue.
