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

# Recipe: sync the whole catalogue into your store

> Page through the whole Mart catalogue and store every product by its identifiers, in six languages, staying inside your daily request ceiling as you go.

This recipe reads every product your key is offered with `GET /api/v1/products`, 100 per page, pausing a second between pages, and prints each page's count and the total. Replace the comment "Store the products here" with your own storage, keyed by `product_id`.

## Prerequisites

* **`MART_API_KEY`**: your API key, with the `catalog:read` scope.
* **`MART_API_BASE`**: `https://sandbox.mart.ps` while you build, `https://mart.ps` when you go live.

**One runtime:** cURL 7.84 or later with `jq`; Node 22.18 or later, which runs the `.ts` file as it is; Python 3.9 or later with `httpx`; PHP 7.4 or later with its curl extension; Go 1.22 or later; or Java 17 or later with Jackson (`jackson-databind`). Each file reads its variables from the environment and sets a timeout on every call. Run it on your own server: a browser or an app never holds the key.

## Run the recipe

```bash cURL theme={null}
#!/usr/bin/env bash
# Sync the catalogue: read every page of the products your key is offered.
# Needs MART_API_BASE and MART_API_KEY.
set -euo pipefail

# api PATH: sets $body, or prints the status and error code and stops.
api() {
  local response status retry_after
  response=$(curl --silent --show-error --max-time 30 \
    --header @<(printf 'Authorization: Bearer %s\n' "$MART_API_KEY") \
    --write-out '\n%{http_code} %header{retry-after}' "$MART_API_BASE$1") || { echo "error: no answer" >&2; exit 1; }
  read -r status retry_after <<<"${response##*$'\n'}"
  body=${response%$'\n'*}
  if [ "$status" -ge 300 ]; then
    echo "error: $status $(jq -r '.error.code' <<<"$body" 2>/dev/null || echo '(not JSON)')${retry_after:+, try again after $retry_after s}" >&2
    exit 1
  fi
}

page=1
total=0
while true; do
  api "/api/v1/products?limit=100&page=$page"
  count=$(jq '.data.products | length' <<<"$body")
  # Store the products here: jq -c '.data.products[]' prints one per line.
  total=$((total + count))
  echo "page $page: $count products"
  [ "$(jq -r '.meta.pagination.has_next' <<<"$body")" = true ] || break
  page=$((page + 1))
  sleep 1 # a pause between pages, so a full sync never arrives as one burst
done
echo "products: $total"
```

```typescript TypeScript theme={null}
// Sync the catalogue: read every page of the products your key is offered.
// Node 22.18 or later runs this .ts file as it is. Needs MART_API_BASE and MART_API_KEY.
const base = process.env.MART_API_BASE;
const key = process.env.MART_API_KEY;
if (!base || !key) throw new Error('Set MART_API_BASE and MART_API_KEY');

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

async function get(path: string): Promise<any> {
  const response = await fetch(`${base}${path}`, {
    headers: { Authorization: `Bearer ${key}` },
    signal: AbortSignal.timeout(30_000),
  });
  const body = await response.json().catch(() => null); // an edge error page is not JSON
  if (!response.ok || body === null) {
    const retryAfter = response.headers.get('retry-after');
    console.error(`error: ${response.status} ${body?.error?.code ?? '(not JSON)'}${retryAfter ? `, try again after ${retryAfter} s` : ''}`);
    process.exit(1);
  }
  return body;
}

let page = 1;
let total = 0;
while (true) {
  const body = await get(`/api/v1/products?limit=100&page=${page}`);
  const products: any[] = body.data.products;
  // Store the products here.
  total += products.length;
  console.log(`page ${page}: ${products.length} products`);
  if (!body.meta.pagination.has_next) break;
  page++;
  await sleep(1000); // a pause between pages, so a full sync never arrives as one burst
}
console.log(`products: ${total}`);
```

```python Python theme={null}
"""Sync the catalogue: read every page of the products your key is offered. Python 3.9+, httpx.

Needs MART_API_BASE and MART_API_KEY.
"""
import os
import sys
import time

import httpx

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


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


def check(response: httpx.Response) -> dict:
    body = body_of(response)
    if response.is_error or body is None:
        code = body["error"]["code"] if body else "(not JSON)"
        retry_after = response.headers.get("Retry-After")
        sys.exit(f"error: {response.status_code} {code}" + (f", try again after {retry_after} s" if retry_after else ""))
    return body


page = 1
total = 0
while True:
    body = check(client.get("/api/v1/products", params={"limit": 100, "page": page}))
    products = body["data"]["products"]
    # Store the products here.
    total += len(products)
    print(f"page {page}: {len(products)} products")
    if not body["meta"]["pagination"]["has_next"]:
        break
    page += 1
    time.sleep(1)  # a pause between pages, so a full sync never arrives as one burst
print(f"products: {total}")
```

```php PHP theme={null}
<?php
// Sync the catalogue: read every page of the products your key is offered. PHP 7.4 or later, with
// the curl extension. Needs MART_API_BASE and MART_API_KEY.
$base = getenv('MART_API_BASE');
$key = getenv('MART_API_KEY');

/**
 * 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];
}

/** A GET that must succeed: the decoded body, or the status and error code, and stop. */
function get(string $url, string $key): array
{
    [$status, $headers, $raw] = request('GET', $url, $key);
    $body = json_decode($raw, true); // null for an answer that is not JSON (an edge error page)
    if ($status < 200 || $status >= 300 || !is_array($body)) {
        $code = $status === 0 ? 'no answer' : $status . ' ' . ($body['error']['code'] ?? '(not JSON)');
        $wait = isset($headers['retry-after']) ? ", try again after {$headers['retry-after']} s" : '';
        fwrite(STDERR, "error: $code$wait\n");
        exit(1);
    }

    return $body;
}

$page = 1;
$total = 0;
while (true) {
    $body = get("$base/api/v1/products?limit=100&page=$page", $key);
    $products = $body['data']['products'];
    // Store the products here.
    $total += count($products);
    echo "page $page: " . count($products) . " products\n";
    if (!$body['meta']['pagination']['has_next']) {
        break;
    }
    $page++;
    sleep(1); // a pause between pages, so a full sync never arrives as one burst
}
echo "products: $total\n";
```

```go Go theme={null}
//go:build ignore

// Sync the catalogue: read every page of the products your key is offered. Go 1.22 or later.
// Needs MART_API_BASE and MART_API_KEY. Run it with: go run sync-the-catalogue.go
package main

import (
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
	"time"
)

var client = &http.Client{Timeout: 30 * time.Second}

func main() {
	page, total := 1, 0
	for {
		var body struct {
			Data struct {
				Products []json.RawMessage `json:"products"`
			} `json:"data"`
			Meta struct {
				Pagination struct {
					HasNext bool `json:"has_next"`
				} `json:"pagination"`
			} `json:"meta"`
		}
		get(fmt.Sprintf("/api/v1/products?limit=100&page=%d", page), &body)
		// Store the products here: decode each json.RawMessage into your own type.
		total += len(body.Data.Products)
		fmt.Printf("page %d: %d products\n", page, len(body.Data.Products))
		if !body.Meta.Pagination.HasNext {
			break
		}
		page++
		time.Sleep(time.Second) // a pause between pages, so a full sync never arrives as one burst
	}
	fmt.Println("products:", total)
}

// get sends one GET and decodes its answer into out.
func get(path string, out any) {
	req, err := http.NewRequest(http.MethodGet, os.Getenv("MART_API_BASE")+path, nil)
	if err != nil {
		fail(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("MART_API_KEY"))
	resp, err := client.Do(req)
	if err != nil {
		fail(fmt.Errorf("no answer: %v", err))
	}
	decode(resp, out)
}

// decode reads an answer into out. An error answer, or one that is not JSON (an edge error page),
// stops with its status and error code.
func decode(resp *http.Response, out any) {
	defer resp.Body.Close()
	raw, err := io.ReadAll(resp.Body)
	if err != nil {
		fail(err)
	}
	var envelope struct {
		Error *struct {
			Code string `json:"code"`
		} `json:"error"`
	}
	if resp.StatusCode >= 300 {
		code := "(not JSON)"
		if json.Unmarshal(raw, &envelope) == nil && envelope.Error != nil {
			code = envelope.Error.Code
		}
		wait := ""
		if after := resp.Header.Get("Retry-After"); after != "" {
			wait = ", try again after " + after + " s"
		}
		fail(fmt.Errorf("%d %s%s", resp.StatusCode, code, wait))
	}
	if err := json.Unmarshal(raw, out); err != nil {
		fail(fmt.Errorf("%d (not JSON)", resp.StatusCode))
	}
}

func fail(err error) {
	fmt.Fprintln(os.Stderr, "error:", err)
	os.Exit(1)
}
```

```java Java theme={null}
// Sync the catalogue: read every page of the products your key is offered. Java 17 or later, with Jackson.
// Needs MART_API_BASE and MART_API_KEY. Run it as a single file: java -cp <the Jackson jars> sync-the-catalogue.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.Locale;

class SyncTheCatalogue {
    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 {
        int page = 1;
        int total = 0;
        while (true) {
            JsonNode body = get("/api/v1/products?limit=100&page=" + page);
            JsonNode products = body.path("data").path("products");
            // Store the products here.
            total += products.size();
            System.out.println("page " + page + ": " + products.size() + " products");
            if (!body.path("meta").path("pagination").path("has_next").asBoolean()) {
                break;
            }
            page++;
            Thread.sleep(1000); // a pause between pages, so a full sync never arrives as one burst
        }
        System.out.println("products: " + total);
    }

    /** One GET that must succeed: the decoded body, or the status and error code, and stop. */
    static JsonNode get(String path) throws InterruptedException {
        HttpRequest request = HttpRequest.newBuilder(URI.create(System.getenv("MART_API_BASE") + path))
                .header("Authorization", "Bearer " + System.getenv("MART_API_KEY"))
                .timeout(Duration.ofSeconds(30))
                .GET()
                .build();
        HttpResponse<String> response;
        try {
            response = CLIENT.send(request, HttpResponse.BodyHandlers.ofString());
        } catch (IOException e) {
            fail("no answer: " + e.getMessage());
            return null;
        }
        JsonNode body = parse(response.body());
        if (response.statusCode() >= 300 || body == null) {
            fail(response.statusCode() + " " + code(body) + when(response));
        }
        return body;
    }

    /** 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("");
    }
}
```

## Verify the result

```text theme={null}
page 1: 100 products
page 2: 37 products
products: 137
```

The total counts inactive and out-of-stock products too; compare it with the ids from `GET /api/v1/products/ids`. An incremental sync cannot see a price change, so run this full sync on a schedule as well: see [Sync the catalogue](https://docs.mart.ps/developers/catalogue/sync.md).

## Troubleshooting

| What you see | What to do |
| - | - |
| `422` `invalid_parameter` | Keep `limit` at 100 and `page` a positive whole number. |

| Any recipe | What to do |
| - | - |
| `401` `missing_api_key` or `invalid_api_key` | Check that `MART_API_KEY` holds the whole key. A key still refused needs a replacement from Mart. |
| `401` `key_environment_mismatch` | Point `MART_API_BASE` at the environment that issued the key. |
| `403` `insufficient_scope` | Ask Mart to add the scope in `details.required_scope`. |
| `429` `rate_limit_exceeded` | Wait the `Retry-After` the error line shows, then run it again. |
| `error: no answer`, or a timeout | Check `MART_API_BASE` and your network. |
| `error:` with `(not JSON)` | A proxy or firewall answered, not the API. Check `MART_API_BASE` and your network. |

Every other code is in the [error catalog](https://docs.mart.ps/developers/operate/error-catalog.md).


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