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

# Prices and price changes

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

Every product has three prices, each a snapshot of the moment you read it. Only `group_price` limits what you may sell at, and an incremental sync never sees it change.

```json theme={null}
"price": { "group_price": 55.99, "public_price": 59.99, "base_price": 99.99 },
"currency": "ILS"
```

All three are tax included, two decimals, in shekels, always present and never `null`. One `price` applies to every variant of the product.

## What is each price for?

| Price | What it is | Use |
| - | - | - |
| `group_price` | Your cost price: the final unit price for your account, with any temporary price applied. | Your cost basis, and the only floor for an order line. |
| `public_price` | What an ordinary visitor pays on mart.ps now. | A ready-made recommended retail price. Never a limit. |
| `base_price` | The catalogue price before any discount. Always the highest, or equal. | The "was" in "was X, now Y". |

When nothing is discounted, all three are equal: that is normal, not missing data.

## Which price is the floor of an order?

`group_price`, at the moment the order is created, not when you synced. A line `price` under it is refused with `422 price_below_minimum`; equal passes. A line without a price sells at `group_price`. Selling under `public_price` is allowed and normal.

Carry a margin over `group_price`, so a price that moves before your order costs margin instead of a refusal. An order sent with a stale price is refused, never silently accepted.

## Why can't an incremental sync see a price change?

`updated_after` filters on the product's last edit. A scheduled or temporary price starts and ends without any edit, so no timestamp moves, however often you poll.

Run a **full price refresh** at least daily, separate from your incremental sync:

1. Page through the whole catalogue with no `updated_after`.
2. Overwrite all three prices for every product you hold.
3. Recompute your selling price from the new `group_price`.

Your refresh interval is your worst-case staleness. After a sale period, refresh before trading normally: its end is as invisible as its start.

## How do you show a "was / now" price?

Use `base_price` as "was" and `public_price` as "now": they are the figures mart.ps shows the public. Never present `group_price` as a public discount; it is your trade price. Run your own promotions on your own margin.

## Common mistakes

* **"`group_price` is always under `public_price`."** Not always: on some products a discount for your account replaces a shop-wide promotion and comes out higher. Compare per product.
* **"A gap between `base_price` and `group_price` means a promotion."** It is mostly your standing discount.
* **"The API says when a discount ends."** It does not: there is no promotion flag or end date.

Your reward on a line is your selling price less `group_price`, times the quantity, frozen when the order is created. Nothing is re-priced later.


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