Skip to main content
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.
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.
  • 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.
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.