Developers
API referenceBusiness sign in

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

  1. 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.

  2. Install the plugin

    WordPress → Plugins → Add New → Upload Plugin, choose the zip, activate. WooCommerce must be active.

  3. 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.

  4. 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.

  5. 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

SettingWhat it does
Secret API keyStored 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 keyFor the widget only (qd_pk_…); must match the secret key's environment. A secret key pasted here is refused.
Qoene store IDOrders arrive in this store's order inbox with source WOOCOMMERCE.
Drop-off point / pickup addressWhere Relay parcels start (a Qoene Point) and where Express riders collect.
Default parcelUsed when products have no weight or dimensions. Products with both are measured exactly: weights added, items stacked.
Keep prices forRate cache, 1–25 minutes (Qoene quotes are valid for 30).
When Qoene cannot be reachedHide the Qoene methods, or show a flat rate. An address Qoene cannot serve is always hidden.
Require a Qoene PointRelay Point and Locker orders need a point chosen in the widget before they can be placed.
Prohibited itemsYou confirm the current declaration once for all parcels shipped from WooCommerce. A new version pauses shipping until you confirm it.
Create the shipmentAutomatically when the order is paid (Processing), or manually.
Pay Qoene byBusiness invoice, Business wallet or prepaid per parcel (approved in Qoene Business; see payments).
Label formatA6, or A6 centred on A4.
Tell the customer / Complete on deliveryCustomer note with the tracking link; Completed when Qoene reports delivered or collected.
Returns from My AccountCustomers 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

LIVE flow
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 /orders checkoutSelection). 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

SymptomCheck
No Qoene methods at checkoutGhana 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 allowedAdd 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: declarationQoene published a new prohibited-items declaration; confirm it in the Orders section.
Ship run failed with SENDER_VERIFICATION_REQUIREDThe Business owner must complete identity verification in Qoene Business.
Webhooks answer 401The signing secret in the settings is not the endpoint's current secret; register again or paste the right one.
DetailsTurn on Debug log; WooCommerce → Status → Logs → qoene-delivery shows each API status and code (never keys or personal details).