Developers
API referenceBusiness sign in

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.

Shell
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 :4300

What is inside

Example files
FileWhat it does
src/qoene.tsCreates the client from environment variables (key, base URL)
src/shipping.tsfindDropoffPoint, findPickupPoints, checkoutOptions, bookPaidOrder, printLabel, trackingFor. Every creating call uses an idempotency key derived from the cart or order.
src/webhooks.tshandleQoeneWebhook (framework-free, for Next.js Route Handlers) and createNodeWebhookHandler (Node http, Express): raw body, verifyWebhook, deduplication by event ID, then your handler
src/demo.tsRuns the whole flow against your TEST key and prints each step
src/webhook-server.tsServes the webhook handler on a local port

The flow in code

src/demo.ts (shortened)
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

  1. Server only. Put shipping.ts in a server module (for example lib/qoene/) and import it only from Route Handlers, Server Actions or your API server. Keep QOENE_API_KEY and QOENE_WEBHOOK_SECRET in server environment variables.
  2. Checkout. When the buyer reaches the delivery step, call checkoutOptions from a Route Handler and return only names, prices and promises to the browser. Keep the chosen quote.public_id on the order.
  3. Payment succeeded. In the code that marks an order paid, call bookPaidOrder. Store shipment.public_id and tracking_number on the order. Re-running it is safe.
  4. Labels. With a LIVE key, printLabel returns the PDF bytes; save them or stream them to your admin.
  5. Webhooks. Add app/api/qoene/webhook/route.ts that passes await request.text() and request.headers to handleQoeneWebhook, backed by a database table for processed event IDs.
  6. Test, then go LIVE with the go-LIVE checklist.