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

# Create an order safely: idempotency, retries, replay

> Create an order so a timeout or retry never makes a duplicate: store the body, reuse the same partner_reference, and read the replay you get back.

`POST /api/v1/orders` creates an order at your selling prices. **After a timeout, a lost answer or any `5xx`, and after a `429` once `Retry-After` has passed, resend the same body with the same `partner_reference`. Never make a new reference to try again.** You need `orders:write`, with order creation enabled for the key.

## Build the body

```json theme={null}
{
  "partner_reference": "100245",
  "payment_type": "cod",
  "shipping_address": {
    "customer_name": "محمد علي",
    "phone": "0599123456",
    "extra_phone": "022345678",
    "state_id": 386,
    "address": "شارع الإرسال، عمارة 12",
    "notes": null
  },
  "products": [
    { "product_id": 9597, "combination_id": 41206, "quantity": 2, "price": 120 }
  ],
  "free_shipping": true
}
```

| Field | Rules |
| - | - |
| `partner_reference` | Your own order id: letters, digits, `.`, `_`, `-`, at most 64. Spaces at either end are refused, never trimmed. Unique per key. |
| `payment_type` | Required: `"cod"` or `"card"`, lower case. Missing is `422 invalid_parameter`. `"card"` needs card payment enabled (`422 card_not_enabled`) and a saved card. |
| `shipping_address` | `customer_name`, `phone` (the number the courier calls), `state_id` (a town `id` from `GET /states`) and `address` are required. `extra_phone` and `notes` are optional; absent and `null` are the same. |
| `products` | 1 to 200 lines, each with `product_id` and `quantity`. `combination_id` is required for a product with variants, `null` or absent otherwise. The same product and variant twice is `422 duplicate_product` (`details.first_index`). |
| `free_shipping` | `true` means you pay delivery from your margin. Never on a card order (`422 card_free_shipping_not_allowed`). See [Delivery prices and free shipping](https://docs.mart.ps/developers/orders/delivery-prices.md). |

Mart works out the courier's collection, the currency, the courier and the delivery fee: fields you send for them, and any unknown field, are ignored. Errors name a line by `index`, its zero-based position.

### Line prices

A line's `price` is your selling price per unit, tax included.

* **Absent or `null`:** sells at `group_price`, resolved and frozen at creation. An explicit `0` is refused.
* **Sent:** at least `price.group_price` at creation, or `422 price_below_minimum` (`details.minimum`). Equal passes.
* **Custom prices off** (`price_override_allowed: false` on `GET /account`): only the exact `group_price`, or `422 price_override_not_allowed` (`details.expected`). Mart never replaces a price you sent.
* **Card order:** never send a price (`422 card_price_not_allowed`).

## Send it

1. **Make the reference once** from your order id, and store it before the first attempt.
2. **Store the exact body** by reference. A retry sends those stored bytes: a rebuilt body can pick up a new price or order and turn a safe retry into a `409`.
3. **Quote it first** if you show totals: `POST /api/v1/orders/validate` with the same body creates nothing. See [Delivery prices and free shipping](https://docs.mart.ps/developers/orders/delivery-prices.md).
4. **Send it** with a generous timeout, for example 60 seconds.

Every line is checked live at creation: product, variant, price floor, stock. One failure refuses the whole order and creates nothing.

## Act on the answer

| Answer | Meaning | Do |
| - | - | - |
| `201`, `idempotency_replay: false` | Created now. | Record `data.order.id`. |
| `200`, `idempotency_replay: true` | Created earlier with this reference and body: the original order. | Record it. It is a success. |
| No answer (timeout, dropped connection) | Unknown. | Resend the stored body, same reference. |
| `409 idempotency_conflict` | The reference already names a different order (`details.original_order_id`). | Alert a person: your reference generation has a bug. Never use a new reference to get past it. |
| `422` or `400` | Nothing created. | Fix what `error.code` names; resend under the same reference. |
| `429` | A request limit. | Wait `Retry-After`, resend the stored body. |
| `500`, `502`, `504` or any other `5xx` | Mart's side or the network edge; the order may exist. | Resend the stored body, same reference, with backoff. |
| `503 order_creation_in_progress` | This reference, or another order of yours to the same recipient, is in progress. | Wait `Retry-After`, resend. |
| `503 payment_gateway_unavailable` | Card: the gateway did not answer; no order created. | Wait `Retry-After`, resend with the same reference. It never charges twice. |
| `402 card_declined` | Card declined; nothing captured, no order created. | Do not retry in a loop. A later resend with the same reference makes a fresh charge attempt, never a double charge. Once `details.attempts_exhausted` is `true`, fix the card with Mart, then use a new reference. |
| `409 charge_amount_mismatch` | Card: an earlier attempt captured a different amount. | Contact Mart; do not resend. |
| `401`, `403` | Key or permission. | Alert a person. |

## Why is a retry safe?

The same reference returns the original order if it was created, or creates it now: exactly one order either way. The replay check runs before any catalogue check, so a retry is never refused for stock, price or status.

Mart compares a canonical form of the body. It ignores key order, extra spaces, number format (`120`, `"120.00"`), boolean spelling (`true`, `"1"`, `"yes"`), Unicode composition, unknown fields, and absent versus `null`. A change to `partner_reference`, `shipping_address`, `free_shipping` or `products`, including their order, does count. An order created before `payment_type` existed replays against its original body, so adding the field to that reference answers `409`.

After a `422 price_below_minimum`: read the product again, update your price from the new `group_price`, confirm a higher price with your customer, then resend under the same reference.

```text theme={null}
for attempt in 1..5:
    try: r = POST /api/v1/orders with stored_body(reference)
    catch NoResponse: sleep(backoff(attempt)); continue      // same reference, same bytes
    if r.status in (200, 201): return r.body.data.order
    if r.status == 429 or r.status >= 500:                   // 500, 502, 503, 504...
        sleep(retry_after or backoff(attempt)); continue     // same reference, same bytes
    if r.status in (400, 422): return fix_and_resend(r)      // nothing was created
    if r.status == 402: return card_declined(r)              // resend later, same reference,
                                                             // until details.attempts_exhausted
    alert_human(r); return                                   // 401, 403, 409
backoff(attempt) = 2^attempt seconds + random jitter
```

## Read the answer

`data.order` has `id`, `partner_reference`, `status`, `created_at`, `cod_total` (what the courier collects), `shipping_fee`, `free_shipping`, `reward`, `money`, `products` (with each line's frozen `group_price`) and `shipping_address`.

**A replay never changes.** It returns the creation answer byte for byte, including its `status` and its `money` (`earning_state: pending`). Never poll it. Keep the creation answer for settlement: the order read does not repeat `reward`.

## Read an order back

`GET /api/v1/orders/{partner_reference}` returns the live order:

* `status` is `{id, name}`, exactly what the customer sees. Treat `id` as opaque; never parse `name`.
* Quantities, `cod_total` and `free_shipping` follow Mart's changes. Each line's `price` and the `shipping_fee` stay as created.
* `money` is live: `gross`, `shipping_deduction`, `net` and `earning_state`: `pending`, `held` (with `available_at`), `available` or `reversed` (all `0.00`). `available` means the order matured, not that you can withdraw it: a debt can offset it.
* Another partner's reference answers `404 order_not_found`, like one that does not exist.

`GET /api/v1/orders` lists orders, 50 per page by default, at most 100, filtered by `status`, `payment_type`, `created_from`, `created_to` and `updated_since`. To follow many orders, use [events](https://docs.mart.ps/developers/money/events.md).

The full retry loop in six languages: [Create an order](https://docs.mart.ps/recipes/create-an-order.md).


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