Developers
API referenceBusiness sign in

Guides

Store orders and ship runs

Instead of booking each parcel yourself, you can send paid orders to your Business order inbox and let Qoene quote, book and label them in a background ship run, from the API or from the Business workspace.

When to use the inbox

Choosing a flow
Use…When
Quotes and bookingsYour server books each parcel right after payment and wants the shipment back immediately.
Store orders and ship runsYour team reviews orders in the Business workspace, ships in batches, or you want Qoene to apply your store's defaults (drop-off point, pickup address, sender details).

Set up the store

In the Business workspace, open Settings → Stores, create your store (platform CUSTOM) and bind it to your API client: a TEST client's store for testing, a LIVE client's store for production. A key works only with stores bound to its own client; any other store or order reads as 404.

Send an order

const { order, replayed } = await qoene.orders.create({
  storeId: process.env.QOENE_STORE_ID!,
  externalOrderId: String(shopOrder.number),   // your order number
  receiver: { name: shopOrder.shipping.name, phone: shopOrder.shipping.phone },
  serviceCode: 'RELAY_POINT',
  destinationPointCode: shopOrder.qoenePointCode,
  items: shopOrder.lines.map(line => ({ name: line.title, sku: line.sku, quantity: line.quantity, unitPriceMinor: line.priceMinor })),
  parcel: { actualWeightGrams: 1200, lengthMm: 300, widthMm: 200, heightMm: 120 },
  orderTotalMinor: shopOrder.totalMinor,
  storePaymentState: 'PAID',
  placedAt: shopOrder.createdAt,
});
curl -X POST https://api.qoenedelivery.com/v1/orders \
  -H "Authorization: Bearer $QOENE_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"storeId":"QD-STR-…","externalOrderId":"1001","receiver":{"name":"Kwame Mensah","phone":"0247654321"},"serviceCode":"RELAY_POINT","destinationPointCode":"QD-PU-…","parcel":{"actualWeightGrams":1200,"lengthMm":300,"widthMm":200,"heightMm":120},"storePaymentState":"PAID"}'
$response = $client->post('orders', ['json' => [
    'storeId' => getenv('QOENE_STORE_ID'), 'externalOrderId' => (string) $order['number'],
    'receiver' => ['name' => $order['shipping_name'], 'phone' => $order['shipping_phone']],
    'serviceCode' => 'RELAY_POINT', 'destinationPointCode' => $order['qoene_point'],
    'parcel' => ['actualWeightGrams' => 1200, 'lengthMm' => 300, 'widthMm' => 200, 'heightMm' => 120],
    'storePaymentState' => 'PAID',
]]);
response = requests.post(
    "https://api.qoenedelivery.com/v1/orders",
    headers=headers,
    json={"storeId": os.environ["QOENE_STORE_ID"], "externalOrderId": str(order["number"]),
          "receiver": {"name": order["shipping_name"], "phone": order["shipping_phone"]},
          "serviceCode": "RELAY_POINT", "destinationPointCode": order["qoene_point"],
          "parcel": {"actualWeightGrams": 1200, "lengthMm": 300, "widthMm": 200, "heightMm": 120},
          "storePaymentState": "PAID"},
    timeout=30,
)
  • Orders are idempotent by store and external order ID: sending the same order again returns it (200, replayed: true); different details answer 409 COMMERCE_ORDER_CONFLICT. No idempotency key is needed.
  • Relay orders need destinationPointCode; Express orders need destinationAddress.text.
  • Add parcel before shipping; without it the run fails the order with PARCEL_DETAILS_MISSING.
  • An order sent with a TEST key stays in the inbox as a record. It is never shipped and sends no webhooks.

Ship orders

With a LIVE key and the orders.ship scope, queue a ship run for one order or up to 100. Each order is quoted (with your contract prices), booked as the Business's verified owner and labelled when ready. A prepaid parcel waits for payment.

const { declaration } = await qoene.declarations.prohibitedItems();
const { job } = await qoene.shipJobs.create({
  orderIds: ['QD-ORD-…', 'QD-ORD-…'],
  paymentMode: 'BUSINESS_INVOICE',
  prohibitedItemsDeclaration: { accepted: true, version: declaration.version },
}, { idempotencyKey: 'ship-run-2026-10-27-am' });

// Later (or on order.shipped / order.failed webhooks):
const { job: done } = await qoene.shipJobs.get(job.public_id);
for (const item of done.items ?? []) console.log(item.order_reference, item.status, item.tracking_number ?? item.failure_code);
curl -X POST https://api.qoenedelivery.com/v1/ship-jobs \
  -H "Authorization: Bearer $QOENE_API_KEY" \
  -H "Idempotency-Key: ship-run-2026-10-27-am" \
  -H "Content-Type: application/json" \
  --data '{"orderIds":["QD-ORD-…"],"paymentMode":"BUSINESS_INVOICE","prohibitedItemsDeclaration":{"accepted":true,"version":"2026-10-v1"}}'
$response = $client->post('ship-jobs', [
    'headers' => ['Idempotency-Key' => 'ship-run-2026-10-27-am'],
    'json' => ['orderIds' => $orderIds, 'paymentMode' => 'BUSINESS_INVOICE',
        'prohibitedItemsDeclaration' => ['accepted' => true, 'version' => $declarationVersion]],
]);
$job = json_decode((string) $response->getBody(), true)['data']['job'];
response = requests.post(
    "https://api.qoenedelivery.com/v1/ship-jobs",
    headers={**headers, "Idempotency-Key": "ship-run-2026-10-27-am"},
    json={"orderIds": order_ids, "paymentMode": "BUSINESS_INVOICE",
          "prohibitedItemsDeclaration": {"accepted": True, "version": declaration_version}},
    timeout=30,
)
job = response.json()["data"]["job"]
  • The response is 202 with the run. Follow it with GET /ship-jobs/{jobId} or subscribe to order.shipped and order.failed.
  • Orders already shipped, cancelled or in another run are SKIPPED with a reason. An order can never get two shipments.
  • Up to 5 runs can be in progress per Business; more answer 429.
  • BUSINESS_WALLET needs the wallet.spend scope too.