> ## 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 order

> Creates an order priced at your selling prices. Atomic: any single line failure rejects the whole order with 422 and nothing is created. Idempotent by `partner_reference`: an identical retry answers 200 with `meta.idempotency_replay: true`, different content answers 409. `payment_type` is REQUIRED (`cod` or `card`); with `card` the saved card is charged synchronously for the server-computed total (402 `card_declined` / 503 `payment_gateway_unavailable`; allow a 60s client timeout). Read the order back with `GET /api/v1/orders/{partner_reference}`. Full behaviour: https://mart.ps/api/docs#orders.



## OpenAPI

````yaml /openapi.json post /api/v1/orders
openapi: 3.0.3
info:
  title: Mart Partner API
  version: 1.1.0
  description: >-
    REST API for Mart reseller partners: the product catalog (with per-product
    and per-combination stock), delivery destinations, and order creation — cash
    on delivery or card.


    Every response, success or failure, uses the envelope `{status, status_code,
    message, data, meta, error}`; branch on `error.code`, never on `message`.
    Response keys are structurally stable: absent objects are `null`, absent
    collections are `[]`; the only caller-controlled structural variance is the
    products listing's `include=` parameter.


    Authenticate with `Authorization: Bearer <key>` (preferred) or `X-Api-Key`.
    A key holds scopes, each operation names the one it needs in
    `x-required-scope`, and a key without it is answered `403`
    `insufficient_scope` (`details.required_scope` names it) without using any
    quota; keys made before scopes existed keep exactly the access they had.
    Rate limits are per key on fixed minute/day windows; the `X-RateLimit-*`
    headers are authoritative.


    **Environments** — build against the sandbox first.
    `https://sandbox.mart.ps` is a separate installation with its own keys
    (`mk_test_…`), a periodically refreshed copy of the catalog, synthetic
    customers and orders, and Lahza's test gateway: nothing placed there is
    fulfilled or charged, and its data is reset on a published schedule.
    Production keys are `mk_live_…` and work only against `https://mart.ps`; a
    key sent to the wrong environment answers `401` `key_environment_mismatch`
    before anything else is checked. Every response carries `X-Mart-Environment:
    production|sandbox` — assert it in your client so a misconfigured base URL
    fails loudly.


    This document is the machine contract. The human documentation — onboarding,
    sync guidance, pricing semantics, idempotent retries, the full error
    catalogue with remedies — is at https://mart.ps/api/docs.
servers:
  - url: https://mart.ps
    description: Production
  - url: https://sandbox.mart.ps
    description: Sandbox
security:
  - bearerAuth: []
  - apiKeyHeader: []
tags:
  - name: Products
    description: 'Catalog: listing and product detail, with prices and stock.'
  - name: Categories
    description: Catalog category vocabulary for the products category_id filter.
  - name: Attributes
    description: Attribute-group vocabulary behind the products combination attributes.
  - name: Delivery
    description: Delivery destinations for order shipping addresses.
  - name: Orders
    description: >-
      Cash-on-delivery order creation, order list, dry-run validation, order
      read and cancellation.
  - name: Money
    description: >-
      Your balance, the ledger of movements, your statements, your payout
      method, your withdrawals and the feed of events on your account.
  - name: Reports
    description: Your own order totals by month, and your most ordered products.
  - name: Account
    description: 'Your own account: its state, limits and withdrawal rules.'
paths:
  /api/v1/orders:
    post:
      tags:
        - Orders
      summary: Create order
      description: >-
        Creates an order priced at your selling prices. Atomic: any single line
        failure rejects the whole order with 422 and nothing is created.
        Idempotent by `partner_reference`: an identical retry answers 200 with
        `meta.idempotency_replay: true`, different content answers 409.
        `payment_type` is REQUIRED (`cod` or `card`); with `card` the saved card
        is charged synchronously for the server-computed total (402
        `card_declined` / 503 `payment_gateway_unavailable`; allow a 60s client
        timeout). Read the order back with `GET
        /api/v1/orders/{partner_reference}`. Full behaviour:
        https://mart.ps/api/docs#orders.
      operationId: createOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCreateRequest'
            example:
              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
      responses:
        '200':
          description: >-
            Idempotent replay: the ORIGINAL response, byte-for-byte, frozen at
            creation (`meta.idempotency_replay: true`) — a record of what was
            created, not a live view. One shape exception: an order created
            before `payment_type` existed replays its frozen body without that
            key.
          headers:
            X-Mart-Environment:
              $ref: '#/components/headers/X-Mart-Environment'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelope'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          order:
                            $ref: '#/components/schemas/Order'
                      meta:
                        $ref: '#/components/schemas/OrderMeta'
              example:
                status: success
                status_code: 201
                message: Created
                data:
                  order:
                    id: 100311
                    partner_reference: '100245'
                    status: processing
                    payment_type: cod
                    created_at: '2026-08-01T10:15:00+00:00'
                    cod_total: 240
                    shipping_fee: 35
                    free_shipping: true
                    reward:
                      gross_product_reward: 130.02
                      shipping_deduction: 35
                      net_reward: 95.02
                    money:
                      gross: 130.02
                      shipping_deduction: 35
                      net: 95.02
                      earning_state: pending
                      available_at: null
                    products:
                      - product_id: 9597
                        combination_id: 41206
                        quantity: 2
                        price: 120
                        group_price: 54.99
                    shipping_address:
                      customer_name: محمد علي
                      phone: '0599123456'
                      extra_phone: '022345678'
                      state_id: 386
                      address: شارع الإرسال، عمارة 12
                      notes: null
                meta:
                  idempotency_replay: true
                error: null
        '201':
          description: Order created. `meta.idempotency_replay` is false.
          headers:
            X-Mart-Environment:
              $ref: '#/components/headers/X-Mart-Environment'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelope'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          order:
                            $ref: '#/components/schemas/Order'
                      meta:
                        $ref: '#/components/schemas/OrderMeta'
              example:
                status: success
                status_code: 201
                message: Created
                data:
                  order:
                    id: 100311
                    partner_reference: '100245'
                    status: processing
                    payment_type: cod
                    created_at: '2026-08-01T10:15:00+00:00'
                    cod_total: 240
                    shipping_fee: 35
                    free_shipping: true
                    reward:
                      gross_product_reward: 130.02
                      shipping_deduction: 35
                      net_reward: 95.02
                    money:
                      gross: 130.02
                      shipping_deduction: 35
                      net: 95.02
                      earning_state: pending
                      available_at: null
                    products:
                      - product_id: 9597
                        combination_id: 41206
                        quantity: 2
                        price: 120
                        group_price: 54.99
                    shipping_address:
                      customer_name: محمد علي
                      phone: '0599123456'
                      extra_phone: '022345678'
                      state_id: 386
                      address: شارع الإرسال، عمارة 12
                      notes: null
                meta:
                  idempotency_replay: false
                error: null
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/CardDeclined'
        '403':
          $ref: '#/components/responses/ForbiddenGroup'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
        '422':
          $ref: '#/components/responses/OrderUnprocessable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/PaymentGatewayUnavailable'
      x-codeSamples:
        - lang: bash
          label: cURL recipe
          source: >
            #!/usr/bin/env bash

            # Create an order that survives a timeout: retry with the same
            partner_reference and read the replay.

            # Needs MART_API_BASE, MART_API_KEY, MART_PRODUCT_ID, MART_STATE_ID
            and MART_PARTNER_REFERENCE:

            # your own id for this order, from your own system, so that running
            this again can never make a

            # second order.

            set -euo pipefail

            export LC_NUMERIC=C # printf reads and writes amounts with a decimal
            point


            reference=${MART_PARTNER_REFERENCE:?set MART_PARTNER_REFERENCE to
            your own id for this order}

            order=$(jq -n --arg ref "$reference" --argjson product
            "$MART_PRODUCT_ID" --argjson state "$MART_STATE_ID" '{
              partner_reference: $ref,
              payment_type: "cod",
              products: [{product_id: $product, quantity: 1}],
              shipping_address: {customer_name: "Test Buyer", phone: "0599000000", state_id: $state, address: "Main street 1"}
            }')

            echo "reference: $reference" # written down before the first attempt


            # Retries are your choice of numbers: at most 5 attempts; after no
            answer, a 429 or a 5xx, wait

            # what Retry-After says, or else 1, 2, 4, 8 seconds (capped at 30)
            with jitter. Any other answer

            # is final. Every attempt sends the SAME body, so a retry can never
            create a second order.

            for attempt in 1 2 3 4 5; do
              response=$(curl --silent --show-error --max-time 60 --request POST \
                --header @<(printf 'Authorization: Bearer %s\n' "$MART_API_KEY") --header 'Content-Type: application/json' \
                --data "$order" --write-out '\n%{http_code} %header{retry-after}' "$MART_API_BASE/api/v1/orders") || response=$'\n000'
              read -r status retry_after <<<"${response##*$'\n'}"
              body=${response%$'\n'*}
              case $status in 000 | 429 | 500 | 502 | 503 | 504) ;; *) break ;; esac
              [ "$attempt" = 5 ] && break
              if [[ $retry_after =~ ^[0-9]+$ ]]; then
                if [ "$retry_after" -gt 60 ]; then
                  echo "error: $status, try again after $retry_after s with MART_PARTNER_REFERENCE=$reference" >&2
                  exit 1
                fi
                wait_ms=$((retry_after * 1000))
              else
                wait_ms=$((1000 << (attempt - 1)))
                [ "$wait_ms" -gt 30000 ] && wait_ms=30000
                wait_ms=$((wait_ms / 2 + RANDOM % (wait_ms / 2 + 1)))
              fi
              printf 'retry: attempt %d %s, waiting %d.%d s\n' "$attempt" \
                "$([ "$status" = 000 ] && echo 'got no answer' || echo "answered $status")" $((wait_ms / 1000)) $((wait_ms % 1000 / 100)) >&2
              sleep "$((wait_ms / 1000)).$(printf '%03d' $((wait_ms % 1000)))"
            done


            if [ "$status" = 000 ] || [ "$status" -ge 500 ] || [ "$status" = 429
            ]; then
              echo "error: ${status/000/no answer}${retry_after:+, try again after $retry_after s}; the order may exist: run again later with MART_PARTNER_REFERENCE=$reference" >&2
              exit 1
            fi

            if [ "$status" -ge 300 ]; then
              echo "error: $status $(jq -r '.error.code' <<<"$body" 2>/dev/null || echo '(not JSON)')" >&2
              exit 1
            fi


            # 201: created now. 200 with meta.idempotency_replay true: this
            order already existed.

            echo "order: $(jq -r '.data.order.partner_reference' <<<"$body")"

            echo "status: $(jq -r '.data.order.status' <<<"$body")"

            printf 'order total: %.2f\n' "$(jq -r '.data.order.order_total'
            <<<"$body")"

            echo "replay: $(jq -r '.meta.idempotency_replay' <<<"$body")"
        - lang: typescript
          label: TypeScript recipe
          source: >
            // Create an order that survives a timeout: retry with the same
            partner_reference and read the replay.

            // Node 22.18 or later runs this .ts file as it is. Needs
            MART_API_BASE, MART_API_KEY, MART_PRODUCT_ID,

            // MART_STATE_ID and MART_PARTNER_REFERENCE: your own id for this
            order, from your own system, so that

            // running this again can never make a second order.

            const base = process.env.MART_API_BASE;

            const key = process.env.MART_API_KEY;

            const reference = process.env.MART_PARTNER_REFERENCE;

            if (!base || !key || !reference) throw new Error('Set MART_API_BASE,
            MART_API_KEY and MART_PARTNER_REFERENCE');


            const sleep = (ms: number) => new Promise((resolve) =>
            setTimeout(resolve, ms));

            const RETRYABLE = new Set([429, 500, 502, 503, 504]);


            // Retries are your choice of numbers: at most 5 attempts; after no
            answer, a 429 or a 5xx, wait

            // what Retry-After says, or else 1, 2, 4, 8 seconds (capped at 30)
            with jitter. Any other answer

            // is final. Every attempt sends the same bytes.

            async function send(path: string, payload: string, timeoutMs:
            number): Promise<Response | null> {
              for (let attempt = 1; ; attempt++) {
                let response: Response | null = null;
                try {
                  response = await fetch(`${base}${path}`, {
                    method: 'POST',
                    headers: { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json' },
                    body: payload,
                    signal: AbortSignal.timeout(timeoutMs),
                  });
                  if (!RETRYABLE.has(response.status) || attempt === 5) return response;
                } catch {
                  if (attempt === 5) return null; // no answer at all
                }
                let wait: number;
                const retryAfter = Number(response?.headers.get('retry-after'));
                if (response && Number.isInteger(retryAfter) && retryAfter > 0) {
                  if (retryAfter > 60) return response; // too long to wait here: the caller says when to come back
                  wait = retryAfter;
                } else {
                  const backoff = Math.min(30, 2 ** (attempt - 1));
                  wait = backoff / 2 + (Math.random() * backoff) / 2;
                }
                console.error(`retry: attempt ${attempt} ${response ? `answered ${response.status}` : 'got no answer'}, waiting ${wait.toFixed(1)} s`);
                await sleep(wait * 1000);
              }
            }


            // Decided once, before any attempt: every retry sends this same
            body.

            const order = JSON.stringify({
              partner_reference: reference,
              payment_type: 'cod',
              products: [{ product_id: Number(process.env.MART_PRODUCT_ID), quantity: 1 }],
              shipping_address: {
                customer_name: 'Test Buyer',
                phone: '0599000000',
                state_id: Number(process.env.MART_STATE_ID),
                address: 'Main street 1',
              },
            });

            console.log(`reference: ${reference}`); // written down before the
            first attempt


            const response = await send('/api/v1/orders', order, 60_000);

            const body = response ? await response.json().catch(() => null) :
            null;

            if (response === null || response.status === 429 || response.status
            >= 500) {
              const when = response?.headers.get('retry-after');
              console.error(`error: ${response ? response.status : 'no answer'}${when ? `, try again after ${when} s` : ''}; the order may exist: run again later with MART_PARTNER_REFERENCE=${reference}`);
              process.exit(1);
            }

            if (!response.ok || body === null) {
              console.error(`error: ${response.status} ${body?.error?.code ?? '(not JSON)'}`);
              process.exit(1);
            }

            // 201: created now. 200 with meta.idempotency_replay true: this
            order already existed.

            console.log(`order: ${body.data.order.partner_reference}`);

            console.log(`status: ${body.data.order.status}`);

            console.log(`order total:
            ${body.data.order.order_total.toFixed(2)}`);

            console.log(`replay: ${body.meta.idempotency_replay}`);
        - lang: python
          label: Python recipe
          source: >
            """Create an order that survives a timeout: retry with the same
            partner_reference and read the replay.


            Python 3.9 or later, with httpx. Needs MART_API_BASE, MART_API_KEY,
            MART_PRODUCT_ID, MART_STATE_ID and

            MART_PARTNER_REFERENCE: your own id for this order, from your own
            system, so that running this again

            can never make a second order.

            """

            import os

            import random

            import sys

            import time


            import httpx


            TIMEOUT = 60

            client = httpx.Client(
                base_url=os.environ["MART_API_BASE"],
                headers={"Authorization": f"Bearer {os.environ['MART_API_KEY']}"},
                timeout=TIMEOUT,
            )

            reference = os.environ["MART_PARTNER_REFERENCE"]



            def body_of(response: httpx.Response):
                """The JSON body, or None for an answer that is not JSON (an edge error page)."""
                try:
                    return response.json()
                except ValueError:
                    return None

            RETRYABLE = {429, 500, 502, 503, 504}



            def send(path: str, payload: dict):
                """POST the same payload until it is answered for good.

                Retries are your choice of numbers: at most 5 attempts; after no answer, a 429 or a 5xx, wait
                what Retry-After says, or else 1, 2, 4, 8 seconds (capped at 30) with jitter. Any other answer
                is final. Returns None when no attempt got an answer.
                """
                for attempt in range(1, 6):
                    response = None
                    try:
                        response = client.post(path, json=payload)
                        if response.status_code not in RETRYABLE or attempt == 5:
                            return response
                    except httpx.TransportError:
                        if attempt == 5:
                            return None
                    retry_after = response.headers.get("Retry-After", "") if response is not None else ""
                    if retry_after.isdigit() and int(retry_after) > 0:
                        if int(retry_after) > 60:
                            return response  # too long to wait here: the caller says when to come back
                        wait = float(retry_after)
                    else:
                        backoff = min(30, 2 ** (attempt - 1))
                        wait = backoff / 2 + random.uniform(0, backoff / 2)
                    what = f"answered {response.status_code}" if response is not None else "got no answer"
                    print(f"retry: attempt {attempt} {what}, waiting {wait:.1f} s", file=sys.stderr)
                    time.sleep(wait)


            def when(response) -> str:
                """", try again after N s" when the answer says how long to wait (Retry-After), else nothing."""
                retry_after = response.headers.get("Retry-After") if response is not None else None
                return f", try again after {retry_after} s" if retry_after else ""


            # Decided once, before any attempt: every retry sends this same
            body.

            order = {
                "partner_reference": reference,
                "payment_type": "cod",
                "products": [{"product_id": int(os.environ["MART_PRODUCT_ID"]), "quantity": 1}],
                "shipping_address": {
                    "customer_name": "Test Buyer",
                    "phone": "0599000000",
                    "state_id": int(os.environ["MART_STATE_ID"]),
                    "address": "Main street 1",
                },
            }

            print(f"reference: {reference}", flush=True)  # written down before
            the first attempt


            response = send("/api/v1/orders", order)

            if response is None or response.status_code == 429 or
            response.status_code >= 500:
                status = response.status_code if response is not None else "no answer"
                sys.exit(f"error: {status}{when(response)}; the order may exist: run again later with MART_PARTNER_REFERENCE={reference}")
            body = body_of(response)

            if response.is_error or body is None:
                sys.exit(f"error: {response.status_code} {body['error']['code'] if body else '(not JSON)'}{when(response)}")
            # 201: created now. 200 with meta.idempotency_replay true: this
            order already existed.

            created = body["data"]["order"]

            print(f"order: {created['partner_reference']}")

            print(f"status: {created['status']}")

            print(f"order total: {created['order_total']:.2f}")

            print(f"replay: {str(body['meta']['idempotency_replay']).lower()}")
        - lang: php
          label: PHP recipe
          source: >
            <?php

            // Create an order that survives a timeout: retry with the same
            partner_reference and read the replay.

            // PHP 7.4 or later, with the curl extension. Needs MART_API_BASE,
            MART_API_KEY, MART_PRODUCT_ID,

            // MART_STATE_ID and MART_PARTNER_REFERENCE: your own id for this
            order, from your own system, so that

            // running this again can never make a second order.

            $base = getenv('MART_API_BASE');

            $key = getenv('MART_API_KEY');

            $reference = (string) getenv('MART_PARTNER_REFERENCE');

            if ($reference === '') {
                fwrite(STDERR, "error: set MART_PARTNER_REFERENCE to your own id for this order\n");
                exit(1);
            }


            /**
             * One request with the curl extension. Returns [status, headers (lower-case name => value), body];
             * status 0 when there was no answer at all.
             */
            function request(string $method, string $url, string $key, ?string
            $payload = null, int $timeout = 30): array

            {
                $headers = [];
                $curl = curl_init($url);
                curl_setopt_array($curl, [
                    CURLOPT_CUSTOMREQUEST => $method,
                    CURLOPT_HTTPHEADER => ["Authorization: Bearer $key", 'Content-Type: application/json'],
                    CURLOPT_RETURNTRANSFER => true,
                    CURLOPT_CONNECTTIMEOUT => 10,
                    CURLOPT_TIMEOUT => $timeout,
                    CURLOPT_HEADERFUNCTION => function ($curl, string $line) use (&$headers): int {
                        $parts = explode(':', $line, 2);
                        if (count($parts) === 2) {
                            $headers[strtolower(trim($parts[0]))] = trim($parts[1]);
                        }
                        return strlen($line);
                    },
                ]);
                if ($payload !== null) {
                    curl_setopt($curl, CURLOPT_POSTFIELDS, $payload);
                }
                $body = curl_exec($curl);
                $status = $body === false ? 0 : (int) curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
                curl_close($curl);

                return [$status, $headers, (string) $body];
            }


            /** ", try again after N s" when the answer says how long to wait
            (Retry-After), else nothing. */

            function when(array $headers): string

            {
                return isset($headers['retry-after']) ? ", try again after {$headers['retry-after']} s" : '';
            }


            /**
             * POST the same payload until it is answered for good. Retries are your choice of numbers: at most
             * 5 attempts; after no answer, a 429 or a 5xx, wait what Retry-After says, or else 1, 2, 4, 8
             * seconds (capped at 30) with jitter. Any other answer is final.
             */
            function send(string $url, string $key, string $payload, int
            $timeout): array

            {
                for ($attempt = 1; ; $attempt++) {
                    [$status, $headers, $raw] = request('POST', $url, $key, $payload, $timeout);
                    if (!in_array($status, [0, 429, 500, 502, 503, 504], true) || $attempt === 5) {
                        return [$status, $headers, $raw];
                    }
                    $retryAfter = $headers['retry-after'] ?? '';
                    if (ctype_digit($retryAfter) && (int) $retryAfter > 0) {
                        if ((int) $retryAfter > 60) {
                            return [$status, $headers, $raw]; // too long to wait here: the caller says when to come back
                        }
                        $wait = (float) $retryAfter;
                    } else {
                        $backoff = min(30, 2 ** ($attempt - 1));
                        $wait = $backoff / 2 + mt_rand() / mt_getrandmax() * $backoff / 2;
                    }
                    fwrite(STDERR, sprintf("retry: attempt %d %s, waiting %.1f s\n", $attempt, $status === 0 ? 'got no answer' : "answered $status", $wait));
                    usleep((int) ($wait * 1000000));
                }
            }


            // Decided once, before any attempt: every retry sends this same
            body.

            $order = json_encode([
                'partner_reference' => $reference,
                'payment_type' => 'cod',
                'products' => [['product_id' => (int) getenv('MART_PRODUCT_ID'), 'quantity' => 1]],
                'shipping_address' => [
                    'customer_name' => 'Test Buyer',
                    'phone' => '0599000000',
                    'state_id' => (int) getenv('MART_STATE_ID'),
                    'address' => 'Main street 1',
                ],
            ]);

            echo "reference: $reference\n"; // written down before the first
            attempt


            [$status, $headers, $raw] = send("$base/api/v1/orders", $key,
            $order, 60);

            if ($status === 0 || $status === 429 || $status >= 500) {
                fwrite(STDERR, 'error: ' . ($status === 0 ? 'no answer' : $status) . when($headers) . "; the order may exist: run again later with MART_PARTNER_REFERENCE=$reference\n");
                exit(1);
            }

            $body = json_decode($raw, true);

            if ($status >= 300 || !is_array($body)) {
                fwrite(STDERR, "error: $status " . ($body['error']['code'] ?? '(not JSON)') . when($headers) . "\n");
                exit(1);
            }


            // 201: created now. 200 with meta.idempotency_replay true: this
            order already existed.

            echo "order: {$body['data']['order']['partner_reference']}\n";

            echo "status: {$body['data']['order']['status']}\n";

            printf("order total: %.2f\n",
            $body['data']['order']['order_total']);

            echo 'replay: ' . ($body['meta']['idempotency_replay'] ? 'true' :
            'false') . "\n";
        - lang: go
          label: Go recipe
          source: "//go:build ignore\n\n// Create an order that survives a timeout: retry with the same partner_reference and read the replay.\n// Go 1.22 or later. Needs MART_API_BASE, MART_API_KEY, MART_PRODUCT_ID, MART_STATE_ID and\n// MART_PARTNER_REFERENCE: your own id for this order, from your own system, so that running this again\n// can never make a second order. Run it with: go run create-an-order.go\npackage main\n\nimport (\n\t\"bytes\"\n\t\"encoding/json\"\n\t\"fmt\"\n\t\"io\"\n\t\"math\"\n\t\"math/rand\"\n\t\"net/http\"\n\t\"os\"\n\t\"strconv\"\n\t\"time\"\n)\n\nvar client = &http.Client{Timeout: 60 * time.Second}\n\nfunc main() {\n\treference := os.Getenv(\"MART_PARTNER_REFERENCE\")\n\tif reference == \"\" {\n\t\tfail(fmt.Errorf(\"set MART_PARTNER_REFERENCE to your own id for this order\"))\n\t}\n\tproductID, _ := strconv.Atoi(os.Getenv(\"MART_PRODUCT_ID\"))\n\tstateID, _ := strconv.Atoi(os.Getenv(\"MART_STATE_ID\"))\n\n\t// Decided once, before any attempt: every retry sends these same bytes.\n\torder, err := json.Marshal(map[string]any{\n\t\t\"partner_reference\": reference,\n\t\t\"payment_type\":      \"cod\",\n\t\t\"products\":          []map[string]any{{\"product_id\": productID, \"quantity\": 1}},\n\t\t\"shipping_address\": map[string]any{\n\t\t\t\"customer_name\": \"Test Buyer\", \"phone\": \"0599000000\", \"state_id\": stateID, \"address\": \"Main street 1\",\n\t\t},\n\t})\n\tif err != nil {\n\t\tfail(err)\n\t}\n\tfmt.Println(\"reference:\", reference) // written down before the first attempt\n\n\tresp := send(\"/api/v1/orders\", order)\n\tif resp == nil || resp.StatusCode == 429 || resp.StatusCode >= 500 {\n\t\tstatus := \"no answer\"\n\t\tif resp != nil {\n\t\t\tstatus = strconv.Itoa(resp.StatusCode)\n\t\t\tif after := resp.Header.Get(\"Retry-After\"); after != \"\" {\n\t\t\t\tstatus += \", try again after \" + after + \" s\"\n\t\t\t}\n\t\t}\n\t\tfail(fmt.Errorf(\"%s; the order may exist: run again later with MART_PARTNER_REFERENCE=%s\", status, reference))\n\t}\n\tvar answer struct {\n\t\tData struct {\n\t\t\tOrder struct {\n\t\t\t\tPartnerReference string  `json:\"partner_reference\"`\n\t\t\t\tStatus           string  `json:\"status\"`\n\t\t\t\tOrderTotal       float64 `json:\"order_total\"`\n\t\t\t} `json:\"order\"`\n\t\t} `json:\"data\"`\n\t\tMeta struct {\n\t\t\tIdempotencyReplay bool `json:\"idempotency_replay\"`\n\t\t} `json:\"meta\"`\n\t}\n\tdecode(resp, &answer)\n\t// 201: created now. 200 with meta.idempotency_replay true: this order already existed.\n\tfmt.Println(\"order:\", answer.Data.Order.PartnerReference)\n\tfmt.Println(\"status:\", answer.Data.Order.Status)\n\tfmt.Printf(\"order total: %.2f\\n\", answer.Data.Order.OrderTotal)\n\tfmt.Println(\"replay:\", answer.Meta.IdempotencyReplay)\n}\n\nvar retryable = map[int]bool{429: true, 500: true, 502: true, 503: true, 504: true}\n\n// send POSTs the same bytes until they are answered for good, and returns the last answer, or\n// nil when no attempt got one. Retries are your choice of numbers: at most 5 attempts; after no\n// answer, a 429 or a 5xx, wait what Retry-After says, or else 1, 2, 4, 8 seconds (capped at 30)\n// with jitter. Any other answer is final.\nfunc send(path string, payload []byte) *http.Response {\n\tfor attempt := 1; ; attempt++ {\n\t\treq, err := http.NewRequest(http.MethodPost, os.Getenv(\"MART_API_BASE\")+path, bytes.NewReader(payload))\n\t\tif err != nil {\n\t\t\tfail(err)\n\t\t}\n\t\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"MART_API_KEY\"))\n\t\treq.Header.Set(\"Content-Type\", \"application/json\")\n\t\tresp, err := client.Do(req)\n\t\tif err != nil && attempt == 5 {\n\t\t\treturn nil\n\t\t}\n\t\tif err == nil && (!retryable[resp.StatusCode] || attempt == 5) {\n\t\t\treturn resp\n\t\t}\n\t\twhat := \"got no answer\"\n\t\tbackoff := math.Min(30, math.Pow(2, float64(attempt-1)))\n\t\twait := backoff/2 + rand.Float64()*backoff/2\n\t\tif err == nil {\n\t\t\twhat = fmt.Sprintf(\"answered %d\", resp.StatusCode)\n\t\t\tif seconds, convErr := strconv.Atoi(resp.Header.Get(\"Retry-After\")); convErr == nil && seconds > 0 {\n\t\t\t\tif seconds > 60 {\n\t\t\t\t\treturn resp // too long to wait here: the caller says when to come back\n\t\t\t\t}\n\t\t\t\twait = float64(seconds)\n\t\t\t}\n\t\t\tresp.Body.Close()\n\t\t}\n\t\tfmt.Fprintf(os.Stderr, \"retry: attempt %d %s, waiting %.1f s\\n\", attempt, what, wait)\n\t\ttime.Sleep(time.Duration(wait * float64(time.Second)))\n\t}\n}\n\n// decode reads an answer into out. An error answer, or one that is not JSON (an edge error page),\n// stops with its status and error code.\nfunc decode(resp *http.Response, out any) {\n\tdefer resp.Body.Close()\n\traw, err := io.ReadAll(resp.Body)\n\tif err != nil {\n\t\tfail(err)\n\t}\n\tvar envelope struct {\n\t\tError *struct {\n\t\t\tCode string `json:\"code\"`\n\t\t} `json:\"error\"`\n\t}\n\tif resp.StatusCode >= 300 {\n\t\tcode := \"(not JSON)\"\n\t\tif json.Unmarshal(raw, &envelope) == nil && envelope.Error != nil {\n\t\t\tcode = envelope.Error.Code\n\t\t}\n\t\twait := \"\"\n\t\tif after := resp.Header.Get(\"Retry-After\"); after != \"\" {\n\t\t\twait = \", try again after \" + after + \" s\"\n\t\t}\n\t\tfail(fmt.Errorf(\"%d %s%s\", resp.StatusCode, code, wait))\n\t}\n\tif err := json.Unmarshal(raw, out); err != nil {\n\t\tfail(fmt.Errorf(\"%d (not JSON)\", resp.StatusCode))\n\t}\n}\n\nfunc fail(err error) {\n\tfmt.Fprintln(os.Stderr, \"error:\", err)\n\tos.Exit(1)\n}\n"
        - lang: java
          label: Java recipe
          source: >
            // Create an order that survives a timeout: retry with the same
            partner_reference and read the replay.

            // Java 17 or later, with Jackson. Needs MART_API_BASE,
            MART_API_KEY, MART_PRODUCT_ID, MART_STATE_ID and

            // MART_PARTNER_REFERENCE: your own id for this order, from your own
            system, so that running this again

            // can never make a second order. Run it as a single file: java -cp
            <the Jackson jars> create-an-order.java

            import com.fasterxml.jackson.databind.JsonNode;

            import com.fasterxml.jackson.databind.ObjectMapper;

            import java.io.IOException;

            import java.net.URI;

            import java.net.http.HttpClient;

            import java.net.http.HttpRequest;

            import java.net.http.HttpResponse;

            import java.time.Duration;

            import java.util.List;

            import java.util.Locale;

            import java.util.Map;

            import java.util.Set;

            import java.util.concurrent.ThreadLocalRandom;


            class CreateAnOrder {
                static final HttpClient CLIENT = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(10)).build();
                static final ObjectMapper JSON = new ObjectMapper();

                public static void main(String[] args) throws Exception {
                    String reference = System.getenv("MART_PARTNER_REFERENCE");
                    if (reference == null || reference.isEmpty()) {
                        fail("set MART_PARTNER_REFERENCE to your own id for this order");
                    }

                    // Decided once, before any attempt: every retry sends this same body.
                    String order = JSON.writeValueAsString(Map.of(
                            "partner_reference", reference,
                            "payment_type", "cod",
                            "products", List.of(Map.of("product_id", Integer.parseInt(System.getenv("MART_PRODUCT_ID")), "quantity", 1)),
                            "shipping_address", Map.of("customer_name", "Test Buyer", "phone", "0599000000",
                                    "state_id", Integer.parseInt(System.getenv("MART_STATE_ID")), "address", "Main street 1")));
                    HttpRequest request = HttpRequest.newBuilder(URI.create(System.getenv("MART_API_BASE") + "/api/v1/orders"))
                            .header("Authorization", "Bearer " + System.getenv("MART_API_KEY"))
                            .header("Content-Type", "application/json")
                            .timeout(Duration.ofSeconds(60))
                            .POST(HttpRequest.BodyPublishers.ofString(order))
                            .build();
                    System.out.println("reference: " + reference); // written down before the first attempt

                    HttpResponse<String> response = send(request);
                    if (response == null || response.statusCode() == 429 || response.statusCode() >= 500) {
                        String status = response == null ? "no answer" : response.statusCode() + when(response);
                        fail(status + "; the order may exist: run again later with MART_PARTNER_REFERENCE=" + reference);
                    }
                    JsonNode body = parse(response.body());
                    if (response.statusCode() >= 300 || body == null) {
                        fail(response.statusCode() + " " + code(body) + when(response));
                    }
                    // 201: created now. 200 with meta.idempotency_replay true: this order already existed.
                    JsonNode created = body.path("data").path("order");
                    System.out.println("order: " + created.path("partner_reference").asText());
                    System.out.println("status: " + created.path("status").asText());
                    System.out.printf(Locale.ROOT, "order total: %.2f%n", created.path("order_total").asDouble());
                    System.out.println("replay: " + body.path("meta").path("idempotency_replay").asBoolean());
                }

                static final Set<Integer> RETRYABLE = Set.of(429, 500, 502, 503, 504);

                /**
                 * Sends the same request until it is answered for good, and returns the last answer, or null when
                 * no attempt got one. Retries are your choice of numbers: at most 5 attempts; after no answer, a
                 * 429 or a 5xx, wait what Retry-After says, or else 1, 2, 4, 8 seconds (capped at 30) with jitter.
                 * Any other answer is final.
                 */
                static HttpResponse<String> send(HttpRequest request) throws InterruptedException {
                    for (int attempt = 1; ; attempt++) {
                        HttpResponse<String> response = null;
                        try {
                            response = CLIENT.send(request, HttpResponse.BodyHandlers.ofString());
                            if (!RETRYABLE.contains(response.statusCode()) || attempt == 5) {
                                return response;
                            }
                        } catch (IOException e) {
                            if (attempt == 5) {
                                return null;
                            }
                        }
                        double backoff = Math.min(30, Math.pow(2, attempt - 1));
                        double wait = backoff / 2 + ThreadLocalRandom.current().nextDouble() * backoff / 2;
                        String what = "got no answer";
                        if (response != null) {
                            what = "answered " + response.statusCode();
                            String after = response.headers().firstValue("Retry-After").orElse("");
                            if (after.matches("[0-9]+") && Long.parseLong(after) > 0) {
                                if (Long.parseLong(after) > 60) {
                                    return response; // too long to wait here: the caller says when to come back
                                }
                                wait = Long.parseLong(after);
                            }
                        }
                        System.err.printf(Locale.ROOT, "retry: attempt %d %s, waiting %.1f s%n", attempt, what, wait);
                        Thread.sleep((long) (wait * 1000));
                    }
                }

                /** The JSON body, or null for an answer that is not JSON (an edge error page). */
                static JsonNode parse(String text) {
                    try {
                        return JSON.readTree(text);
                    } catch (IOException e) {
                        return null;
                    }
                }

                static void fail(String message) {
                    System.err.println("error: " + message);
                    System.exit(1);
                }

                static String code(JsonNode body) {
                    return body == null ? "(not JSON)" : body.path("error").path("code").asText();
                }

                /** ", try again after N s" when the answer says how long to wait (Retry-After), else nothing. */
                static String when(HttpResponse<String> response) {
                    return response.headers().firstValue("Retry-After").map(s -> ", try again after " + s + " s").orElse("");
                }
            }
components:
  schemas:
    OrderCreateRequest:
      type: object
      required:
        - partner_reference
        - payment_type
        - shipping_address
        - products
      properties:
        payment_type:
          type: string
          enum:
            - cod
            - card
          description: >-
            REQUIRED: exact lowercase `cod` or `card` — never normalized, never
            defaulted. `card` charges your saved card synchronously for the
            server-computed total and needs per-key enablement
            (`card_not_enabled`) plus a reusable saved card on file
            (`card_not_on_file`). See https://mart.ps/api/docs#payments.
          example: cod
        partner_reference:
          type: string
          maxLength: 64
          description: >-
            Your own order id and the idempotency key, stored and matched
            byte-for-byte. Letters, digits, dot, underscore, hyphen; max 64
            characters; surrounding whitespace is rejected, never trimmed;
            unique per key. Identity is judged on a canonical form —
            https://mart.ps/api/docs#idempotency.
          example: '100245'
        shipping_address:
          type: object
          required:
            - customer_name
            - phone
            - state_id
            - address
          properties:
            customer_name:
              type: string
              example: محمد علي
            phone:
              type: string
              description: >-
                The recipient's primary (mobile) number — the one the courier
                calls.
              example: '0599123456'
            extra_phone:
              type: string
              nullable: true
              description: >-
                Optional second number for the recipient. Omitted and null are
                equivalent.
              example: '022345678'
            state_id:
              type: integer
              description: >-
                A leaf `states[].id` from GET /api/v1/states — a city `id` is
                not a `state_id`. Unknown or inactive returns 422 invalid_state.
              example: 812
            address:
              type: string
              example: شارع الإرسال، عمارة 12
            notes:
              type: string
              nullable: true
              description: Optional. Omitted and null are equivalent.
        products:
          type: array
          minItems: 1
          maxItems: 200
          description: 'Order is significant: error details reference the line index.'
          items:
            type: object
            required:
              - product_id
              - quantity
            properties:
              product_id:
                type: integer
                description: >-
                  Stable product identifier used in catalog synchronization and
                  order creation.
                example: 68516
              combination_id:
                type: integer
                nullable: true
                description: >-
                  REQUIRED for a product that has combinations; MUST be null (or
                  omitted) for one that does not. Mismatches return 422
                  combination_required / combination_not_allowed /
                  unknown_combination / combination_mismatch.
              quantity:
                type: integer
                minimum: 1
                example: 2
              price:
                type: number
                format: double
                exclusiveMinimum: true
                minimum: 0
                description: >-
                  Optional tax-included selling price per unit. Omitted or
                  `null` = sell at your group's catalog price, resolved at
                  creation. Must be at least `price.group_price` when your group
                  allows overrides (`price_below_minimum`), and must equal it
                  exactly when not (`price_override_not_allowed`). An explicit 0
                  is always invalid. Rejected with `card_price_not_allowed` on
                  card orders. See https://mart.ps/api/docs#orders.
                example: 120
        free_shipping:
          type: boolean
          default: false
          description: >-
            `true` = you absorb the delivery fee (needs your group's permission
            — `free_shipping_not_allowed` otherwise; `free_shipping_not_covered`
            when your margin cannot cover the fee, exact coverage passing).
            Rejected with `card_free_shipping_not_allowed` on card orders. See
            https://mart.ps/api/docs#orders.
    SuccessEnvelope:
      type: object
      required:
        - status
        - status_code
        - message
        - data
        - meta
        - error
      properties:
        status:
          type: string
          enum:
            - success
        status_code:
          type: integer
          example: 200
        message:
          type: string
          example: OK
        data:
          type: object
          description: >-
            One key named after the resource (products / product / states /
            categories / attributes / order / validation).
        meta:
          nullable: true
          type: object
        error:
          nullable: true
          type: object
          enum:
            - null
    Order:
      type: object
      required:
        - id
        - partner_reference
        - status
        - payment_type
        - created_at
        - order_total
        - cod_total
        - shipping_fee
        - free_shipping
        - payment_reference
        - reward
        - money
        - products
        - shipping_address
      properties:
        id:
          type: integer
          description: Mart's internal order id.
        partner_reference:
          type: string
        status:
          type: string
          enum:
            - processing
          description: >-
            API-owned order status vocabulary, not the raw store state. Orders
            are created as `processing`. The vocabulary may extend over time —
            treat it as an enum, never as free text.
        payment_type:
          type: string
          enum:
            - cod
            - card
          description: >-
            Echoed from the request, frozen at creation. ONE documented
            exception: a 200 replay of an order created before this field
            existed returns its frozen body verbatim, which omits `payment_type`
            — the order read always carries it instead.
        created_at:
          type: string
          format: date-time
        order_total:
          type: number
          format: double
          description: >-
            The payment-neutral total the order carries: SUM(price x quantity)
            plus the delivery fee unless you absorbed it. For card orders this
            is exactly the amount charged to your saved card.
        cod_total:
          type: number
          format: double
          description: >-
            What the courier collects: SUM(price x quantity) plus the delivery
            fee unless you absorbed it. Always 0.00 for card orders — the
            courier collects nothing.
        shipping_fee:
          type: number
          format: double
          description: The delivery fee for this destination, frozen at creation.
        free_shipping:
          type: boolean
        payment_reference:
          type: string
          nullable: true
          description: >-
            The gateway (Lahza) transaction reference actually charged for a
            card order — quote it when reconciling against your Lahza dashboard.
            Always null for cod.
        reward:
          type: object
          required:
            - gross_product_reward
            - shipping_deduction
            - net_reward
          description: >-
            How you are paid, frozen at creation and never recomputed — the sole
            settlement record for this order. Your reward is the margin above
            the catalog price; with `free_shipping: true` the delivery fee is
            deducted from it.
          properties:
            gross_product_reward:
              type: number
              format: double
              description: SUM((your price - catalog price) x quantity).
            shipping_deduction:
              type: number
              format: double
              description: >-
                The fee taken out of your margin; 0.00 unless free_shipping is
                true.
            net_reward:
              type: number
              format: double
              description: gross_product_reward - shipping_deduction. What you are owed.
        money:
          type: object
          required:
            - gross
            - shipping_deduction
            - net
            - earning_state
            - available_at
          description: >-
            What this order earns your account and when it can be counted.
            `gross`, `shipping_deduction` and `net` are the order's current
            settlement figures (`net` = `gross` - `shipping_deduction`), kept in
            step with Mart's staff edits. `available` means this order's money
            has matured, not that it can be withdrawn: a debt on the account can
            offset it. When `earning_state` is `reversed` every figure is
            `0.00`. In the creation response (201 and every replay) this block
            is a record of what was created, so it is always `pending` with a
            null `available_at`; read the order for the live state.
          properties:
            gross:
              type: number
              format: double
              description: The order's gross product reward.
            shipping_deduction:
              type: number
              format: double
              description: >-
                The delivery fee taken out of it; 0.00 unless free_shipping is
                true.
            net:
              type: number
              format: double
              description: gross - shipping_deduction. What this order earns your account.
            earning_state:
              type: string
              enum:
                - pending
                - held
                - available
                - reversed
              description: >-
                `pending`: not earned yet, or not known. `held`: earned, inside
                its hold. `available`: this order's money matured. `reversed`:
                the order was cancelled or returned and earns nothing.
            available_at:
              type: string
              format: date-time
              nullable: true
              description: >-
                When the held money matures; null unless the order is `held` or
                `available` and has a maturity date.
        products:
          type: array
          items:
            type: object
            required:
              - product_id
              - combination_id
              - quantity
              - price
              - group_price
            properties:
              product_id:
                type: integer
              combination_id:
                type: integer
                nullable: true
              quantity:
                type: integer
              price:
                type: number
                format: double
                description: Your selling price, as submitted.
              group_price:
                type: number
                format: double
                description: >-
                  The catalog price we used as the baseline for this line.
                  Returned so you can verify your own margin and predict
                  free-shipping coverage.
        shipping_address:
          type: object
          required:
            - customer_name
            - phone
            - extra_phone
            - state_id
            - address
            - notes
          description: >-
            Echo of what you sent; notes and extra_phone are null when not
            supplied.
          properties:
            customer_name:
              type: string
            phone:
              type: string
            extra_phone:
              type: string
              nullable: true
            state_id:
              type: integer
            address:
              type: string
            notes:
              type: string
              nullable: true
    OrderMeta:
      type: object
      required:
        - idempotency_replay
      description: Order-creation meta. Present on both the 201 and the 200 replay.
      properties:
        idempotency_replay:
          type: boolean
          description: >-
            false when this call created the order, true when it returned an
            order an identical earlier request had already created.
          example: false
    ErrorEnvelope:
      type: object
      required:
        - status
        - status_code
        - message
        - data
        - meta
        - error
      properties:
        status:
          type: string
          enum:
            - fail
        status_code:
          type: integer
          example: 422
        message:
          type: string
        data:
          nullable: true
          enum:
            - null
        meta:
          nullable: true
          enum:
            - null
        error:
          type: object
          required:
            - code
            - details
          properties:
            code:
              type: string
              enum:
                - missing_api_key
                - invalid_api_key
                - key_environment_mismatch
                - api_customer_not_configured
                - customer_group_not_allowed
                - insufficient_scope
                - product_not_found
                - order_not_found
                - route_not_found
                - method_not_allowed
                - invalid_parameter
                - invalid_state
                - rate_limit_exceeded
                - bad_request
                - orders_not_enabled
                - api_group_misconfigured
                - idempotency_conflict
                - unknown_product
                - product_not_offered
                - product_not_orderable
                - combination_required
                - combination_not_allowed
                - unknown_combination
                - combination_mismatch
                - duplicate_product
                - cart_minimum_not_met
                - price_below_minimum
                - price_override_not_allowed
                - insufficient_stock
                - free_shipping_not_covered
                - free_shipping_not_allowed
                - card_not_enabled
                - internal_error
                - order_not_cancellable
                - order_cancellation_not_configured
                - order_cancellation_in_progress
                - card_not_on_file
                - saved_card_invalid
                - card_price_not_allowed
                - card_free_shipping_not_allowed
                - card_declined
                - payment_gateway_unavailable
                - order_creation_in_progress
                - charge_amount_mismatch
                - invalid_cursor
                - cursor_expired
                - ledger_unavailable
                - statement_not_found
                - withdrawals_disabled
                - invalid_iban
                - invalid_account_holder_name
                - invalid_national_id
                - invalid_amount
                - amount_below_minimum
                - payout_method_missing
                - withdrawals_locked
                - too_many_open_withdrawals
                - insufficient_available
                - withdrawal_busy
                - withdrawal_not_found
                - withdrawal_not_cancellable
                - cash_not_allowed
                - payout_method_change_blocked
                - amount_above_cash_maximum
                - invalid_payout_method
                - bank_transfer_not_allowed
            details:
              description: >-
                Structured context (parameter name, supported values, retry
                hints). Empty array when none.
  headers:
    X-Mart-Environment:
      description: >-
        Which installation answered: `production` or `sandbox`. Present on every
        response; assert it once at startup.
      schema:
        type: string
        enum:
          - production
          - sandbox
    X-RateLimit-Limit:
      description: Limit of the tightest active window.
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Requests remaining in the tightest active window.
      schema:
        type: integer
    X-RateLimit-Reset:
      description: Epoch seconds when the tightest window resets.
      schema:
        type: integer
  responses:
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
      description: >-
        The request body is missing, is not valid JSON, or is not a JSON object
        (`bad_request`).
    Unauthorized:
      description: >-
        Missing or unusable API key (`missing_api_key`, `invalid_api_key`).
        Revoked and paused keys answer identically to unknown keys. A key issued
        for the other environment answers `key_environment_mismatch` before any
        lookup: `details.environment` names the environment you called
        (`production` or `sandbox`) — switch base URL or key. See the
        Environments note in the introduction.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    CardDeclined:
      description: >-
        The gateway declined the charge (`card_declined`) — no order was created
        and nothing was captured. Retrying the same reference makes a fresh
        attempt, never a double charge; `details.attempts_exhausted: true` means
        the reference is terminally declined. See
        https://mart.ps/api/docs#payments.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    ForbiddenGroup:
      description: >-
        The key customer is missing or inactive (`api_customer_not_configured`)
        or outside the allowed groups (`customer_group_not_allowed`). Group
        membership is re-checked on every request; access resumes when the
        customer rejoins an allowed group. This endpoint needs no scope that can
        be missing: a key without the order-writing permission is answered `422`
        `orders_not_enabled` by the endpoint itself.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    NotFound:
      description: >-
        The route does not exist (`route_not_found`) or the addressed resource
        does not (`product_not_found`). On the product detail route the two are
        distinct: a malformed id never matches the route; a well-formed unknown
        id answers `product_not_found`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    MethodNotAllowed:
      description: >-
        The method is not accepted on this endpoint (`method_not_allowed`). Read
        the `Allow` response header rather than assuming; `OPTIONS` is accepted
        everywhere and answered as a bodyless 204.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    IdempotencyConflict:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
      description: >-
        This `partner_reference` was already used for a DIFFERENT order
        (`idempotency_conflict`; `details.original_order_id`) — the original is
        never modified. Card orders can also answer 409
        `charge_amount_mismatch`: a captured charge no longer matches the
        current total. See https://mart.ps/api/docs#idempotency.
    OrderUnprocessable:
      description: >-
        Order validation failed — no order was created and the same
        `partner_reference` may be reused for the corrected request.
        Product-level codes carry `details.index` (zero-based position in
        `products`). Codes: `orders_not_enabled`, `api_group_misconfigured`,
        `invalid_parameter`, `invalid_state`, `unknown_product`,
        `product_not_offered`, `product_not_orderable`, `combination_required`,
        `combination_not_allowed`, `unknown_combination`,
        `combination_mismatch`, `duplicate_product`,
        `price_override_not_allowed`, `price_below_minimum`,
        `insufficient_stock`, `free_shipping_not_covered`,
        `free_shipping_not_allowed`, `card_not_enabled`, `card_not_on_file`,
        `saved_card_invalid`, `card_price_not_allowed`,
        `card_free_shipping_not_allowed`. What each means and how to clear it:
        https://mart.ps/api/docs#errors.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    TooManyRequests:
      description: >-
        Rate limit exceeded (`rate_limit_exceeded`). Carries `Retry-After`
        (seconds) plus the X-RateLimit-* trio of the exceeded window; day-window
        breaches advertise the day reset, not a 60-second retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    InternalError:
      description: >-
        Opaque server failure (`internal_error`). Details are logged server-side
        and never exposed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    PaymentGatewayUnavailable:
      description: >-
        Card charging is temporarily impossible: `payment_gateway_unavailable`
        (the gateway did not answer — retry the same `partner_reference` after
        `Retry-After`; never double-charges) or `order_creation_in_progress`
        (another request with this reference, or another order to the same
        recipient, is mid-flight — wait for `Retry-After` and retry; applies to
        cash-on-delivery orders too).
      headers:
        X-Mart-Environment:
          $ref: '#/components/headers/X-Mart-Environment'
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Authorization: Bearer <key>'
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-Api-Key

````

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