Skip to main content
Import the whole catalogue once, keyed on 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

To order that variant, send "product_id": 9597, "combination_id": 41206.

Import the catalogue once

  1. Read GET /api/v1/products?page=1&limit=500. limit is 500 by default, at most 1000.
  2. Upsert each row on product_id. Never insert a second row, and never delete and re-insert.
  3. Read the next page until meta.pagination.has_next is false.
Add 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_after never shows stock. Poll full pages.
  • A product with variants carries available_quantity per variant. in_stock: true can 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

  1. Send the highest updated_at you received, verbatim. Never build it from your own clock: a few seconds of skew loses rows for good.
  2. 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.
  3. URL-encode it: + travels as %2B. A value that is not ISO 8601 answers 422 invalid_parameter.
Every timestamp the API returns carries an explicit offset.

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 from GET /products, answers 404 product_not_found on GET /products/{product_id}, and is refused in an order with 422 product_not_offered.
  1. Read GET /api/v1/products/ids on a schedule, and again whenever meta.offer_changed_at moves. That field is present only when your account has an offer of its own.
  2. Drop what is no longer listed.
  3. Fetch what is new with GET /api/v1/products?product_ids=9597,12402: 1 to 100 positive ids. Anything else answers 422 invalid_parameter.

Troubleshooting

The same sync in six languages: Sync the catalogue.