Tracking for Royal Mail Click & Drop

Free plugin v0.9.0 + DJ Royal Mail Pro v0.2.0 add-on  |  ← Back to plugin page

Requirements

Requirement	Minimum	Recommended
WordPress	6.0	6.9+
WooCommerce	8.0	9.0+
PHP	7.4	8.2+
Click & Drop account	Required for tracking auto-fetch. Free for Royal Mail business customers.

Installation

Step 1 — Install the free plugin from WordPress.org

1. WP Admin → Plugins → Add New → search tracking royal mail click drop
2. Install and activate Tracking for Royal Mail Click & Drop

The free plugin gives you full Royal Mail integration: API auto-fetch, dispatch-note parsing, hourly backfill cron, plain-text email injection, public Track Order page, WP-CLI commands. No payment required.

Step 2 (optional) — Install the Pro add-on for branded emails, webhooks, and admin tools

1. Purchase DJ Royal Mail Pro at digitaljunkys.com/plugins/dj-royal-mail/#pricing
2. Download the zip from your Freemius account email
3. WP Admin → Plugins → Add New → Upload Plugin → install and activate
4. Activate your licence key when prompted

Pro is a separate plugin that runs alongside the free one and extends it via documented hooks. Both must be active for Pro features to work.

Configuration

After activating the free plugin, go to WooCommerce → Royal Mail Tracking.

Setting	Plan	Description
Click & Drop API key	Free	Your Integration API key from Click & Drop → Settings → Integration API. Stored encrypted at rest with AES-256-GCM.
Order reference prefix	Free	Prefix prepended to WooCommerce order numbers when matching against Click & Drop. Default: #
Dispatch email line	Free	Adds a plain-text "Your tracking number is …" line to the customer order-completed email. Default: on. When Pro is active, this checkbox controls the branded HTML block instead.
Email block colours	Pro	Available in the Pro settings page (WooCommerce → Royal Mail Pro). Colour pickers for the branded dispatch email — background, left border, button background, button text.
Email-only lookup	Free	Allow customers to look up orders using only their email address on the Track Order page. Off by default for privacy.
Trust X-Forwarded-For	Free	Enable when behind Cloudflare or a load balancer for accurate rate limiting. Off by default.

If Pro is active, additional settings live at WooCommerce → Royal Mail Pro: webhook URL, stale-dispatch threshold, daily digest email, email colour pickers.

What the free plugin does Free

Click & Drop API auto-fetch

When an order is marked Complete, the plugin immediately queries the Click & Drop API for a matching tracking number using your API key. If Click & Drop hasn't dispatched yet, the hourly background sync picks it up automatically.

Dispatch note parsing

When Click & Drop writes a dispatch note to your WooCommerce order (via the WooCommerce REST API connection), the plugin extracts the Royal Mail tracking number from the note and stores it — no API key required for this path.

Hourly background sync

A WP-Cron job runs every hour, fetching the Click & Drop order map in a single API call and backfilling tracking numbers for any completed orders from the last 14 days that are still missing one.

Plain-text tracking line in dispatch email

When a tracking number is recorded, the customer "Order Completed" email gets a single plain-text line: "Your Royal Mail tracking number: VU032331508GB · Track on Royal Mail →". Always on, always free.

For a fully branded HTML block with colour pickers and a template override, install the Pro add-on (see below).

Manual tracking entry

A Royal Mail tracking meta box appears on every order edit screen. Enter any tracking number manually — it's stored as _dj_rm_tracking_number order meta and immediately visible on the Track Order page and dispatch email.

Public Track Order page

Add [dj_track_order] to any page. Customers can search by order number + email, email address alone, or tracking number. Results show the tracking number with a deep-link to Royal Mail's tracking portal. The same functionality is available as the DJ Track Order Gutenberg block.

WP-CLI commands

Useful in deploys and on-call scripts:

# Show plugin status + ping the C&D API
wp djrmcd status

# Backfill tracking for the last 200 completed orders
wp djrmcd backfill

# Backfill orders from a specific date
wp djrmcd backfill --since=2026-01-01

# Dry run — see what would be fetched
wp djrmcd backfill --dry-run

# Force re-fetch even for orders that already have tracking
wp djrmcd backfill --force

What the Pro add-on adds Pro

Branded HTML dispatch email

Replaces the free plugin's plain-text tracking line with a fully styled "Your order has been dispatched" HTML block, with admin colour pickers and a theme-overridable template. See Email block colours & template override below.

Slack / Discord / Microsoft Teams webhooks

One customisable POST to a team-chat webhook URL every time tracking is recorded. See Dispatch webhooks below.

"Royal Mail" tracking column on WooCommerce → Orders

A new column on the WooCommerce orders list table (classic and HPOS modes) shows tracking status with a clickable deep-link to Royal Mail. No more opening each order to check.

Stale-dispatch warnings + daily email digest

Admin notice when Completed orders sit longer than a configurable threshold (default 48 hours) without a tracking number — catches missed dispatches. Optional daily WP-Cron job emails a one-line summary to a chosen address.

Bulk "Fetch Royal Mail tracking" admin action

Select multiple orders on the WooCommerce orders screen, pick Fetch Royal Mail tracking from the Bulk Actions dropdown, and the plugin pulls tracking from Click & Drop for all of them in one click. Classic and HPOS supported.

Bulk CSV import

Upload order_number,tracking_number CSVs via the Pro settings page, or from the command line — see Bulk CSV import below.

Pro: email block colours & template override Pro

Match the dispatch email tracking block to your store's brand — no code required. Go to WooCommerce → Royal Mail Pro → Branded dispatch email.

Colour	Default	Controls
Background	#f0fdf4	The fill behind the entire tracking block
Left border	#16a34a	The 4px accent bar on the left edge of the block
Button background	#111827	The "Track on Royal Mail →" button fill
Button text	#ffffff	Text and arrow colour on the button

Each field has a colour picker — click the swatch to open the picker. Changes apply to all dispatch emails sent after saving.

Advanced: theme-level filter overrides

For dynamic colours (different per child theme or based on order data), use filters in your theme's functions.php. Filters take priority over the settings UI.

add_filter( 'djrmcdpro_email_block_bg',     fn() => '#f0fdf4' ); // block background
add_filter( 'djrmcdpro_email_block_border', fn() => '#16a34a' ); // left border accent
add_filter( 'djrmcdpro_email_button_bg',    fn() => '#111827' ); // button fill
add_filter( 'djrmcdpro_email_button_color', fn() => '#ffffff' ); // button text

Advanced: full template override

To change the layout, structure, or any element not exposed in settings, copy the Pro template file to your theme:

wp-content/plugins/dj-royal-mail-pro/templates/email-tracking-block.php
      → copy to →
wp-content/themes/your-theme/dj-royal-mail-pro/email-tracking-block.php

WordPress loads your theme's version automatically. The template receives: $tracking_number, $tracking_url, $site_track_url, $order, plus the four colour variables.

Pro: dispatch webhooks Pro

Go to WooCommerce → Royal Mail Pro → Dispatch Webhooks. Paste a Slack, Discord, or Microsoft Teams incoming-webhook URL. The plugin POSTs a Slack-style {"text":"…"} payload (which all three services accept) every time a Royal Mail tracking number is recorded against an order.

Default message template:

📦 Order #{order_number} dispatched — tracking {tracking_number} → {tracking_url}

Available placeholders: {order_number}, {tracking_number}, {tracking_url}, {customer_name}, {order_total}.

For advanced payload customisation (Slack blocks, Discord embeds, Teams adaptive cards), use the djrmcdpro_webhook_payload filter:

add_filter( 'djrmcdpro_webhook_payload', function ( $payload, $order, $tracking ) {
    // Replace the simple text payload with a Slack blocks payload, etc.
    return $payload;
}, 10, 3 );

Pro: bulk CSV import Pro

Two columns, with or without a header row:

order_number,tracking_number
1234,VU032331508GB
1235,VU032331509GB

Order numbers may optionally be prefixed with #. Tracking numbers are uppercased and validated against the Royal Mail format (two letters, 8–9 digits, two letters).

From the admin UI

WooCommerce → Royal Mail Pro → Bulk CSV Import, choose a file, upload. You'll get a notice with counts: imported / skipped / failed.

From WP-CLI

wp djrmcdpro import-csv /path/to/file.csv

Click & Drop API setup

1. Log in to Click & Drop
2. Go to Settings → Integration API
3. Click Generate API key (or copy your existing key)
4. In WP Admin → WooCommerce → Royal Mail Tracking, paste the key and save

You also need Click & Drop connected to WooCommerce via the WooCommerce REST API so that Click & Drop can write dispatch notes back to your orders:

1. WP Admin → WooCommerce → Settings → Advanced → REST API → Add key (read/write)
2. In Click & Drop → Settings → WooCommerce, add your store URL and the REST API credentials

Track Order page Free

Create a page and add the [dj_track_order] shortcode (or the DJ Track Order Gutenberg block). The page supports three search modes:

Mode	What customer enters
order	Order number + email address
email	Email address alone (shows all orders)
tracking	Royal Mail tracking number directly

Control which modes are active via shortcode attributes:

[dj_track_order modes="order,tracking"]
[dj_track_order title="Where's My Order?" description="Enter your details to track."]
[dj_track_order show_logged_in_orders="no"]

WP-CLI reference

Free plugin

# Show plugin status + ping the C&D API
wp djrmcd status

# Backfill tracking for completed orders
wp djrmcd backfill --since=2026-01-01 --limit=500
wp djrmcd backfill --dry-run
wp djrmcd backfill --force --limit=50

Pro add-on

# Show Pro licence + configuration status
wp djrmcdpro status

# Bulk-import tracking numbers from a CSV file
wp djrmcdpro import-csv /tmp/dispatch-batch.csv

HPOS compatibility

Both plugins are fully compatible with WooCommerce's High Performance Order Storage (HPOS). All order data is accessed via wc_get_order() and $order->update_meta_data() — never via direct wp_postmeta queries. The Pro orders-list column and bulk action register on both classic and HPOS hook variants.

Both plugins declare HPOS compatibility via FeaturesUtil::declare_compatibility() so WooCommerce will not show a compatibility warning.

Troubleshooting

Tracking number not being fetched automatically

• Confirm your API key is saved correctly in WooCommerce → Royal Mail Tracking
• Check the order reference prefix matches — Click & Drop must show the order as e.g. #1234
• Run wp djrmcd backfill --dry-run to test the query without writing
• Check WooCommerce logs: WP Admin → WooCommerce → Status → Logs → filter by tracking-for-royal-mail-click-drop

Dispatch email not showing tracking

• Confirm "Dispatch email line" is enabled in settings
• The tracking number must be stored before the Order Complete email fires — if the order completed before the tracking number was available, the email won't include it (but future emails will)
• If you expect the branded HTML block but see plain text instead: confirm the Pro add-on is installed, activated, and has a valid licence

404 on Track Order page

• Ensure the page exists and contains the [dj_track_order] shortcode
• Go to WP Admin → Settings → Permalinks and click Save to flush rewrite rules

Pro features disabled even with the licence active

• Confirm the free plugin is also active — Pro depends on it
• Confirm the licence is active in the Pro plugin's settings (look for the "Activate licence" banner — if it's there, the licence isn't recognised)
• If the orders column or bulk action isn't showing on HPOS-mode stores: ensure WooCommerce is current (HPOS hook names changed across versions)

HPOS: tracking not showing on order page

• With HPOS active, tracking is stored in order tables, not postmeta. If you're reading it with get_post_meta() in custom code, switch to wc_get_order($id)->get_meta('_dj_rm_tracking_number')