Selling cash on delivery
Offers and discounts
Bundles, quantity packs and cross-sells, discount codes and automatic discounts, and how orders use them.
Three kinds of offer
type | What it does | What it needs |
|---|---|---|
bundle | Buy these products together and save. | product_ids (2 or more) and a discount and/or free_shipping. |
upsell | Buy more of one product and save more: packs such as "1", "2 save 10%", "3 save 20% + free delivery". | One product in product_ids, and its packs in tiers (1 to 6, at least one with a discount). |
cross_sell | A cart holding A is offered B and C, optionally at a discount. | cross_sell: what arms it and what it suggests. |
A discount is { "type": "percent", "value": "10" } (up to 90) or { "type": "fixed", "value": "500.00" } (an amount in the store's currency, with its decimals).
curl https://api.ordexs.com/v1/offers \
-H "Authorization: Bearer $ORDEXS_KEY" \
-H "Content-Type: application/json" \
-d '{"type":"upsell","name":"Buy more, save more","product_ids":["prod_…"],
"tiers":[{"quantity":1},
{"quantity":2,"discount":{"type":"percent","value":"10"},"badge":"POPULAR"},
{"quantity":3,"discount":{"type":"percent","value":"20"},"free_shipping":true}]}'A cross-sell's trigger_scope decides which carts show it: products (carts holding one of trigger_product_ids), collection (a product of trigger_collection_ids) or all. placements says where: order_button, summary, checkout_summary, cart, post_purchase. With auto_fill, the store tops the suggestions up with its best sellers.
statetells where an offer is in its schedule:active,scheduled(starts_atis ahead),expiredorpaused.- Pause and resume with
PATCH{"status": "paused"}/"active". The type can't change. GET /v1/offers/{id}/performancegives the orders the offer was applied to, their revenue and the discount it gave. Cancelled and returned orders don't count.- A store has at most 30 offers; creating a 31st returns
quota_exceeded.
Discounts
A discount with a code is typed by the shopper at checkout; without one it is an automatic discount the store applies by itself. applies_to is store, product (with product_ids) or collection (with collection_ids). usage_limit caps the total uses, per_customer_limit the uses per phone number.
- Codes are stored in capitals and are unique in a store whatever their letter case: a second
RAMADAN10returnsduplicate_discount_code. GET /v1/discounts?code=ramadan10finds a code.POST /v1/discounts/previewwith acodeandline_itemssays whether it works right now and what it would take off. The per-customer limit is checked only when the order is placed.stateaddsused_upwhentimes_usedreachedusage_limit.- A store has at most 50 discounts.
Orders
POST /v1/orders (and /v1/orders/preview) takes discount_code and offer_ids: the offers the shopper took, up to 4. The store checks each one against the lines, the schedule and the pack quantities, and applies only those that qualify, so you can pass what the shopper picked without pricing anything yourself. The order then shows offers and offer_ids (what applied), discount_code, discount_name and discount (the total taken off).
