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
| Use… | When |
|---|---|
| Quotes and bookings | Your server books each parcel right after payment and wants the shipment back immediately. |
| Store orders and ship runs | Your 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 answer409 COMMERCE_ORDER_CONFLICT. No idempotency key is needed. - Relay orders need
destinationPointCode; Express orders needdestinationAddress.text. - Add
parcelbefore shipping; without it the run fails the order withPARCEL_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
202with the run. Follow it withGET /ship-jobs/{jobId}or subscribe toorder.shippedandorder.failed. - Orders already shipped, cancelled or in another run are
SKIPPEDwith a reason. An order can never get two shipments. - Up to 5 runs can be in progress per Business; more answer
429. BUSINESS_WALLETneeds thewallet.spendscope too.