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

# Delivery prices, quotes and free shipping

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

Read each town's fee brackets from `GET /api/v1/states`, quote the final basket with `POST /api/v1/orders/validate`, then create the order with the same body. The delivery fee depends on the town and the products total.

## Read the towns and their brackets

`GET /api/v1/states` (scope `catalog:read`) returns cities, each with its towns as `id`, `name` and `delivery`. It is not paged.

* Send a town's `id` as `shipping_address.state_id`. A city `id`, or an unknown or inactive town, refuses the order with `422 invalid_state`.
* Town names repeat: offer a picker and match on `id`.
* Re-read it at least daily: fees change.

```json theme={null}
"delivery": {
  "available": true,
  "fees": [
    { "from_total": 0.0, "to_total": 300.0, "fee": 35.0 },
    { "from_total": 300.0, "to_total": null, "fee": 20.0 }
  ]
}
```

The numbers are an illustration; read your own. The brackets are your account's own.

## Show the delivery price

1. Work out the products total: each line's price times its quantity, tax included, delivery excluded. Use `group_price` for a line sent without a price.
2. Take the bracket where `from_total` ≤ total \< `to_total`. A total equal to `to_total` pays the next bracket; `to_total: null` has no upper end.
3. Show its `fee`.

A town with `available: false` and empty `fees` cannot be delivered to right now: do not offer it.

## Quote the order

Send the exact body you will create to `POST /api/v1/orders/validate` (scope `orders:write`). It runs every check a create runs, and creates, reserves and charges nothing.

```json theme={null}
"quote": {
  "products_total": 240.0,
  "shipping_fee": 35.0,
  "free_shipping": true,
  "order_total": 240.0,
  "cod_total": 240.0,
  "reward": { "gross": 40.0, "shipping_deduction": 35.0, "net": 5.0 }
}
```

* `order_total` is what a card order is charged; `cod_total` is what the courier collects, `0.00` on a card order.
* `reward` is the `gross`, `shipping_deduction` and `net` a create would freeze now.
* A body that would be refused gets the same error a create would.
* `quote` is `null` when your `partner_reference` already names an order with the same content: read that order instead.

Then create with the same body. The create answer is binding: prices, stock and fees can move in between, so show your customer the created figures if they differ.

## Free shipping from your margin

`free_shipping: true` means you pay the delivery fee from your reward, and your customer pays the products only.

```text theme={null}
gross               = SUM((your price - group_price) x quantity)
shipping_deduction  = the delivery fee   (0.00 without free shipping)
net                 = gross - shipping_deduction      accepted when net >= 0.00
```

The numbers are an illustration: 2 units at 120.00 with a `group_price` of 100.00 and a fee of 35.00 give a gross of 40.00 and a net of 5.00. At 105.00 per unit the gross is 10.00, and the order is refused with `422 free_shipping_not_covered`.

* A refusal reports `details.gross_reward`, `details.shipping_fee` and `details.shortfall`. Raise your prices, or resend with `free_shipping: false`, under the same `partner_reference`.
* `free_shipping_allowed: false` on `GET /account` means `422 free_shipping_not_allowed`.
* A card order never has free shipping: `422 card_free_shipping_not_allowed`.

After creation, the per-unit margin and the delivery fee are frozen, and the reward follows the quantity that remains. If Mart reduces the order so the reward no longer covers the fee: before the parcel leaves, free shipping ends, the frozen fee goes back on the customer's order and `shipping_deduction` returns to `0.00`; after it leaves, the customer's charge never changes and `net` becomes `0.00`. `GET /api/v1/orders/{partner_reference}` shows the live `money` and `free_shipping`.

## Check the result

* The created `shipping_fee` equals the fee you showed, or you showed the new figure.
* On a cash-on-delivery order, `cod_total` is `products_total` with free shipping, and `products_total` plus `shipping_fee` without.

The same flow in six languages and four frameworks: [Delivery prices and quote](https://docs.mart.ps/recipes/delivery-prices-and-quote.md).


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