Start
Reference integration
A small, runnable shop backend that uses only @qoene/delivery and a TEST key: find points, quote at checkout, book a paid order, print the label, follow tracking and receive webhooks. Copy the parts you need into your own project.
Get the code
The example is examples/node-shop-integration in the Qoene Delivery repository. Ask the Delivery team for a copy if you do not have access.
cd examples/node-shop-integration
cp .env.example .env # add your qd_test_ key
npm install
npm start # quote → book → label → tracking
npm run webhooks # local webhook receiver on :4300What is inside
| File | What it does |
|---|---|
src/qoene.ts | Creates the client from environment variables (key, base URL) |
src/shipping.ts | findDropoffPoint, findPickupPoints, checkoutOptions, bookPaidOrder, printLabel, trackingFor. Every creating call uses an idempotency key derived from the cart or order. |
src/webhooks.ts | handleQoeneWebhook (framework-free, for Next.js Route Handlers) and createNodeWebhookHandler (Node http, Express): raw body, verifyWebhook, deduplication by event ID, then your handler |
src/demo.ts | Runs the whole flow against your TEST key and prints each step |
src/webhook-server.ts | Serves the webhook handler on a local port |
The flow in code
const qoene = createQoeneClient(); // QOENE_API_KEY, QOENE_API_BASE_URL
const shop = { dropoffPointCode: await findDropoffPoint(qoene, shopLocation),
senderName: 'Adwoa Styles', senderPhone: '0241234567', payment: 'PAY_ON_PICKUP' };
const points = await findPickupPoints(qoene, buyerLocation);
const { offers } = await checkoutOptions(qoene, shop, cart, points[0].public_code);
// after the buyer has paid:
const shipment = await bookPaidOrder(qoene, shop, { ...order, quoteId: offers[0].quoteId });
const label = await printLabel(qoene, order, shipment); // TEST keys: { skipped: '…LIVE key…' }
const tracking = await trackingFor(qoene, shipment.public_id);Adopting it in your Next.js or Node shop
- Server only. Put
shipping.tsin a server module (for examplelib/qoene/) and import it only from Route Handlers, Server Actions or your API server. KeepQOENE_API_KEYandQOENE_WEBHOOK_SECRETin server environment variables. - Checkout. When the buyer reaches the delivery step, call
checkoutOptionsfrom a Route Handler and return only names, prices and promises to the browser. Keep the chosenquote.public_idon the order. - Payment succeeded. In the code that marks an order paid, call
bookPaidOrder. Storeshipment.public_idandtracking_numberon the order. Re-running it is safe. - Labels. With a LIVE key,
printLabelreturns the PDF bytes; save them or stream them to your admin. - Webhooks. Add
app/api/qoene/webhook/route.tsthat passesawait request.text()andrequest.headerstohandleQoeneWebhook, backed by a database table for processed event IDs. - Test, then go LIVE with the go-LIVE checklist.