Start
Getting started
In about five minutes you will make a TEST key, find two Qoene Points, get a price and book a simulated parcel. TEST keys never create real parcels, charges, riders or messages.
Create a Business account
Sign up at qoenedelivery.com/signup and choose Business. If you already use Qoene Logistics or Qoene Delivery, sign in with the same email or phone. You can also be invited to an existing Business with the Developer role, which can manage TEST keys.
Create a TEST key
In the Business workspace, open Manage → API & Webhooks. Create an API client with environment TEST, then create a key. For this guide, tick
locations.read,quotes.write,shipments.write,shipments.readandtracking.read.The key is shown once. Put it in your server's environment, not in your code:
Shell # .env (never commit this file) QOENE_API_KEY=qd_test_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxInstall the SDK
Shell npm install @qoene/deliveryFind a drop-off point and a pickup point
Relay parcels go from a drop-off point (where you hand them in) to a pickup point (where the buyer collects). Search near a position; results are ranked and come with the reason any nearby point cannot be used.
import { QoeneDelivery } from '@qoene/delivery'; const qoene = new QoeneDelivery({ apiKey: process.env.QOENE_API_KEY! }); // Near your shop: where you will drop parcels off. const dropoff = await qoene.locations.search({ lat: 5.6037, lng: -0.187, purpose: 'DROPOFF', limit: 1 }); // Near the buyer: where they will collect. const pickup = await qoene.locations.search({ lat: 5.6502, lng: -0.1869, purpose: 'PICKUP', size: 'SMALL', limit: 3 }); const origin = dropoff.results[0].public_code; const destination = pickup.results[0].public_code;curl -G https://api.qoenedelivery.com/v1/locations/search \ -H "Authorization: Bearer $QOENE_API_KEY" \ --data-urlencode "lat=5.6502" --data-urlencode "lng=-0.1869" \ --data-urlencode "purpose=PICKUP" --data-urlencode "size=SMALL" --data-urlencode "limit=3"$response = $client->get('locations/search', [ 'query' => ['lat' => 5.6502, 'lng' => -0.1869, 'purpose' => 'PICKUP', 'size' => 'SMALL', 'limit' => 3], ]); $points = json_decode((string) $response->getBody(), true)['data']['results']; $destination = $points[0]['public_code'];response = requests.get( "https://api.qoenedelivery.com/v1/locations/search", headers={"Authorization": f"Bearer {os.environ['QOENE_API_KEY']}"}, params={"lat": 5.6502, "lng": -0.1869, "purpose": "PICKUP", "size": "SMALL", "limit": 3}, timeout=30, ) destination = response.json()["data"]["results"][0]["public_code"]Get a price
A quote prices one product for this parcel and route and is valid until
expires_at. TheIdempotency-Keymakes a retry return the same quote instead of a new one.const { quote } = await qoene.quotes.create({ service: 'RELAY', serviceVariant: 'POINT_TO_POINT', measurements: { actualWeightGrams: 1200, lengthMm: 300, widthMm: 200, heightMm: 120 }, originLocationCode: origin, destinationLocationCode: destination, payOnPickup: true, }, { idempotencyKey: 'order-1001:quote' }); console.log(quote.public_id, quote.total_minor); // QD-QT-… 2500 (pesewas)curl -X POST https://api.qoenedelivery.com/v1/quotes \ -H "Authorization: Bearer $QOENE_API_KEY" \ -H "Idempotency-Key: order-1001:quote" \ -H "Content-Type: application/json" \ --data '{"service":"RELAY","serviceVariant":"POINT_TO_POINT","measurements":{"actualWeightGrams":1200,"lengthMm":300,"widthMm":200,"heightMm":120},"originLocationCode":"QD-DO-…","destinationLocationCode":"QD-PU-…","payOnPickup":true}'$response = $client->post('quotes', [ 'headers' => ['Idempotency-Key' => 'order-1001:quote'], 'json' => [ 'service' => 'RELAY', 'serviceVariant' => 'POINT_TO_POINT', 'measurements' => ['actualWeightGrams' => 1200, 'lengthMm' => 300, 'widthMm' => 200, 'heightMm' => 120], 'originLocationCode' => $origin, 'destinationLocationCode' => $destination, 'payOnPickup' => true, ], ]); $quote = json_decode((string) $response->getBody(), true)['data']['quote'];response = requests.post( "https://api.qoenedelivery.com/v1/quotes", headers={"Authorization": f"Bearer {os.environ['QOENE_API_KEY']}", "Idempotency-Key": "order-1001:quote"}, json={"service": "RELAY", "serviceVariant": "POINT_TO_POINT", "measurements": {"actualWeightGrams": 1200, "lengthMm": 300, "widthMm": 200, "heightMm": 120}, "originLocationCode": origin, "destinationLocationCode": destination, "payOnPickup": True}, timeout=30, ) quote = response.json()["data"]["quote"]Book the parcel
Every booking confirms the current prohibited-items declaration. Show its text to whoever books (or keep it in your seller terms), then send its version.
const { declaration } = await qoene.declarations.prohibitedItems(); const { shipment } = await qoene.shipments.create({ quoteId: quote.public_id, description: 'Two cotton shirts, boxed', orderReference: 'SHOP-1001', sender: { name: 'Adwoa Styles', phone: '0241234567' }, receiver: { name: 'Kwame Mensah', phone: '0247654321' }, paymentMode: 'PAY_ON_PICKUP', prohibitedItemsDeclaration: { accepted: true, version: declaration.version }, }, { idempotencyKey: 'order-1001:book' }); console.log(shipment.public_id, shipment.tracking_number); // QD-TST-… (TEST)curl https://api.qoenedelivery.com/v1/declarations/prohibited-items -H "Authorization: Bearer $QOENE_API_KEY" curl -X POST https://api.qoenedelivery.com/v1/shipments \ -H "Authorization: Bearer $QOENE_API_KEY" \ -H "Idempotency-Key: order-1001:book" \ -H "Content-Type: application/json" \ --data '{"quoteId":"QD-QT-…","description":"Two cotton shirts, boxed","orderReference":"SHOP-1001","sender":{"name":"Adwoa Styles","phone":"0241234567"},"receiver":{"name":"Kwame Mensah","phone":"0247654321"},"paymentMode":"PAY_ON_PICKUP","prohibitedItemsDeclaration":{"accepted":true,"version":"2026-10-v1"}}'$declaration = json_decode((string) $client->get('declarations/prohibited-items')->getBody(), true)['data']['declaration']; $response = $client->post('shipments', [ 'headers' => ['Idempotency-Key' => 'order-1001:book'], 'json' => [ 'quoteId' => $quote['public_id'], 'description' => 'Two cotton shirts, boxed', 'orderReference' => 'SHOP-1001', 'sender' => ['name' => 'Adwoa Styles', 'phone' => '0241234567'], 'receiver' => ['name' => 'Kwame Mensah', 'phone' => '0247654321'], 'paymentMode' => 'PAY_ON_PICKUP', 'prohibitedItemsDeclaration' => ['accepted' => true, 'version' => $declaration['version']], ], ]); $shipment = json_decode((string) $response->getBody(), true)['data']['shipment'];headers = {"Authorization": f"Bearer {os.environ['QOENE_API_KEY']}"} declaration = requests.get("https://api.qoenedelivery.com/v1/declarations/prohibited-items", headers=headers, timeout=30).json()["data"]["declaration"] response = requests.post( "https://api.qoenedelivery.com/v1/shipments", headers={**headers, "Idempotency-Key": "order-1001:book"}, json={"quoteId": quote["public_id"], "description": "Two cotton shirts, boxed", "orderReference": "SHOP-1001", "sender": {"name": "Adwoa Styles", "phone": "0241234567"}, "receiver": {"name": "Kwame Mensah", "phone": "0247654321"}, "paymentMode": "PAY_ON_PICKUP", "prohibitedItemsDeclaration": {"accepted": True, "version": declaration["version"]}}, timeout=30, ) shipment = response.json()["data"]["shipment"]Follow it
const { tracking } = await qoene.shipments.tracking(shipment.public_id); console.log(tracking.milestoneLabel); // "Booked"curl https://api.qoenedelivery.com/v1/shipments/QD-TST-…/tracking -H "Authorization: Bearer $QOENE_API_KEY"$tracking = json_decode((string) $client->get("shipments/{$shipment['public_id']}/tracking")->getBody(), true)['data']['tracking'];tracking = requests.get(f"https://api.qoenedelivery.com/v1/shipments/{shipment['public_id']}/tracking", headers=headers, timeout=30).json()["data"]["tracking"]That's a complete TEST booking. Next, read Authentication and safety, then the guide for your checkout.
Go LIVE
LIVE keys create real parcels and real payment obligations. Before you switch:
- Verify the Business owner. LIVE bookings and ship runs are made as the Business's verified owner; until an owner has completed sender verification the API answers
403 SENDER_VERIFICATION_REQUIRED. - Create a LIVE client and key. Only an Owner or Admin can. Give the key only the scopes your server uses. Keys expire (1–365 days, default 90); plan the rotation.
- Choose how you pay for deliveries. Pay on pickup, prepaid with an approval request, Business invoice (approved credit) or Business wallet (needs the
wallet.spendscope). See Payment status. - Register a webhook endpoint on public HTTPS (port 443) and store its
whsec_secret on your server. Send a test event. See Webhooks. - Print labels with
POST /shipments/{id}/labels(LIVE only). - Bind your store to the LIVE client in Business Settings → Stores if you use the order inbox.
- Confirm your routes and launch date with the Qoene Delivery team before sending real parcels.
The base URL stays the same: https://api.qoenedelivery.com/v1. Only the key changes.