POST /api/v1/orders creates an order at your selling prices. After a timeout, a lost answer or any 5xx, and after a 429 once Retry-After has passed, resend the same body with the same partner_reference. Never make a new reference to try again. You need orders:write, with order creation enabled for the key.
Build the body
Mart works out the courier’s collection, the currency, the courier and the delivery fee: fields you send for them, and any unknown field, are ignored. Errors name a line by
index, its zero-based position.
Line prices
A line’sprice is your selling price per unit, tax included.
- Absent or
null: sells atgroup_price, resolved and frozen at creation. An explicit0is refused. - Sent: at least
price.group_priceat creation, or422 price_below_minimum(details.minimum). Equal passes. - Custom prices off (
price_override_allowed: falseonGET /account): only the exactgroup_price, or422 price_override_not_allowed(details.expected). Mart never replaces a price you sent. - Card order: never send a price (
422 card_price_not_allowed).
Send it
- Make the reference once from your order id, and store it before the first attempt.
- Store the exact body by reference. A retry sends those stored bytes: a rebuilt body can pick up a new price or order and turn a safe retry into a
409. - Quote it first if you show totals:
POST /api/v1/orders/validatewith the same body creates nothing. See Delivery prices and free shipping. - Send it with a generous timeout, for example 60 seconds.
Act on the answer
Why is a retry safe?
The same reference returns the original order if it was created, or creates it now: exactly one order either way. The replay check runs before any catalogue check, so a retry is never refused for stock, price or status. Mart compares a canonical form of the body. It ignores key order, extra spaces, number format (120, "120.00"), boolean spelling (true, "1", "yes"), Unicode composition, unknown fields, and absent versus null. A change to partner_reference, shipping_address, free_shipping or products, including their order, does count. An order created before payment_type existed replays against its original body, so adding the field to that reference answers 409.
After a 422 price_below_minimum: read the product again, update your price from the new group_price, confirm a higher price with your customer, then resend under the same reference.
Read the answer
data.order has id, partner_reference, status, created_at, cod_total (what the courier collects), shipping_fee, free_shipping, reward, money, products (with each line’s frozen group_price) and shipping_address.
A replay never changes. It returns the creation answer byte for byte, including its status and its money (earning_state: pending). Never poll it. Keep the creation answer for settlement: the order read does not repeat reward.
Read an order back
GET /api/v1/orders/{partner_reference} returns the live order:
statusis{id, name}, exactly what the customer sees. Treatidas opaque; never parsename.- Quantities,
cod_totalandfree_shippingfollow Mart’s changes. Each line’spriceand theshipping_feestay as created. moneyis live:gross,shipping_deduction,netandearning_state:pending,held(withavailable_at),availableorreversed(all0.00).availablemeans the order matured, not that you can withdraw it: a debt can offset it.- Another partner’s reference answers
404 order_not_found, like one that does not exist.
GET /api/v1/orders lists orders, 50 per page by default, at most 100, filtered by status, payment_type, created_from, created_to and updated_since. To follow many orders, use events.
The full retry loop in six languages: Create an order.