# Mart Partners > The documentation for Mart partners: how the partner programme pays you, how to use the partner panel, and how to integrate the Mart Partner API, with recipes in six languages. > ## 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)). - [Mart Partners documentation](https://docs.mart.ps/index.md): The Mart partner documentation: a short manual for running your partnership in the panel, and developer guides and recipes for the Mart Partner API. - [Get started as a Mart partner](https://docs.mart.ps/manual/get-started.md): See how a Mart order becomes money in four steps, then open the partner panel, follow your first order and get paid in your first days as a partner. - [How you earn on each order](https://docs.mart.ps/manual/how-you-earn.md): What each order earns you, which prices you may sell at, how card orders and free shipping work, and what a refused parcel can cost your account. - [Your money: balance, holds, movements and statements](https://docs.mart.ps/manual/your-money.md): Understand every figure on the Balance tab, when earnings become money you can withdraw, why your balance changed, and how to read a statement. - [Get paid: payout method and withdrawals](https://docs.mart.ps/manual/get-paid.md): Choose how Mart pays you, request a withdrawal of the money available to you, follow it until it is paid, collect cash at the office, or cancel a request. - [Why a withdrawal is refused, and what to do](https://docs.mart.ps/manual/why-a-withdrawal-can-be-refused.md): Look up each reason the panel refuses or Mart rejects a withdrawal request, the exact message you see, and what to change before you ask again. - [Your orders: follow, cancel and changes by Mart](https://docs.mart.ps/manual/your-orders.md): Find any order in the partner panel, read its status and earnings, learn how to cancel it, and see how a change by Mart affects what you earn. - [The partner panel, tab by tab](https://docs.mart.ps/manual/partner-panel.md): Look up what each tab of the partner panel shows and who sees it: Overview, Orders, Payments, Balance, API & Activity, and Reports & Help. - [Programme rules at a glance](https://docs.mart.ps/manual/programme-rules.md): The rules of the Mart partner programme that decide what you earn and when you are paid, on one page, each linked to the page that explains it. - [Get help from Mart](https://docs.mart.ps/manual/get-help.md): Contact Mart about an order, your money or the API, and send the details that let Mart answer the first time: the reference, the time and the message. - [Glossary](https://docs.mart.ps/manual/glossary.md): Look up any term used in the Mart partner documentation, from cost price and on hold to payout method and partner reference, each in one sentence. - [Changelog](https://docs.mart.ps/changelog.md): Every change to the Mart Partner API, the partner panel and how money works, newest first; filter by API, Money, Orders or Panel, or follow the RSS feed. - [Quickstart: from a sandbox key to production](https://docs.mart.ps/developers/quickstart.md): Make your first call in the Mart sandbox, quote, create and cancel a test order safely, then switch to production by changing only the base URL and key. - [Authenticate, scopes and keeping your key safe](https://docs.mart.ps/developers/authenticate.md): Send your API key on every request, check the scopes it holds, read what your account may do, and follow the rules that keep your key and money safe. - [Connect your AI tool to this documentation](https://docs.mart.ps/developers/connect-your-ai-tool.md): Connect Claude, Cursor, VS Code or another AI tool to the Mart Partners docs through MCP, llms.txt or Markdown pages, so its answers follow the rules. - [Sync the catalogue: identifiers, stock and schedule](https://docs.mart.ps/developers/catalogue/sync.md): Import the Mart catalogue once, key it on the right identifiers, then keep products, stock and offered items fresh with a schedule that fits your limits. - [Prices and price changes](https://docs.mart.ps/developers/catalogue/prices.md): Understand the three prices on every product, why an incremental sync never sees a price change, and how a daily full refresh keeps your prices right. - [Create an order safely: idempotency, retries, replay](https://docs.mart.ps/developers/orders/create-an-order.md): 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. - [Delivery prices, quotes and free shipping](https://docs.mart.ps/developers/orders/delivery-prices.md): Show delivery prices per town before checkout, quote the whole order so your totals match the created order, and fund free shipping from your margin. - [Cancel an order through the API](https://docs.mart.ps/developers/orders/cancel-an-order.md): Cancel an order you created by its partner_reference, retry safely after a timeout, and handle each answer so your store and Mart stay in step. - [Balance, movements, statements and reports](https://docs.mart.ps/developers/money/balance-and-statements.md): Read your balance, list the movements behind it, fetch closed statements and your order totals through the API, and show each figure with its meaning. - [Payout method and withdrawals](https://docs.mart.ps/developers/money/payout-and-withdrawals.md): Save your payout method, then request, follow and cancel withdrawals through the API, with idempotency keys so a retried request is never paid twice. - [Follow events on your account](https://docs.mart.ps/developers/money/events.md): Follow your orders, movements, withdrawals and payout method as one feed of events, store the cursor right, and process each event once after retries. - [Request limits and a schedule that fits them](https://docs.mart.ps/developers/operate/request-limits.md): Look up how request limits work per key, per minute and per day, how to read the rate-limit headers, and a sync schedule that stays inside your ceiling. - [Handle errors: retry, fix or escalate](https://docs.mart.ps/developers/operate/handle-errors.md): Handle every failed call by its error code: read the envelope, retry only what can succeed, fix and resend a refused order, and know when to alert a person. - [Error catalog: every Mart Partner API error code](https://docs.mart.ps/developers/operate/error-catalog.md): Look up every error code the Mart Partner API can return, with its HTTP status, what it means and what to do next, grouped by the area it comes from. - [Recipe: make your first authenticated call](https://docs.mart.ps/recipes/first-call.md): Make your first authenticated call to the Mart Partner API in cURL, TypeScript, Python, PHP, Go or Java, with a timeout and the key read from the environment. - [Recipe: sync the whole catalogue into your store](https://docs.mart.ps/recipes/sync-the-catalogue.md): 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. - [Recipe: show delivery prices and quote an order](https://docs.mart.ps/recipes/delivery-prices-and-quote.md): Fetch the delivery price brackets for a town and quote a whole order before you create it, in six languages plus Next.js, FastAPI, Laravel and Spring. - [Recipe: create an order with safe retries](https://docs.mart.ps/recipes/create-an-order.md): Create an order that survives a timeout: send it once, retry with the same partner_reference, and read the replay, in six languages and four frameworks. - [Recipe: cancel an order by its partner reference](https://docs.mart.ps/recipes/cancel-an-order.md): Cancel an order by its partner reference and handle each possible answer, in cURL, TypeScript, Python, PHP, Go or Java, with a timeout on every call. - [Recipe: follow your account's events, once each](https://docs.mart.ps/recipes/follow-events.md): Catch up on the events feed of your account after each run, skipping events you already handled and pausing between pages, in six languages and four frameworks. - [Recipe: read your balance and show each figure](https://docs.mart.ps/recipes/read-your-balance.md): Read your balance through the API and show each figure with its own meaning, handling an unavailable balance, in cURL, TypeScript, Python, PHP, Go or Java. - [Recipe: request a withdrawal with an idempotency key](https://docs.mart.ps/recipes/request-a-withdrawal.md): Request a withdrawal of available money with an idempotency key, so that a retry after a timeout returns the original request instead of a second one. - [API reference: base URLs, authentication, envelope](https://docs.mart.ps/api-reference/overview.md): Look up the base URLs, how to authenticate, the shape every Mart Partner API answer shares, and the conventions for money, time and paging. - [List products](https://docs.mart.ps/api-reference/products/list-products.md): One page of the catalog, priced for your account, with stock and combinations on every row. Returns both active and inactive products (each row carries `status`); zero-stock rows remain with `in_stock: false`. Sync guidance — including why incremental syncs can never detect price changes: https://ma… - [List offered product ids](https://docs.mart.ps/api-reference/products/list-product-ids.md): The ids of the products your account is offered, ascending, and nothing else. Use it to notice what entered or left your offer: pull the ids now and then (or when `meta.offer_changed_at` moves), compare them with the ids you hold, drop the ones that are gone, and fetch the new ones with `GET /produc… - [Get product details](https://docs.mart.ps/api-reference/products/get-product.md): The full product record: text fields and every combination with its stock and images. Pricing is product-level — the single `price` object applies to every combination. A malformed id never matches the route (`route_not_found`); a well-formed id with no such product answers `product_not_found`. - [List product categories](https://docs.mart.ps/api-reference/categories/list-categories.md): The category vocabulary behind the products endpoints (Meta's product taxonomy), flat, ordered by `category_name` — no pagination (`meta` is `null`). `category_id` is the exact value the products `category_id` filter accepts. - [List attribute groups and values](https://docs.mart.ps/api-reference/attributes/list-attributes.md): The attribute vocabulary behind combination `attributes`, grouped by attribute group; only values actually in use are served — no pagination (`meta` is `null`). `values[].attribute_id` equals the `id` the products endpoints emit in `combinations[].attributes[]`; join by that id. - [List delivery destinations](https://docs.mart.ps/api-reference/delivery/list-states.md): All delivery destinations as a two-level tree: cities, each holding its deliverable states — no pagination (`meta` is `null`). Only a leaf `states[].id` is a valid `shipping_address.state_id`; names are not unique, so match on `id`. Every state carries `delivery`: the fee brackets, by products total… - [List orders](https://docs.mart.ps/api-reference/orders/list-orders.md): One page of your own orders, as summaries: the order's status, payment type, dates and totals, the same values `GET /api/v1/orders/{partner_reference}` returns for that order. Lines, delivery address, payment reference, cancellation and money stay on that single read. Ownership is your key: you neve… - [Create order](https://docs.mart.ps/api-reference/orders/create-order.md): 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 (… - [Validate an order without creating it](https://docs.mart.ps/api-reference/orders/validate-order.md): The dry-run twin of `POST /api/v1/orders`: same body, same validation pipeline, byte-identical error envelopes — but nothing is written, reserved or consumed. Idempotency is predicted, not processed. A valid order answers a `quote`: its products total, delivery fee, totals and reward exactly as a cr… - [Cancel an order by partner reference](https://docs.mart.ps/api-reference/orders/cancel-order-by-partner-reference.md): Cancels an order you created, addressed by YOUR reference. Same permission as creation. Mart's configuration decides which states are cancellable (409 `order_not_cancellable` past that point). Repeating is safe and IS the retry procedure: an already-cancelled order answers 200 with `already_cancelle… - [Get order by partner reference](https://docs.mart.ps/api-reference/orders/get-order-by-partner-reference.md): Returns YOUR order, addressed by the reference you submitted at creation. Key-scoped: an unknown or foreign reference answers the identical 404 `order_not_found`. Live view with frozen prices: `status`, quantities and `cod_total` are current; each item's `price` and the `shipping_fee` stay the creat… - [Events](https://docs.mart.ps/api-reference/money/list-events.md): What happened to your account, oldest first, as a feed with a cursor: orders, earnings and other ledger movements, withdrawals and your payout method. Store `meta.next_cursor` and ask again with `after=`; a replay from any cursor shows every later event, in the same order, with no gaps. `next_cu… - [Balance](https://docs.mart.ps/api-reference/money/get-balance.md): Your account's money in one read: the balance, what is available now, what is held until it matures, the next maturity, and any amount you owe. `available` is what may be taken out now. `held` is earned but not yet matured; `next_maturity` says when the next part of it becomes available and how much… - [Ledger](https://docs.mart.ps/api-reference/money/list-ledger.md): Your account's movements, newest first, one page at a time. `amount` is signed: a credit to you is positive, a payment to you or a deduction is negative. `type` is `earning`, `reversal`, `payment`, `adjustment` or `charge`; a type this document does not list yet may appear as `other`, so treat an un… - [List statements](https://docs.mart.ps/api-reference/money/list-statements.md): Your finalized statements, newest first, one page at a time. A statement is a balance snapshot for a period: `opening` and `closing` are the balance at the start and at the end of it, and they include earnings that were still held. They are not an amount that could be paid out; read `available` on t… - [Get statement](https://docs.mart.ps/api-reference/money/get-statement.md): One finalized statement and the movements that belong to it. `movements` are the entries recorded in the statement's period, from `period_start` up to but not including `period_end`, oldest first, in the same shape as the ledger. A movement belongs to the period in which it was recorded, which can d… - [Your payout method](https://docs.mart.ps/api-reference/money/get-payout-method.md): How your money is paid, in full: it is yours, and only your key reads it. `method` is `bank` (the IBAN and account holder) or `cash` (collected at Mart's office by the person named in `account_holder_name`, with `pickup_instructions` saying where and when; `iban` is `null`). A withdrawal is paid by… - [Save your payout method](https://docs.mart.ps/api-reference/money/put-payout-method.md): Saves how your money is paid. For a bank transfer send `iban` and `account_holder_name`, and optionally `national_id`; `method` may be left out, as before cash existed. For cash at Mart's office send `"method": "cash"`, the collector's full name as `account_holder_name` and optionally their ID numbe… - [List your withdrawals](https://docs.mart.ps/api-reference/money/list-withdrawals.md): Your withdrawal requests, newest first, one page at a time. Filter with `status`. Each item is `{withdrawal_id, amount, status, iban, reject_reason, requested_at, approved_at, paid_at, method, requested_amount}`. `iban` is the one fixed when the request was approved and is null before, and always fo… - [Ask to withdraw](https://docs.mart.ps/api-reference/money/create-withdrawal.md): Asks Mart to pay out part of what is available. Send `amount` (shekels, at most two decimals) and your own `idempotency_key`. The request is checked in this order: a repeat of an earlier request is answered first, whatever has changed since; then withdrawals must be enabled for your account (`403` `… - [Get a withdrawal](https://docs.mart.ps/api-reference/money/get-withdrawal.md): One of your withdrawal requests, in the shape of a list item. An id that belongs to another account answers exactly as an id that does not exist: `404` `withdrawal_not_found`. Full behaviour: https://mart.ps/api/docs#money/withdrawal. - [Cancel a withdrawal](https://docs.mart.ps/api-reference/money/cancel-withdrawal.md): Takes a request back while it is still `requested`: its amount is released at once. Cancelling one that is already `cancelled` answers `200` again and changes nothing. An `approved`, `paid` or `rejected` request answers `409` `withdrawal_not_cancellable`. An id that belongs to another account answer… - [Reports summary](https://docs.mart.ps/api-reference/reports/get-reports-summary.md): Your own order totals over a recent range: the number and value of orders, the average order value, a breakdown by calendar month (shop-local months, newest first) with the cash-on-delivery and card split and the number cancelled, and the products you order most. Values are order totals, nothing els… - [Your account](https://docs.mart.ps/api-reference/account/get-account.md): Your own account in one read: the shop name, whether it is active, paused or closed, what your key may do, your request limits, whether a payout method is saved, the withdrawal rules and whether the money endpoints can be read right now. The shape is the same for every partner. It always answers `20… ## OpenAPI Specs - [openapi](/openapi.json) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.