Developers
API referenceBusiness sign in

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

  1. 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).

  2. Ask for all options from your server

    POST /quotes/options prices every product that can serve this parcel and route. Narrow it with serviceCodes if 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"]
  3. Show the offers

    For each offer show the product name, quote.total_minor (integer pesewas, tax included) and quote.promise.label, for example "Ready for pickup by Thursday 29 October". Hide or grey out the excluded products and, if useful, say why.

  4. Keep the chosen quote

    Save the chosen offer's quote.public_id and quote.expires_at with 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

Request fields per product
ProductSendNotes
Relay PointoriginLocationCode, destinationLocationCodePoint codes from Picking a Qoene Point. The point is re-checked at quote and booking time.
Relay LockerSame, with a locker as destinationOnly once lockers are live; until then lockers do not appear.
ExpressoriginAddressText, 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.components sum to the subtotal; price.taxComponents show each tax or levy line.
  • A Business contract's prices apply automatically to its quotes.
  • A promotionCode applies only when it is valid; an unknown or expired code answers 422 instead 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 /services shows each product's promise "if booked now" without a quote.