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

# Authenticate, scopes and keeping your key safe

> Send your API key on every request, check the scopes it holds, read what your account may do, and follow the rules that keep your key and money safe.

Send your API key on every call. Each endpoint needs one scope on that key. Anyone who holds the key can read your prices and create orders in your name, so it lives on your server only.

## Send the key

Use either header; `Authorization` is preferred:

```http theme={null}
Authorization: Bearer <your key>
X-Api-Key: <your key>
```

Keys are `mk_test_…` for the sandbox and `mk_live_…` for production, and each works only in its own environment. A key prices the catalogue for your own account, so another partner can see a different `group_price` for the same product.

## Scopes

A key without the scope an endpoint needs gets `403 insufficient_scope`, with `error.details.required_scope`. The check runs before the rate limit, so the refusal uses none of your budget. Retrying does not help: ask Mart to add the scope.

| Scope | Endpoints |
| - | - |
| `catalog:read` | `GET /products`, `/products/ids`, `/products/{product_id}`, `/categories`, `/attributes`, `/states` |
| `orders:read` | `GET /orders`, `/orders/{partner_reference}` |
| `orders:write` | `POST /orders`, `/orders/validate`, `/orders/cancel/{partner_reference}` |
| `payments:card` | `payment_type: "card"` on `POST /orders` |
| `money:read` | `GET /balance`, `/ledger`, `/statements`, `/statements/{statement_number}`, `/payout-method`, `/withdrawals`, `/withdrawals/{withdrawal_id}` |
| `iban:write` | `PUT /payout-method` |
| `withdrawals:write` | `POST /withdrawals`, `/withdrawals/{withdrawal_id}/cancel` |
| `events:read` | `GET /events` |
| `reports:read` | `GET /reports/summary` |

`GET /account` needs no scope. Each operation in the [API reference](https://docs.mart.ps/api-reference/overview.md) names its scope in `x-required-scope`.

**Keys made before scopes existed** keep exactly their old access. On order writes they still get `422 orders_not_enabled`, never a `403`, and a card order without card payment gets `422 card_not_enabled`. Where withdrawals are off, their money writes get `403 withdrawals_disabled`.

## Read what your account may do

Call `GET /api/v1/account` at startup instead of learning from refusals.

| Field | Meaning |
| - | - |
| `status` | `active`, `paused` or `closed`. A paused account takes no new orders but reads and cancels. |
| `orders_enabled` | Your key may write orders and the account is not paused. |
| `card_enabled`, `price_override_allowed`, `free_shipping_allowed` | Whether you may send a card order, your own line `price`, and `free_shipping: true`. |
| `rate_limits` | `per_minute` and `per_day` for your key across the API. |
| `payout_method_saved` | Whether a payout method is saved. When `false`, save one before the first withdrawal. |
| `withdrawals` | `enabled`, `minimum` (shekels) and `max_open_requests`; numbers are `null` when withdrawals are off or Mart set none. |
| `money.available` | Whether money reads work now. When `false`, they answer `503 ledger_unavailable`. |
| `shop_display_name` | Your shop's name on Mart's records. |

A closed account's key can still read your money and ask to withdraw, but cannot change the payout method or place orders.

## Keep the key safe

1. Keep it in a secrets manager or a server-side environment variable.
2. Never put it in client-side code, a mobile app, a repository or a URL.
3. Call the API from your server only, never from a browser.
4. If a key is exposed, tell Mart: Mart issues a replacement.

> [!WARNING]
>
> Treat every `401` as "stop and alert a person", never as something to retry. A paused or revoked key answers exactly like an unknown one.

## Troubleshooting

| Answer | Fix |
| - | - |
| `401 missing_api_key` | Send the header. |
| `401 invalid_api_key` | The key is unknown, paused or revoked: ask Mart. |
| `401 key_environment_mismatch` | Pair `mk_test_` with the sandbox and `mk_live_` with `https://mart.ps`. |
| `403 insufficient_scope` | Ask Mart to add `details.required_scope`. |
| `422 orders_not_enabled` | Order creation is off for the key, or the account is paused: ask Mart. |


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