> ## 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)).

# Request limits and a schedule that fits them

> Look up how request limits work per key, per minute and per day, how to read the rate-limit headers, and a sync schedule that stays inside your ceiling.

Limits apply per key, per minute and per day, both across the whole API and per endpoint. Whichever is tighter is the one you hit first. Plan against the **global daily ceiling**.

## Rules

* **Fixed windows.** A burst across a boundary can briefly get twice the per-minute limit; never design around it.
* **The daily window resets at 00:00 UTC,** not your local midnight. Place heavy nightly jobs relative to UTC.
* **Refused calls count.** A `429` still uses budget, so hammering keeps you blocked.
* **Scope refusals do not count.** `403 insufficient_scope` is decided first.

## Your limits

Your own limits are in the `X-RateLimit-*` headers and `rate_limits` on `GET /api/v1/account`, and on the **API & Activity** tab of the partner panel. The shop's defaults follow; Mart can change them, so never hard-code one.

| Scope | Per minute | Per day |
| - | - | - |
| **All endpoints combined** | **120** | **20,000** |
| `GET /products` | 60 | 10,000 |
| `GET /products/{product_id}` | 120 | 20,000 |
| `GET /products/ids` | 60 | none of its own |
| `GET /states`, `/categories`, `/attributes` | 60 each | 5,000 each |
| `POST /orders` | 30 | 2,000 |
| `POST /orders/validate` | 60 | 5,000 |
| `GET /orders/{partner_reference}` | 120 | 20,000 |
| `POST /orders/cancel/{partner_reference}` | 30 | 2,000 |
| Order list, events, money and account | global only | global only |

The per-endpoint daily figures are not a budget you can add up: the global ceiling covers everything.

## Headers

On every `2xx` and on errors raised by an endpoint, for the tightest window. They are absent on `401`, `403`, `405`, a `route_not_found` `404` and `OPTIONS`.

| Header | Meaning |
| - | - |
| `X-RateLimit-Limit` | The tightest window's limit. |
| `X-RateLimit-Remaining` | Requests left in it. Back off when it gets low. |
| `X-RateLimit-Reset` | When it resets, in epoch seconds. |

Over a limit you get `429 rate_limit_exceeded` with `Retry-After` in seconds. A daily breach advertises the daily reset, not 60 seconds: honour the header.

## A schedule that fits

| Job | Call | Interval |
| - | - | - |
| Stock poll | `GET /products`, every page | 5 to 15 minutes |
| Structural sync | `GET /products?updated_after=…` | Hourly |
| Full price refresh | `GET /products`, every page | Daily |
| Destinations | `GET /states` | At least daily |
| Full reconcile | `GET /products`, every page | Weekly |
| Events | `GET /events` | At once while `has_more`; otherwise wait |

A catalogue of about 20,000 products at `limit=1000` is about 20 pages. Polling stock every 15 minutes is 1,920 calls a day, every 5 minutes 5,760: both fit. Every 30 seconds would be 57,600, and fail partway through the day.


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