Skip to main content
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’s price is your selling price per unit, tax included.
  • Absent or null: sells at group_price, resolved and frozen at creation. An explicit 0 is refused.
  • Sent: at least price.group_price at creation, or 422 price_below_minimum (details.minimum). Equal passes.
  • Custom prices off (price_override_allowed: false on GET /account): only the exact group_price, or 422 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

  1. Make the reference once from your order id, and store it before the first attempt.
  2. 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.
  3. Quote it first if you show totals: POST /api/v1/orders/validate with the same body creates nothing. See Delivery prices and free shipping.
  4. Send it with a generous timeout, for example 60 seconds.
Every line is checked live at creation: product, variant, price floor, stock. One failure refuses the whole order and creates nothing.

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:
  • status is {id, name}, exactly what the customer sees. Treat id as opaque; never parse name.
  • Quantities, cod_total and free_shipping follow Mart’s changes. Each line’s price and the shipping_fee stay as created.
  • money is live: gross, shipping_deduction, net and earning_state: pending, held (with available_at), available or reversed (all 0.00). available means 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.