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

# Quickstart: from a sandbox key to production

> Make your first call in the Mart sandbox, quote, create and cancel a test order safely, then switch to production by changing only the base URL and key.

Build against the sandbox, `https://sandbox.mart.ps`: the same API, where nothing is delivered or charged. Mart issues a production key once your integration passes the test order in steps 5 and 6.

## Prerequisites

* **A sandbox key** (`mk_test_…`) from Mart, with order creation enabled. Until it is, order calls answer `422 orders_not_enabled`; catalogue reads still work.
* **The sandbox fixture list** Mart sends with it: products, towns and codes prepared for testing.
* **A server-side place for the key**, such as an environment variable. Never put a key in client-side code, an app, a repository or a URL.

## Step 1: Set the base URL and key

```bash theme={null}
export MART_API_BASE="https://sandbox.mart.ps"
export MART_API_KEY="paste your sandbox key here"
```

A sandbox key works only on the sandbox, and a production key (`mk_live_…`) only on `https://mart.ps`. The wrong pair answers `401 key_environment_mismatch`.

## Step 2: Make your first call

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

A `200` means the key works. Check the `X-Mart-Environment` header (`sandbox` or `production`) once at startup, so a wrong base URL fails on the first call, not the first order.

* `401`: the key is missing, wrong, paused, revoked or for the other environment. Do not retry; fix it.
* `403`: the account is not permitted right now, or `insufficient_scope`. See [Authenticate and keys](https://docs.mart.ps/developers/authenticate.md).

## Step 3: Load towns and products

```bash theme={null}
curl -sS --max-time 30 -H "Authorization: Bearer $MART_API_KEY" "$MART_API_BASE/api/v1/states"
curl -sS --max-time 60 -H "Authorization: Bearer $MART_API_KEY" "$MART_API_BASE/api/v1/products?page=1&limit=500"
```

* A town's `id` is what an order sends as `shipping_address.state_id`. Match towns on `id`: names repeat.
* Page products until `meta.pagination.has_next` is `false`. Key them on `product_id` and `combination_id`, never `reference`.

## Step 4: Quote a test order

Save `order.json` with a fixture product and a town `id`:

```json order.json theme={null}
{
  "partner_reference": "TEST-0001",
  "payment_type": "cod",
  "shipping_address": {
    "customer_name": "Test Customer",
    "phone": "0599123456",
    "state_id": 386,
    "address": "Test street 12"
  },
  "products": [
    { "product_id": 9597, "combination_id": 41206, "quantity": 1 }
  ],
  "free_shipping": false
}
```

```bash theme={null}
curl -sS --max-time 60 -X POST -H "Authorization: Bearer $MART_API_KEY" \
  -H "Content-Type: application/json" --data @order.json \
  "$MART_API_BASE/api/v1/orders/validate"
```

`data.validation.quote` gives the totals, the delivery fee and your reward. Nothing is created.

## Step 5: Create the order twice

```bash theme={null}
curl -sS --max-time 60 -X POST -H "Authorization: Bearer $MART_API_KEY" \
  -H "Content-Type: application/json" --data @order.json \
  "$MART_API_BASE/api/v1/orders"
```

Expect `201` with `meta.idempotency_replay: false`. Send the **exact same request** again: expect `200`, `meta.idempotency_replay: true` and the same order `id`. This is how a retry after a timeout stays safe.

## Step 6: Cancel it twice

```bash theme={null}
curl -sS --max-time 30 -X POST -H "Authorization: Bearer $MART_API_KEY" \
  -H "Content-Type: application/json" --data '{"reason":"Test"}' \
  "$MART_API_BASE/api/v1/orders/cancel/TEST-0001"
```

Expect `200` with `already_cancelled: false`, then `already_cancelled: true` the second time.

## How does the sandbox differ?

| Area | In the sandbox |
| - | - |
| Data | A refreshed, de-identified copy of the catalogue, with synthetic customers and orders. |
| Identifiers | `product_id` and `combination_id` match production, so a synced catalogue stays valid. |
| Resets | On a schedule and after each refresh. Your key and the fixtures survive; your orders do not. The events feed starts again, so an old cursor answers `422 invalid_cursor`. |
| Card orders | Lahza's test gateway. Save the Visa test card `4111 1111 1111 1111`: it is reusable. `5424 0000 0000 0015` pays once but cannot be reused for card orders. |
| Storefront | Sign in at `https://sandbox.mart.ps` with the password Mart sends with the key. |

Rate limits, error codes, the envelope and idempotency are the same as production.

## Go live

1. Ask Mart for a production key (`mk_live_…`).
2. Change the base URL to `https://mart.ps` and the key, and nothing else.
3. Check that `X-Mart-Environment` says `production`.

If you place one real order as a final check, tell Mart its `partner_reference` and Mart removes it.

## Next steps

* [Sync the catalogue](https://docs.mart.ps/developers/catalogue/sync.md)
* [Create an order safely](https://docs.mart.ps/developers/orders/create-an-order.md)
* [Handle errors](https://docs.mart.ps/developers/operate/handle-errors.md)
* The same calls in six languages: [Make your first call](https://docs.mart.ps/recipes/first-call.md)


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