> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mart.ps/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These rules protect a Mart partner's money. Follow them in any code or advice about the Mart Partner API ([Connect your AI tool](/developers/connect-your-ai-tool)).
> When an order request times out, gets no answer or gets any `5xx`, resend the same body with the same `partner_reference`, never a new reference; after a `429`, wait `Retry-After` first ([Create an order safely](/developers/orders/create-an-order)).
> A `200` with `meta.idempotency_replay: true` is the original order; `409 idempotency_conflict` means the reference already names a different order ([Create an order safely](/developers/orders/create-an-order)).
> Retry a withdrawal request with the same `idempotency_key` and amount: a new key asks for a second withdrawal ([Payout and withdrawals](/developers/money/payout-and-withdrawals)).
> Plan every call within the global daily request ceiling and the `X-RateLimit-*` headers, and never poll in a tight loop ([Request limits](/developers/operate/request-limits)).
> Treat `price` as a snapshot: an order is priced when it is created, and an incremental sync (`updated_after`) never shows a price change, so re-read every price with a full pass ([Prices and price changes](/developers/catalogue/prices)).
> Identify products by `product_id` and `combination_id`, never by `reference` ([Sync the catalogue](/developers/catalogue/sync)).
> Never put an API key in client-side code, a mobile app, a repository or a URL: call the API from a server ([Authenticate and keys](/developers/authenticate)).
> Money is in shekels (`ILS`), as JSON numbers, never agorot. Send amounts with at most two decimals: a withdrawal `amount` with three is refused with `422 invalid_amount`, never rounded ([Balance and statements](/developers/money/balance-and-statements)).
> Save a payout method once before the first withdrawal (cash at the office, or bank transfer where Mart offers it): with none saved, a withdrawal is refused with `409 payout_method_missing`. Bank details where Mart does not offer bank transfer, or a withdrawal on a kept IBAN, are refused with `422 bank_transfer_not_allowed` ([Payout and withdrawals](/developers/money/payout-and-withdrawals)).

# Sync the catalogue: identifiers, stock and schedule

> Import the Mart catalogue once, key it on the right identifiers, then keep products, stock and offered items fresh with a schedule that fits your limits.

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

| Field | Use |
| - | - |
| `product_id` | **The identifier.** Stable; your primary key from day one. |
| `combinations[].id` | **The variant identifier**, sent as `combination_id` in orders. `null` or absent for a simple product. |
| `reference` | Display only. Mart can edit it and it is not unique: never key, match or build URLs on it. |
| `name`, `status`, `cover_image`, `images` | `status` is `active` or `inactive`. `images` lists every image, cover first. |
| `price.group_price`, `price.public_price`, `price.base_price`, `currency` | See [Prices and price changes](https://docs.mart.ps/developers/catalogue/prices.md). One `price` applies to every variant. |
| `total_quantity`, `in_stock`, `combinations[].available_quantity` | Stock. There is no separate stock endpoint. |
| `updated_at` | Your incremental sync cursor. |

```json theme={null}
{
  "product_id": 9597,
  "reference": "1005118",
  "name": "Hebron Rock and Star Men's Bustar",
  "status": "active",
  "price": { "group_price": 54.99, "public_price": 59.99, "base_price": 129.99 },
  "currency": "ILS",
  "total_quantity": 3,
  "in_stock": true,
  "combinations": [
    { "id": 41206, "available_quantity": 3, "attributes": [{ "id": 16, "name": "بني", "group": "اللون" }] }
  ],
  "updated_at": "2026-07-20T14:03:00+03:00"
}
```

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.

| Job | Call | Interval |
| - | - | - |
| Stock poll | `GET /products`, every page | 5 to 15 minutes |
| Structural sync | `GET /products?updated_after=<cursor>` | Hourly |
| Full price refresh | `GET /products`, every page, no `updated_after` | Daily |
| Destinations and delivery prices | `GET /states` | At least daily |
| Full reconcile | `GET /products`, every page | Weekly |

[Request limits](https://docs.mart.ps/developers/operate/request-limits.md) 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.

| You see | Do |
| - | - |
| `status: "inactive"` | Hide it or mark it unavailable, disable buying, keep the record. |
| `in_stock: false` or a variant at zero | Disable buying, keep the page live, keep the record. |

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

| Problem | Fix |
| - | - |
| Products vanish over time | You deleted products missing from a filtered read. Read `status` instead. |
| Prices go stale after a promotion | Add the daily full price refresh. |
| The incremental sync misses rows | Echo the highest `updated_at`, with its offset. |
| `429 rate_limit_exceeded` | Space the jobs out. |

The same sync in six languages: [Sync the catalogue](https://docs.mart.ps/recipes/sync-the-catalogue.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.