WooCommerce integration

The Maxmove Delivery for WooCommerce plugin adds Maxmove as a shipping method, quotes delivery at checkout, creates a Maxmove delivery from each qualifying order, and writes delivery status and the tracking link back to the order.

For click-by-click setup, see Set up the Maxmove WooCommerce plugin.

Plugin facts#

How it connects#

The plugin does not use the public /v1 API or /v1 API keys. It talks to a dedicated WooCommerce API at https://api.maxmove.com (the address is fixed), and its orders send no /v1 webhook events.

1. Link token

   An admin of a Maxmove business workspace creates a single-use link token in the dashboard under Integrations → WooCommerce. It is valid for 15 minutes and approved for the store address saved there.

2. Connect

   The merchant pastes the token in WooCommerce → Maxmove. The plugin sends it to Maxmove with the store URL and its callback URL, /wp-json/maxmove/v1/webhooks. Store and callback must be on the approved host, and the callback must be publicly reachable.

3. Plugin credentials

   Maxmove returns credentials that the plugin sends as a bearer token from then on. They are renewed while in use, and the plugin checks the connection daily. If Maxmove rejects them, the plugin deletes its local credentials and the store must reconnect.

One store connects to one business workspace, and each workspace has one active WooCommerce connection.

Checkout#

When the shopper's address matches a zone with the Maxmove method enabled, the plugin requests a quote with:

• the store's pickup address and the delivery address,
• the cart currency and merchandise subtotal,
• up to 4 pickup times: the earliest possible and 2-hour slots within the store's opening hours,
• the language (English or German; other WordPress languages fall back to English).

The plugin doesn't send line items, weights, or dimensions. Maxmove geocodes the addresses.

The shopper sees the price from the store's pricing policy (live price with an adjustment, fixed price, free delivery above a subtotal, and a cap on the carrier cost), not necessarily the carrier price. Each rate is signed, so the order can later be checked against what the shopper accepted.

Maxmove hides the method, with a generic notice, when it can't quote: for example when the cart has more than one shipping package, the currency doesn't have exactly two decimals, no pickup time is available, the API doesn't answer in time, or the workspace's billing isn't ready.

Data flow#

1. Order status changes

   When an order with a Maxmove shipping line reaches one of the ready statuses (by default processing and completed), and, if required, is paid, the plugin queues it in Action Scheduler.

2. Order sent to Maxmove

   The plugin sends the order in the background and retries network errors, 429, and 5xx answers with backoff, honouring Retry-After. A reconciler runs every 5 minutes for orders that are still missing, and the merchant can retry from the order with Retry Maxmove delivery.

3. Delivery created

   Maxmove re-prices the route and rejects the order if the price exceeds what the shopper accepted. One WooCommerce order becomes at most one Maxmove delivery, and each signed rate can only be used for one order. Orders with more than one Maxmove package are blocked.

Status sync#

Maxmove pushes status to the plugin's callback URL; the plugin doesn't poll. The webhook request carries these headers:

These are not the /v1 webhook events and use their own event names and signature. The plugin stores the delivery stage and tracking URL on the order and shows the status and tracking link in My Account and in customer emails. It does not change the WooCommerce order status by default; a theme or plugin can map events to order statuses with the maxmove_woocommerce_order_status_for_event filter.

Payment#

The shopper pays the store. Maxmove charges the business workspace's company card per delivery: it authorizes the amount when it imports the order and captures it after completion. If billing isn't ready, the order waits in Maxmove until the merchant completes billing setup.

Cancellations#

• An order set to cancelled or refunded in WooCommerce cancels the Maxmove delivery. If the courier already picked up the goods, the cancellation is rejected and the plugin marks the order for manual action.
• A delivery cancelled by Maxmove doesn't cancel or refund the WooCommerce order.
• Partial refunds are not synced.

Settings#

In WordPress, the merchant sets the link token, the pickup address, the ready order statuses, and per zone whether the method is enabled and its title. Pricing, automatic import, paid-order requirement, vehicle type, extra services, and scheduling are managed in the Maxmove dashboard and shown read-only in the plugin.

Data stored by the plugin#

The plugin keeps its settings and credentials in the maxmove_woocommerce_settings option, _maxmove_* order meta, a webhook ledger table (30 days, for deduplication), and a privacy job table. Deactivating the plugin disconnects the store and deletes the credentials. Uninstalling it removes its tables and options; existing _maxmove_* order meta stays.