Guides
WooCommerce plugin
The official WooCommerce plugin: Qoene Express and Qoene Relay as shipping methods with live prices and promised dates, the Qoene Point picker at checkout, shipments and labels from the orders screen, tracking for customers, and returns from My Account. It is a thin layer over the API in this documentation: no price or rule lives in PHP.
Install and connect
Prepare Qoene Business
In the Business workspace, Settings → API & webhooks: create an API client, a secret key with the scopes below, and a checkout widget key (publishable) that allows your shop's address, for example
https://shop.example.com. Then Settings → Stores: add a store with platform WooCommerce, bound to that API client, with your sender name and phone and your usual drop-off Qoene Point. Use a TEST client first.Install the plugin
WordPress → Plugins → Add New → Upload Plugin, choose the zip, activate. WooCommerce must be active.
Connect
WooCommerce → Settings → Qoene Delivery: paste the secret key, the publishable key and the store ID (
QD-STR-…), save, and press Test connection. It checks the key, the store binding, the drop-off point, the publishable key's environment and the prohibited-items declaration.Add the methods
WooCommerce → Settings → Shipping → your Ghana zone → Add shipping method: Qoene Express Standard, Express Priority, Relay – pickup point, Relay – locker, Relay – home delivery. Each can add a percentage, a handling fee or free shipping above a cart total.
Go LIVE
Swap in the LIVE secret and publishable keys and the LIVE store, then on an HTTPS site press Register webhooks in the Webhooks section.
Settings
| Setting | What it does |
|---|---|
| Secret API key | Stored encrypted with the site's salts, never printed back or sent to a browser. Or define QOENE_DELIVERY_SECRET_KEY in wp-config.php. Scopes: services.read, locations.read, quotes.write, checkout.write, orders.write, orders.read, orders.ship, shipments.read, shipments.write, tracking.read, labels.write, labels.read, returns.read, returns.write, webhooks.read, webhooks.write (and wallet.spend to pay from the wallet). |
| Publishable key | For the widget only (qd_pk_…); must match the secret key's environment. A secret key pasted here is refused. |
| Qoene store ID | Orders arrive in this store's order inbox with source WOOCOMMERCE. |
| Drop-off point / pickup address | Where Relay parcels start (a Qoene Point) and where Express riders collect. |
| Default parcel | Used when products have no weight or dimensions. Products with both are measured exactly: weights added, items stacked. |
| Keep prices for | Rate cache, 1–25 minutes (Qoene quotes are valid for 30). |
| When Qoene cannot be reached | Hide the Qoene methods, or show a flat rate. An address Qoene cannot serve is always hidden. |
| Require a Qoene Point | Relay Point and Locker orders need a point chosen in the widget before they can be placed. |
| Prohibited items | You confirm the current declaration once for all parcels shipped from WooCommerce. A new version pauses shipping until you confirm it. |
| Create the shipment | Automatically when the order is paid (Processing), or manually. |
| Pay Qoene by | Business invoice, Business wallet or prepaid per parcel (approved in Qoene Business; see payments). |
| Label format | A6, or A6 centred on A4. |
| Tell the customer / Complete on delivery | Customer note with the tracking link; Completed when Qoene reports delivered or collected. |
| Returns from My Account | Customers start returns for delivered LIVE orders. |
Rates and the Qoene Point picker
Each method is priced live with POST /quotes/options: Express address to address; Relay to the best Qoene Point near the shopper's address, found with GET /locations/search?address=…. The label shows the promised date ("Ready to collect by Thu 5 Nov").
When the shopper picks a Relay method, the picker appears below the shipping methods (classic checkout and Checkout block). The shop server creates the checkout session with the secret key; the page mounts the checkout widget from js.qoenedelivery.com with the publishable key only. The signed choice is sent back to the shop server, verified with POST /checkout/selections/verify, and its price replaces the estimate. Placing the order verifies it again; a changed cart or an expired choice asks the shopper to choose again.
Orders, shipments and labels
Shopper picks "Qoene Relay – pickup point" → widget → signed choice
→ order placed (checked with Qoene again) → Qoene order inbox (POST /orders, checkoutSelection)
→ order paid (Processing) or "Ship with Qoene" → ship run (POST /orders/{id}/ship)
→ shipment + label → order.shipped webhook → tracking number on the order and in the customer email
→ shipment.* webhooks → order notes → delivered/collected → Completed (if enabled)- The order goes to the Qoene order inbox when it is placed, with the signed selection (
POST /orderscheckoutSelection). Resending is safe: Qoene recognises the order number. - The ship run books the selection's quote, at the price the shopper saw, while it is valid (about 30 minutes). Later it quotes again for the same product and point. Editing the product, point or parcel in the Qoene inbox detaches the selection.
- Ship with Qoene is in the order actions, in the Qoene box on the order screen and as a bulk action in the orders list (one ship run per 100 orders).
- Download label (PDF) in the Qoene box. Prepaid parcels get their label after payment.
- Every write uses an Idempotency-Key made from the order ID, so a retry after a timeout never ships twice.
- TEST keys: ship runs are LIVE only, so the plugin books a simulated parcel directly (
POST /shipments). There are no labels or webhooks in TEST; use Refresh status.
Tracking and webhooks
The receiver is https://your-shop/wp-json/qoene-delivery/v1/webhooks. It checks the HMAC signature and the five-minute timestamp window, records each event ID once (a replay or retry is acknowledged without acting twice) and answers 500 when processing fails so Qoene retries. It subscribes to shipment.status_changed, order.shipped, order.failed and every return.* event. Customers see the product, the point, the promised date, the milestone and the tracking link in My Account, on the thank-you page and in WooCommerce emails.
Returns
On a delivered LIVE order, My Account → Orders → View shows Return items with Qoene Delivery: items and quantities, a reason, the declaration. The plugin starts the return with POST /returns under your return policy. Qoene sends the customer the paperless drop-off code by SMS (and email); the shop never sees it. return.* events become order notes; on return.received or return.inspected the note reminds you to refund in WooCommerce. Qoene never refunds the customer.
Troubleshooting
| Symptom | Check |
|---|---|
| No Qoene methods at checkout | Ghana address, store currency GHS, the method in the zone, Test connection passes, a drop-off point (Relay) or pickup address (Express). Relay Point and Locker also need the publishable key. |
| The picker says the website is not allowed | Add the shop's exact origin (scheme and host) to the publishable key's allowed websites. |
| "Choose a Qoene Point before placing your order" | The shopper has not confirmed a point, or the cart changed after they did. |
| "The store is not bound to this key's API client" | Qoene Business → Settings → Stores → bind the WooCommerce store to the same API client as the key. |
| Shipping paused: declaration | Qoene published a new prohibited-items declaration; confirm it in the Orders section. |
Ship run failed with SENDER_VERIFICATION_REQUIRED | The Business owner must complete identity verification in Qoene Business. |
| Webhooks answer 401 | The signing secret in the settings is not the endpoint's current secret; register again or paste the right one. |
| Details | Turn on Debug log; WooCommerce → Status → Logs → qoene-delivery shows each API status and code (never keys or personal details). |