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

# Follow events on your account

> Follow your orders, movements, withdrawals and payout method as one feed of events, store the cursor right, and process each event once after retries.

`GET /api/v1/events` (scope `events:read`) is one feed of what happened on your account, oldest first. Reading it replaces polling every order and your balance.

## What is in the feed?

Each item has `cursor`, `type`, `reference`, `occurred_at` and `payload`; `meta` has `next_cursor` and `has_more`.

| `type` | `reference` | `payload` |
| - | - | - |
| `order.created` | Your `partner_reference` | An item of `GET /orders` |
| `order.status_changed` | Your `partner_reference` | An item of `GET /orders`, with the new `status` |
| `ledger.entry_posted` | Your `partner_reference` for an earning or a reversal, otherwise `null` | An item of `GET /ledger` |
| `withdrawal.requested`, `.approved`, `.rejected`, `.cancelled`, `.paid` | The `withdrawal_id` | An item of `GET /withdrawals`, without `iban` |
| `payout_method.changed` | `null` | `version` and `updated_at` only |

Treat an unknown `type` as informational.

## Read it

1. **Start** with no `after` to read from the oldest event kept, or `start=latest` to start from now (an empty page whose `next_cursor` is the head).
2. **Read a page:** `GET /api/v1/events?after=<cursor>&limit=100`. `limit` is 1 to 500, 100 by default.
3. **Skip** any `cursor` you already processed.
4. **Store `meta.next_cursor`**, not your last event's cursor: it can move past your last event, even on an empty page.
5. **`has_more: true`:** ask again at once; that page can be empty. **`false`:** nothing more now; wait before polling again.

A cursor is opaque. After a `500`, ask again with the cursor you hold.

## Guarantees

* **No gaps.** A replay from any cursor shows every later event, in the same order.
* **At least once.** After a lost answer you read events again: de-duplicate on `cursor`.
* **Feed order is commit order.** Use `occurred_at` to tell which of two changes came last.
* **Late events.** An event that could not be written at the time is written once, later, with its original `occurred_at`. A late `order.created` shows the order as it is when written.

The feed belongs to your account, not your key: a replacement key reads the same feed.

## Recover from a refused cursor

* **`422 invalid_cursor`:** the feed never issued that `after`, blank included, or the store was restored under it (in the sandbox, after a reseed). Start over with no `after`, or `start=latest`. `start` and `after` together, or a bad `limit` or `start`, answer `422 invalid_parameter`.
* **`410 cursor_expired`** (`details.resync: true`): the cursor is older than what the feed keeps. Events are kept unless Mart sets a retention period for your account. Recover in this order:
  1. Send `start=latest` and keep its `next_cursor`.
  2. Rebuild from `GET /orders`, `GET /ledger` and `GET /withdrawals`.
  3. Read on from the cursor of step 1, skipping events already in your rebuild.

The same loop in six languages and four frameworks: [Follow events](https://docs.mart.ps/recipes/follow-events.md).


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