CBX Woo Connector — how it works
The CBX Woo Connector links your WooCommerce store to The Frozen Food Courier®. It sends your ready orders to TFFC and brings delivery updates back to your orders, all from the Cibarix™ Console in your WordPress admin. This page shows how to set it up and run it day to day.
The delivery flow
- Your customer orders. With CBX Woo Shipping, they choose a TFFC delivery option and the order gets a dispatch date.
- You mark the order ready. When it reaches your trigger status (for example “Processing” or your own “Dispatch Ready”), the connector picks it up.
- The connector prepares it. It checks the order is one you send to TFFC, works out who paid and who receives it, and reads the address and dispatch date. A date is never guessed.
- TFFC receives it. The order gets a waybill and reads “Received by TFFC — not yet scheduled”.
- TFFC plans it. It shows “Order in Planning” with TFFC’s delivery date. The route is confirmed the evening before and the order moves to Scheduled.
- Updates come back. Collected, in transit, out for delivery, delivered. Each is a private order note or, with your permission, moves the order to the status you chose.
- The delivery closes when it is delivered or cancelled. Your customer can follow it on TFFC’s tracking page throughout.
Two engines, both start Off
Each engine is set to Off, Shadow or Live on its own, and both start Off: installing the plugin changes nothing until you switch one on.
| Engine | Live | Shadow |
|---|---|---|
| Dispatch engine (outbound) | Sends your ready orders to TFFC for a waybill. | Rehearses the send and writes a private note. Nothing is sent. |
| Status engine (inbound) | Receives TFFC’s delivery updates on your orders. | Notes what it would have done. The order is not changed. |
If your store already sends its orders to TFFC another way, leave Dispatch Off and run Status only. Moving from Shadow to Live is a step you take together with TFFC.
What you control, and what TFFC may change
Without your permission, TFFC never changes your orders. Each update is a private order note, seen by your staff and never by your customer. Under Configuration ▸ Inbound — Receiving Updates ▸ Your permission you can give two separate permissions, both off until ticked:
- Order status updates: TFFC may change the order status, only through your own status mapping.
- Dispatch date updates: when TFFC moves a delivery to another day, it may update the order’s dispatch date.
Prefer notes only? Press Keep private notes only to record that and stop the reminder. Every choice is recorded with who and when in a History list under each permission, kept apart from the Logs so clearing the log does not erase it. A permission applies from then on; once you allow status updates, Apply TFFC’s missed updates lists the waiting orders and applies only updates that are still current.
Even with permission, TFFC never deletes, cancels or refunds an order, never changes amounts, items or addresses, and never emails your customers. Note that when a status changes, WooCommerce may send its own usual email for that status, just as if you had changed it yourself.
Two things always stay current: TFFC’s own tracking details on each order (waybill, delivery date, shipment status), and the plugin itself. Install TFFC updates automatically (Configuration ▸ General, On by default) installs new versions of this plugin only, each signed by TFFC and checked first. Turn it Off to update by hand.
Where the settings are
Open Cibarix™ → Connector (shop managers and administrators). The tabs are Flow (your setup as a picture, with warnings), Dashboard (today at a glance), Configuration, Field mapping, Logs, Help and Status (system check and self-test).
Configuration has the sections General · Outbound — Sending Orders · Inbound — Receiving Updates · Customer tracking, which form one form (any of their Save buttons saves all four), then Routing — which statuses start and end a delivery (two lists, each with its own Save) and Self-test (round-trip).
Setting up your store
1. Enter what TFFC gives you
- Merchant short code (General): your store’s code with TFFC, for example ABCD. If it is blank, nothing can be sent.
- Carrier API endpoint (must start with https://) and Carrier API key (Outbound): where orders go, and the password.
- Subscription secret (Inbound): proves an update really came from TFFC. If it is blank, no updates get in.
Saved keys show only their last four characters; an empty key box keeps the saved key. Press Save, then Test connection. Then send TFFC the Status webhook endpoint shown at the bottom of Inbound (it ends in /wp-json/cbx/v1/status), so TFFC can send your updates.
2. Choose which statuses start and end a delivery
- Trigger status(es): the status that means “ready for the courier”. The default is Processing. Tick nothing and nothing is sent.
- Cycle-ending status(es): statuses that mean “this delivery is finished”. The next send starts a fresh waybill, so an order can be re-used for a later delivery. A cancel-type status also cancels the delivery at TFFC.
A status can start a delivery or end one, never both, so a status ticked in one list is greyed out in the other. Under Outbound, Which orders starts on “Only TFFC-shipped orders”, which sends only orders that chose a TFFC shipping method. Without CBX Woo Shipping, choose All orders or nothing is sent; the Flow tab warns you.
3. Check the delivery date
Leave Dispatch-date field key blank to read the date from CBX Woo Shipping (shown on screen as “TFFC Shipping”); enter a key only if your checkout stores the date in a custom field. Auto-set date when blank (0 = off) can fill a missing date as the order date plus a number of working days, with a visible note. The Dispatch readiness panel shows where the date comes from and how often it was found on recent completed orders.
4. Map TFFC’s updates to your statuses
Status mapping (Inbound) sets what each update does: a status in your store, or “— No change (note only) —”. It acts only once you have given “Order status updates” permission. Starting values:
| TFFC update | Starts as |
|---|---|
| Booked, Scheduled, Collected | No change |
| In transit, Out for delivery, Rescheduled | No change, but follows CBX Woo Shipping’s matching status if you switched it on there. Rescheduled otherwise uses your Scheduled mapping. |
| Delivered | Completed |
| Failed | Failed (a later Delivered still replaces it) |
| Cancelled | Cancelled |
| Received, Rejected, Route locked, Reschedule declined, Merged into another delivery, Order in Planning | No change |
Use TFFC Shipping statuses fills only the empty rows. Date moves and holds never change a status: they arrive as a note (for example “Delivery moved by The Frozen Food Courier: Thu 1 Oct → Fri 2 Oct”) and change the dispatch date only with your date permission.
5. Rehearse, then go Live
Set both engines to Shadow and read the notes on a few orders. On the Status tab, Run dry-run (loopback) checks your setup with a made-up order. Send test waybill (Configuration ▸ Self-test) sends a disposable test through TFFC and back, without a real order. Then agree the switch to Live with TFFC and decide on your permissions.
Gift orders and custom fields
The buyer comes from the billing details, and the recipient and delivery address from the shipping details. When the receiver’s name, phone or email differs from the buyer’s, the order goes as a gift: TFFC delivers to, and notifies, the recipient. That works on its own. Use the Field mapping tab only when a detail lives in a custom checkout field:
- Press Scan orders. It reads your last 50 orders and lists their custom fields under Custom Fields Found.
- In the Buyer, Recipient or Delivery address table, pick the field in the row’s override box or type its key. Check a field shows whether a key appears on recent orders.
- Optional: a Custom field present indicator (treat the order as a gift when that field is filled), a Delivery note (extra), and Send the customer’s checkout note (On by default).
- Press Save mapping. Reset mapping goes back to the defaults.
An override is used only when the field is filled in, so it never wipes out a normal detail.
Customer tracking
- Show customers a tracking link (Off by default) adds a “Track delivery” button under My Account once the order has a waybill. Check it on your store first.
- Tracker base URL: leave blank to use TFFC’s tracking page.
- In your own emails: add
[tffc_tracking order_id="123" style="button"]using your email tool’s order-id tag. An email sent instantly by an automation plugin also needsorder_key="…". Nothing shows until there is a waybill.
Day to day
The TFFC column on the Orders list shows one icon per order (hover for detail): green tick synced (or cancelled) · green house delivered · blue clock sending, received or in planning · amber triangle needs a look · red cross delivery failed · grey dash not sent.
While Dispatch is on, the Orders list also shows a Dispatch date column, and each order has a TFFC / CBX box: push state, waybill, delivery date (“moved by TFFC from …” when changed), shipment status, a tracking link and past deliveries. To send by hand, press Send to TFFC (CBX) in the box, or use Send to TFFC in Bulk actions (finished and trashed orders are skipped). Cancelling or refunding an order also cancels its delivery at TFFC.
Why updates are not always instant
The connector is built so that it never slows your store down. Nothing talks to TFFC while a customer checks out or while you save an order: the work is queued and done in the background a moment later. That is why an order does not change the second you save it.
Sending an order to us
- When an order reaches your trigger status, the connector waits about 25 seconds for any further edits (some stores save an order several times in a row), then queues the send. It never waits more than two minutes from the first trigger.
- The send runs on WooCommerce’s background queue. The moment it runs, TFFC answers with the waybill and the order reads “Received by TFFC — not yet scheduled”.
- If we are briefly unreachable, the order shows “Syncing” and the connector tries again after 1 minute, 5 minutes, 15 minutes, 1 hour and 3 hours, then lets us know.
Updates coming back
- We send each update to your store as it happens on our side, usually within a few minutes of the driver’s scan, and your store applies it as soon as it arrives. If your store does not answer, we try again later.
- Planning happens on our side. An order shows “Order in Planning” when it enters our planner and moves to Scheduled when the route is confirmed, normally the evening before delivery. So an order can rightly sit at “Received” for a while.
- An open Orders screen does not refresh by itself: reload the page to see the latest.
Quiet stores: background work needs visitors
WordPress has no clock of its own. Its scheduled tasks (WP-Cron), and with them WooCommerce’s background queue, run only when someone loads a page on your site. On a busy store that happens every few seconds. On a quiet store, at night or between orders, a queued send can wait for the next visitor, sometimes for hours. Nothing is lost; it is just late. The same goes for the connector’s daily log clean-up and its automatic updates.
The fix is an external cron: a service that calls your site’s scheduler on a fixed beat, so background work runs on time whether or not anyone is shopping.
- Ask your host whether they offer a server cron or scheduled task (most managed WordPress hosts do), or use a free external cron service.
- Have it call
https://your-store.co.za/wp-cron.phpevery 5 minutes, using your own store’s address. - Optional, once the external cron runs reliably: ask your developer to add
define( 'DISABLE_WP_CRON', true );towp-config.php, so WordPress stops also running its scheduler on your visitors’ page loads.
To check the queue, open WooCommerce → Status → Scheduled Actions and search for cbx. Pending actions that are well past their scheduled time mean the queue is not being run often enough: set up an external cron.
Reading the logs
The Logs tab lists every update, newest first: when, direction (↑ out, ↓ in), status, outcome, order, the status it moved to, waybill, mode and detail. Green outcomes went through, purple were Shadow rehearsals, amber are waiting, red were refused.
- Keep log entries for … days (default 30); keep it long while testing. Clear log empties the table but keeps order notes.
- Leave Order-note detail and Log detail (General) on Normal unless TFFC asks you to raise them.
Common problems
| What you see | What to do |
|---|---|
| Orders aren’t sent | Check Dispatch is Live, a trigger status is ticked, the short code is set, and “Which orders” is All orders if you don’t use CBX Woo Shipping. |
| “Action needed” (e.g. an invalid postcode) | Correct the order and click Update. It is re-sent automatically. |
| “Held” with a reason | Fix what it says (often the address), then press Send to TFFC (CBX). |
| “On hold at TFFC” | TFFC is confirming a date or address. Act only if the reason asks; it clears with the next update. |
| “Syncing” or “TFFC has been notified” | TFFC was briefly unreachable. The connector retries for a few hours, then alerts TFFC. Nothing for you to do. |
| “Confirm needed” | Choose New delivery or Update existing. |
| “Paused — repeated sends” | Check the order, then press Send to TFFC once. It also lifts after a quiet hour. |
| An order stays on “Sending” or “Not sent” for a long time on a quiet store | The background queue has not run yet. Set up an external cron (see “Why updates are not always instant”). |
| Updates arrive, status doesn’t change | Give “Order status updates” permission and map that update. The order note says which is missing. |
| No updates at all | Check Status is Live, the subscription secret is set, and TFFC has your webhook address. |
| A trashed order is still booked | Trashing doesn’t cancel a delivery. Set the order to Cancelled. |
Still unsure? Contact TFFC; the connector may already have alerted us.
Your customers’ data
The connector sends TFFC only what a courier needs: the order number, the buyer’s name, company, phone and email, the recipient’s details on a gift order, the delivery address, the dispatch date, the checkout note (you can turn it off), and the shipping option and fee chosen. It does not send the products ordered, their prices or payment details. Problems are reported to TFFC, never to your customers, with order ids and field names only. The connector’s log never stores the customer details it sends, and order notes stay private to your staff. Keeping personal information to what delivery needs is how we work under POPIA. Developers: see our developers page.
