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

# Balance, movements, statements and reports

> Read your balance, list the movements behind it, fetch closed statements and your order totals through the API, and show each figure with its meaning.

Money is in shekels (`ILS`), as JSON numbers with at most two decimals, never agorot. Show each figure with its own meaning: they do not add up to one another. You need `money:read`.

## Read your balance

```bash theme={null}
curl -sS --max-time 30 -H "Authorization: Bearer $MART_API_KEY" "$MART_API_BASE/api/v1/balance"
```

| Field | Meaning |
| - | - |
| `balance` | Everything earned, less everything paid or charged, held earnings included. Negative when you owe. |
| `available` | What you may withdraw now: matured earnings less open withdrawal requests. Never negative. |
| `held` | Earned, not matured yet. |
| `next_maturity` | The next part of `held` to mature, as `at` and `amount`, or `null`. |
| `owed` | A debt on the account, `0` when none. |
| `under_review` | Matured earnings whose order is not delivered right now. Never in `available`; can exceed `balance`. |
| `pending` | What orders not delivered yet will earn. Not money: never in `balance`, a statement or a withdrawal. Can be negative. |
| `pending_state` | `ok` (exact), `incomplete` (Mart is checking an order; `pending` is `null`) or `unavailable`. |

Earnings are available only while their order is delivered. If a delivered order moves on, for example to a ticket or an exchange, its earnings wait in `under_review` until it is delivered again. A charge always counts at once.

## List movements

`GET /api/v1/ledger?page=1&limit=50` lists every movement, newest first. `limit` is 50 by default, at most 100.

| Field | Meaning |
| - | - |
| `entry_id` | Opaque and stable. De-duplicate on it: a page can repeat a row, never skip one. |
| `type` | `earning`, `reversal`, `payment`, `adjustment` or `charge`. Treat an unknown value as informational. |
| `amount` | Signed: a credit is positive. A positive `charge` is a charge undone. |
| `partner_reference` | The order an earning, reversal or charge belongs to; `null` otherwise, or for an order placed with another key of your account. |
| `payment_method` | `bank_transfer` or `cash` on a payment, otherwise `null`. |
| `occurred_at`, `recorded_at` | When it happened and when it was entered. `recorded_at` decides its statement. |
| `available_at`, `state` | For an earning or a reversal: `held` until `available_at`, then `available`. |

## Fetch statements

`GET /api/v1/statements` lists closed statements, newest first: `number`, `period_start` (inclusive), `period_end` (exclusive), `opening`, `closing` and `finalized_at`. `GET /api/v1/statements/{statement_number}` adds `movements`, oldest first, paged like `GET /ledger`. A number that is not yours answers `404 statement_not_found`.

`opening` and `closing` include held earnings, so they are not amounts that could be paid out.

## When the balance cannot be read

Every money read answers `503 ledger_unavailable`, with no `Retry-After`, never zeros or an empty list.

1. Show that the balance is unavailable, never a figure you did not get.
2. Retry later with backoff.
3. `money.available` on `GET /api/v1/account` still answers `200`.

An account with no movements gets a normal `200` with zeros and empty lists.

## Order totals report

`GET /api/v1/reports/summary?months=6` (scope `reports:read`) totals your orders over `3`, `6` or `12` months, `12` by default, counting the current month. Any other value, `03` included, answers `422 invalid_parameter`.

* `order_count`, `order_value` and `average_order_value` over the range.
* `by_month`, newest first: `month`, `orders`, `value`, `cod_orders`, `card_orders` and `cancelled`. Months are in the shop's local time.
* `top_products`: up to 10, with `product_id`, `combination_id`, `name`, `quantity` and `orders`.

Values are order totals only, no payouts or balances. Cancelled orders are counted and also shown per month. A new order can be missing for a short time, until it is recorded.

The balance read in six languages: [Read your balance](https://docs.mart.ps/recipes/read-your-balance.md).


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