Riders Delivery for WooCommerce

Description

Riders Delivery for WooCommerce connects your WooCommerce store to the Riders Kuwait delivery platform. It handles the entire flow — from address capture at checkout all the way to order delivery and tracking.

Key Features

  • Kuwait address widget at both classic and Blocks (Gutenberg) checkout: Governorate Area Block Street House cascading dropdowns
  • Civil ID / PACI lookup — customers can auto-fill their address from their Kuwaiti civil ID number
  • Automatic or manual order sync to Riders via Action Scheduler background jobs
  • Delivery status polling — order status updated every 5 minutes; or instantly via webhook push
  • Webhook support — receive real-time status updates from Riders (HMAC-verified)
  • Admin orders list — filter by sync status, retry failed orders individually or in bulk
  • Per-order meta box — view sync status, delivery fee, fleet number, and edit the Kuwait address with cascading dropdowns directly in the WooCommerce order
  • Tracking links — fleet tracking link appended to WooCommerce order completion emails
  • Proper WC_Shipping_Method — add Riders Delivery to any shipping zone with configurable flat rate and free-shipping threshold
  • WooCommerce REST API extension/wc/v3/orders responses include ridedefo_sync_status, ridedefo_uid, and ridedefo_fleet_number
  • English and Arabic (RTL) support
  • HPOS compatible — High-Performance Order Storage declared and tested
  • Idempotent sync — duplicate delivery prevention with syncing-status guard
  • Transient-cached geo data — governorates/areas/blocks/streets cached for 1 hour to reduce API calls

Requirements

External Services

This plugin connects to the Riders delivery platform (https://tryriders.com) to sync WooCommerce orders and retrieve Kuwait address data.

API endpoint: https://app-order.tryriders.com/api
API documentation: https://app-order.tryriders.com/docs/vendor
Vendor portal: https://vendor.tryriders.com

Data sent to Riders:

  • Order details (items, total, billing/shipping address, customer phone) — when an order is synced
  • Kuwait Civil ID number — only when a customer voluntarily uses the PACI lookup to auto-fill their address

All requests are made over HTTPS. A Riders vendor account and API key are required.
Please review the Riders website (https://tryriders.com) for terms and privacy information before using this plugin.

Development

Source code: https://github.com/Phoenix-H22/riders-woocommerce-plugin

The Blocks checkout script is built with @wordpress/scripts.

Source: assets/checkout/blocks/src/index.js
Compiled output: assets/checkout/blocks/build/index.js

The same source is also included in this plugin package under assets/checkout/blocks/src/.

To rebuild from source:

  1. npm install
  2. npm run build

Screenshots

Installation

  1. Upload the plugin folder to /wp-content/plugins/ or install via the WordPress plugins screen.
  2. Activate the plugin through the Plugins screen.
  3. Ensure WooCommerce is installed and active.
  4. Go to WooCommerce Riders and enter your Riders API key.
  5. Click Verify API Key, select your default branch, and configure sync options.
  6. (Optional) Enable Auto-configure Kuwait shipping zone under WooCommerce Riders Sync if you want Riders to create a starter Kuwait zone for you.
  7. (Optional) Add Riders Delivery as a shipping method in WooCommerce Settings Shipping Zones.

FAQ

Does this work with the WooCommerce Blocks checkout?

Yes. Both the classic shortcode-based checkout and the new Blocks (Gutenberg) checkout are fully supported.

Is High-Performance Order Storage (HPOS) supported?

Yes. The plugin declares compatibility and all order data access uses HPOS-safe WooCommerce APIs.

What phone number format does Riders require?

Kuwait mobile numbers in E.164 format, e.g. +96550123456. The plugin automatically normalises 8-digit local numbers, international prefix variants, and the 9-digit format with a leading zero (e.g. 050123456).

How does the webhook work?

Register https://your-store.com/wp-json/ridedefo/v1/webhook as a webhook endpoint in your Riders vendor portal. The plugin verifies the HMAC-SHA256 signature on every request and updates the WooCommerce order status in real time.

Can I use delivery notes templates?

Yes. Go to WooCommerce Riders Settings and set a default delivery notes template. You can use {order_id}, {customer_name}, and {items} as placeholders.

How do I retry failed syncs?

Open WooCommerce Riders Orders, click Retry All Failed to requeue all failed/review-needed orders at once, or use the per-order Sync button.

Reviews

There are no reviews for this plugin.

Contributors & Developers

“Riders Delivery for WooCommerce” is open source software. The following people have contributed to this plugin.

Contributors

Changelog

1.2.1

  • Included Blocks checkout source (assets/checkout/blocks/src) and build tooling in the plugin package.
  • Documented public source repository and npm build steps in the readme.

1.2.0

  • Renamed internal WordPress prefixes from riders_* to unique ridedefo_* (options, meta, hooks, REST, AJAX, table, shipping method).
  • Added upgrade migration for options, custom table, order meta, Action Scheduler hooks, and shipping method instances.
  • REST namespace is now ridedefo/v1 (webhook URL: /wp-json/ridedefo/v1/webhook).
  • Civil ID / PACI lookup now requires a dedicated action nonce, same-origin check, checkout session, and a stricter rate limit.
  • Removed bundled .po/.mo translation files (translations via translate.wordpress.org after approval).
  • Plugin slug and text domain riders-delivery-for-woocommerce are unchanged.

1.1.1

  • Moved settings page CSS/JS to enqueued admin assets.
  • Geo REST endpoints now require a valid wp_rest nonce (PACI lookup included).
  • WooCommerce log directory resolved via wc_get_log_directory() / wp_upload_dir().

1.0.0

  • Initial release with full Kuwait address widget, classic + Blocks checkout support, auto/manual sync, PACI lookup, admin orders page, and per-order address editor.

1.1.0

  • Added idempotency guard to prevent duplicate Riders deliveries on concurrent sync jobs.
  • Fixed sync status overwrite on already-synced orders.
  • Added country guard to classic checkout save — non-Kuwait orders no longer get Kuwait address meta.
  • Fixed shipping-address formatter to respect “ship to different address” with non-KW shipping country.
  • Fixed COD unpaid order logic in onOrderProcessing.
  • Added DB migration on plugin update (no longer requires deactivate/reactivate).
  • Fixed Blocks checkout silent pass when extension data is null for Kuwait orders.
  • Fixed RiderOrder::updateOrCreate() race condition on concurrent inserts.
  • Added WooCommerce Subscriptions renewal guard — renewal orders skipped from auto-sync.
  • Hooked woocommerce_delete_order / woocommerce_trash_order to clean up ridedefo_orders row.
  • Deactivation now unschedules all pending sync jobs, not just polling.
  • uninstall.php now deletes all _ridedefo_* order meta from both classic and HPOS tables.
  • Fixed riders_is_cancellable bool coercion bug ("0" was casting to true).
  • Added 050xxxxxxx (9-digit with leading zero) to Kuwait phone normalizer.
  • Sanitized geo REST endpoint 502 error responses — raw API errors no longer exposed publicly.
  • RidersApiClient now throws on HTTP 2xx + non-JSON body instead of silently returning empty array.
  • After saving address in the admin, sync is now auto-dispatched (no separate Retry Sync click needed).
  • Added 1-hour transient caching to all geo endpoints; cache cleared on API key change.
  • wc-shipped custom status registered as public => false (not visible in front-end order queries).
  • HTTP timeout now filterable via ridedefo_api_timeout filter.
  • Added proper WC_Shipping_Method subclass (ridedefo_delivery) for use in WooCommerce Shipping Zones.
  • Added Riders tracking link to WooCommerce order completion emails.
  • Added real-time webhook endpoint (POST /ridedefo/v1/webhook) with HMAC-SHA256 verification.
  • Added delivery notes template variable substitution ({order_id}, {customer_name}, {items}).
  • Extended /wc/v3/orders REST API with ridedefo_sync_status, ridedefo_uid, ridedefo_fleet_number, ridedefo_error.
  • Added Retry All Failed one-click button on the Riders Orders admin page.
  • AddressValidator now used as single validation entry point for both classic and Blocks checkout.
  • Added checkout notice (not hard block) when block or house is missing from Kuwait address.