Riders Delivery for WooCommerce

By ridersdevelopers

10+ active installationsVersion 1.2.2

Sync WooCommerce orders to the Riders Kuwait same-day delivery platform with a full Kuwait address widget at checkout.

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

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.

Screenshots

Changelog

1.2.2

  • Paid orders now sync automatically with gateways that mark orders Processing/Completed without firing payment_complete (e.g. MyFatoorah).
  • Paid orders stuck in “Awaiting Payment” are released by the manual Sync button, the order-received page, and the 5-minute background check.
  • Added Scheduled Delivery setting: send a fixed delivery date and time to Riders as schedule_date.
  • Orders with Delivery Date / Time Slot custom fields are sent to Riders with that date and the slot’s start time (field names configurable).
  • schedule_date is sent in the store’s local time.
  • When Riders has no location for the house, the street, block, or area location is used instead, with an order note.
  • RIDEDEFO_WC_LOGGING can now be defined in wp-config.php.

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.