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
idasshipping_address.state_id. A cityid, or an unknown or inactive town, refuses the order with422 invalid_state. - Town names repeat: offer a picker and match on
id. - Re-read it at least daily: fees change.
Show the delivery price
- Work out the products total: each line’s price times its quantity, tax included, delivery excluded. Use
group_pricefor a line sent without a price. - Take the bracket where
from_total≤ total <to_total. A total equal toto_totalpays the next bracket;to_total: nullhas no upper end. - Show its
fee.
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 toPOST /api/v1/orders/validate (scope orders:write). It runs every check a create runs, and creates, reserves and charges nothing.
order_totalis what a card order is charged;cod_totalis what the courier collects,0.00on a card order.rewardis thegross,shipping_deductionandneta create would freeze now.- A body that would be refused gets the same error a create would.
quoteisnullwhen yourpartner_referencealready names an order with the same content: read that order instead.
Free shipping from your margin
free_shipping: true means you pay the delivery fee from your reward, and your customer pays the products only.
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_feeanddetails.shortfall. Raise your prices, or resend withfree_shipping: false, under the samepartner_reference. free_shipping_allowed: falseonGET /accountmeans422 free_shipping_not_allowed.- A card order never has free shipping:
422 card_free_shipping_not_allowed.
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_feeequals the fee you showed, or you showed the new figure. - On a cash-on-delivery order,
cod_totalisproducts_totalwith free shipping, andproducts_totalplusshipping_feewithout.
