Guides
Checkout options and prices
At checkout, ask for every delivery option at once, show the buyer the prices and promises, and keep the chosen quote for booking.
The flow
Collect what the price depends on
Parcel weight and size (from your products), where you send from (your usual drop-off point or pickup address) and where it goes (the buyer's chosen Qoene Point for Relay, or their address for Express).
Ask for all options from your server
POST /quotes/optionsprices every product that can serve this parcel and route. Narrow it withserviceCodesif you only sell some.const options = await qoene.quotes.options({ measurements: { actualWeightGrams: 1200, lengthMm: 300, widthMm: 200, heightMm: 120 }, originLocationCode: SHOP_DROPOFF_POINT, // Relay: your drop-off point destinationLocationCode: buyerChoice.pointCode, // Relay: the buyer's Qoene Point payOnPickup: false, }, { idempotencyKey: idempotencyKey('cart', cart.id, cart.version, 'options') }); for (const offer of options.offers) { console.log(offer.serviceCode, formatGhs(offer.quote.total_minor), offer.quote.promise?.label); } for (const item of options.excluded) { console.log(item.serviceCode, 'not available:', item.reason.message); }curl -X POST https://api.qoenedelivery.com/v1/quotes/options \ -H "Authorization: Bearer $QOENE_API_KEY" \ -H "Idempotency-Key: cart-77:v3:options" \ -H "Content-Type: application/json" \ --data '{"measurements":{"actualWeightGrams":1200,"lengthMm":300,"widthMm":200,"heightMm":120},"originLocationCode":"QD-DO-…","destinationLocationCode":"QD-PU-…","payOnPickup":false}'$response = $client->post('quotes/options', [ 'headers' => ['Idempotency-Key' => "cart-{$cart['id']}:v{$cart['version']}:options"], 'json' => [ 'measurements' => ['actualWeightGrams' => 1200, 'lengthMm' => 300, 'widthMm' => 200, 'heightMm' => 120], 'originLocationCode' => $shopDropoffPoint, 'destinationLocationCode' => $buyerPoint, 'payOnPickup' => false, ], ]); $options = json_decode((string) $response->getBody(), true)['data'];response = requests.post( "https://api.qoenedelivery.com/v1/quotes/options", headers={**headers, "Idempotency-Key": f"cart-{cart['id']}:v{cart['version']}:options"}, json={"measurements": {"actualWeightGrams": 1200, "lengthMm": 300, "widthMm": 200, "heightMm": 120}, "originLocationCode": shop_dropoff_point, "destinationLocationCode": buyer_point, "payOnPickup": False}, timeout=30, ) options = response.json()["data"]Show the offers
For each offer show the product name,
quote.total_minor(integer pesewas, tax included) andquote.promise.label, for example "Ready for pickup by Thursday 29 October". Hide or grey out the excluded products and, if useful, say why.Keep the chosen quote
Save the chosen offer's
quote.public_idandquote.expires_atwith the order. Book it once the order is paid. If it has expired by then, ask for a new quote: the price may have changed, so decide whether you absorb the difference.
Express and Relay requests
| Product | Send | Notes |
|---|---|---|
| Relay Point | originLocationCode, destinationLocationCode | Point codes from Picking a Qoene Point. The point is re-checked at quote and booking time. |
| Relay Locker | Same, with a locker as destination | Only once lockers are live; until then lockers do not appear. |
| Express | originAddressText, destinationAddressText (optionally destinationPlaceId, requestedPickupAt) | Doorstep pickup and delivery. Addresses are geocoded; a vague address may be refused with 422. |
For a single product use POST /quotes with service (EXPRESS or RELAY) and serviceVariant (STANDARD, PRIORITY, POINT_TO_POINT or POINT_TO_LOCKER).
Prices and promises
subtotal_minor + tax_minor = total_minor.price.componentssum to the subtotal;price.taxComponentsshow each tax or levy line.- A Business contract's prices apply automatically to its quotes.
- A
promotionCodeapplies only when it is valid; an unknown or expired code answers422instead of a quote without the discount. - TEST quotes use the same tariff as LIVE, so you can test your price display with a TEST key.
- Promises come from the product's rule and cut-off time in the market time zone (Africa/Accra for Ghana).
GET /servicesshows each product's promise "if booked now" without a quote.