Developers
API referenceBusiness sign in

Guides

Booking and labels

Book a parcel from a quote, print its label and, for collections, group parcels on a manifest.

Book from a quote

POST /shipments books an unexpired quote from the same Business and environment.

Booking fields
FieldNotes
quoteIdThe quote's public_id
description3–500 characters describing the contents
sender, receiver{ name, phone } (Ghana numbers). The receiver gets collection or delivery messages.
paymentModePAY_ON_PICKUP or PREPAID (must match the quote's payOnPickup), or BUSINESS_INVOICE / BUSINESS_WALLET for an eligible Business
orderReferenceOptional, 3–100 characters. Unique per Business (case-insensitive, even after cancellation); returned as merchant_reference. Use your order number.
prohibitedItemsDeclaration{ accepted: true, version } with the current version. A changed version answers 409 PROHIBITED_ITEMS_DECLARATION_REQUIRED.
  • LIVE bookings are made as the Business's verified owner: 403 SENDER_VERIFICATION_REQUIRED until an owner has completed sender verification.
  • A LIVE prepaid parcel stays QUOTED until its payment is settled; see Payment status. Pay on pickup, invoice and wallet parcels are ready straight away.
  • Retrying with the same idempotency key returns the original booking; a reused orderReference with a different booking answers 409.

Labels

Once a LIVE parcel is ready (and paid, if prepaid), issue its label. The first call creates it; later calls return the same label with replayed: true. Then download the PDF with the labels.read scope: A6 by default, or format=a4 for an A6 label centred on A4 paper.

import { writeFile } from 'node:fs/promises';

const { label } = await qoene.labels.issue(shipment.public_id, { idempotencyKey: `order-${order.id}:label` });
const pdf = await qoene.labels.download(shipment.public_id, label.public_id, { format: 'a6' });
await writeFile(`labels/${shipment.tracking_number}.pdf`, pdf);
curl -X POST https://api.qoenedelivery.com/v1/shipments/QD-SHP-…/labels \
  -H "Authorization: Bearer $QOENE_API_KEY" \
  -H "Idempotency-Key: order-1001:label" \
  -H "Content-Type: application/json" --data '{}'

curl https://api.qoenedelivery.com/v1/shipments/QD-SHP-…/labels/QD-LBL-….pdf?format=a6 \
  -H "Authorization: Bearer $QOENE_API_KEY" -o label.pdf
$label = json_decode((string) $client->post("shipments/{$shipmentId}/labels", [
    'headers' => ['Idempotency-Key' => "order-{$orderId}:label"], 'json' => new \stdClass(),
])->getBody(), true)['data']['label'];
$client->get("shipments/{$shipmentId}/labels/{$label['public_id']}.pdf", ['query' => ['format' => 'a6'], 'sink' => 'label.pdf']);
label = requests.post(f"https://api.qoenedelivery.com/v1/shipments/{shipment_id}/labels",
    headers={**headers, "Idempotency-Key": f"order-{order_id}:label"}, json={}, timeout=30).json()["data"]["label"]
pdf = requests.get(f"https://api.qoenedelivery.com/v1/shipments/{shipment_id}/labels/{label['public_id']}.pdf",
    headers=headers, params={"format": "a6"}, timeout=30)
open("label.pdf", "wb").write(pdf.content)

Labels are LIVE only: a TEST key answers 403. The API cannot revise a label; Qoene operations can, with a reason.

Manifests

For a collection, create a manifest of 1–100 booked LIVE parcels. A parcel can be on only one issued manifest. A manifest does not confirm pickup: each handoff is still scanned.

Cancelling

POST /shipments/{id}/cancel with a written reason (10–500 characters) works before the parcel is handed over. Paid, payment-uncertain or handed-over parcels need help from Qoene support (409). A wallet-paid parcel needs wallet.spend too; the amount returns to the Business wallet.