Developers
API referenceBusiness sign in

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.

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

  2. 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.read and tracking.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_xxxxxxxxxxxxxxxxxxxxxxxx
  3. Install the SDK

    Shell
    npm install @qoene/delivery
  4. Find 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"]
  5. Get a price

    A quote prices one product for this parcel and route and is valid until expires_at. The Idempotency-Key makes 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"]
  6. 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"]
  7. 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.spend scope). 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.