Aller au contenu principal

WooCommerce integration

WooCommerce stores connect to Alkax from Developer Console → E-commerce → WooCommerce. The Developer Project is the tenant boundary, and every store chooses either Sandbox or Production.

Unlike Shopify, WooCommerce does not require a platform OAuth client for this integration. A thin Alkax for WooCommerce WordPress plugin acts as the store-side agent while the shared woocommerce.alkax.io runtime holds the managed Alkax credential.

Requirements​

  • WordPress with WooCommerce 10.3 or newer.
  • PHP 8.1 or newer.
  • The Alkax for WooCommerce plugin installed and activated.
  • An Alkax Developer Project.

WooCommerce 10.3 introduced the native address-autocomplete provider API used here. The provider registration is shared by shortcode and block-based checkout, so the plugin does not patch checkout DOM markup.

Connect a store​

  1. Install and activate Alkax for WooCommerce in WordPress.
  2. In Alkax, open Developer Console and select the owning project.
  3. Open E-commerce → WooCommerce.
  4. Enter the canonical store URL, for example https://shop.example.com.
  5. Choose Sandbox or Production.
  6. Choose Connect store.
  7. WordPress opens WooCommerce → Alkax with a one-time pairing request.
  8. A WooCommerce administrator approves the connection.

The resulting binding is:

DeveloperProject.Id    -> tenant identity
DeveloperEnvironment   -> Sandbox or Production execution/billing context
WooCommerce store URL  -> connected store

Developers do not paste Alkax API keys, WooCommerce REST consumer keys, or webhook secrets.

Address autocomplete​

The plugin registers an Alkax WC_Address_Provider and client provider with WooCommerce. WooCommerce supplies the suggestion UI and fills its normal address fields.

The buyer-facing JavaScript calls a same-store WordPress REST endpoint. WordPress signs a server-to-server request to woocommerce.alkax.io; the shared runtime then calls the project-scoped Alkax suggestion API with the managed credential.

Woo checkout
  -> Alkax Woo provider
  -> WordPress /wp-json/alkax/v1/address-suggestions
  -> woocommerce.alkax.io
  -> GET /api/v1/addresses/suggestions

The connection secret and Alkax credential never reach checkout JavaScript. If Alkax is temporarily unavailable, the provider returns no suggestions and WooCommerce manual address entry remains usable.

The selected result preserves an Alkax Plus Code in the normal Woo address fields when one is available, allowing later delivery creation even when the order has no latitude/longitude.

Optional order tracking​

Tracking is enabled per connected store in the Developer Console.

The WordPress plugin listens to both classic checkout and Store API/block checkout order creation hooks and funnels them into one asynchronous sender. The shared runtime is idempotent on the connected store + Woo order ID, so duplicate hooks or retries cannot create multiple Alkax deliveries.

Only the shipping destination and stable order identity are sent. Recipient name, email, phone and account profile data are not sent to Alkax.

Destination handling is:

  1. use stored Woo shipping coordinates when available;
  2. otherwise detect an Alkax Plus Code in the address;
  3. resolve that Plus Code through Alkax;
  4. create the delivery only when usable coordinates exist;
  5. otherwise retain an awaiting_address mapping rather than creating a 0,0 delivery.

The customer's Woo order-details page can show the latest Alkax tracking number/state through a signed server-to-server lookup.

Request security​

Pairing creates a random ten-minute handoff. Alkax persists only its hash and redemption is one-time.

After activation:

  • the shared runtime receives an automatically issued project/environment Alkax credential;
  • WordPress receives only a per-connection HMAC signing secret;
  • signed plugin requests bind timestamp, nonce, HTTP method, path and body hash;
  • the runtime rejects requests outside a five-minute clock window;
  • nonces are stored briefly and cannot be replayed;
  • disconnect revokes the managed Alkax credential and deactivates runtime access.

ALKAX_WOOCOMMERCE_PLUGIN_SIGNING_KEY is the runtime-only root used to derive store connection secrets. Rotating it invalidates existing pairings, so stores must reconnect after a root-key rotation.

HPOS and checkout compatibility​

The plugin declares compatibility with WooCommerce High-Performance Order Storage (HPOS) and Cart/Checkout Blocks. It reads orders with WC_Order / wc_get_order() and does not query WordPress order tables directly.

Maintainer configuration​

The integration lives under integrations/woocommerce/:

plugin/   WordPress/WooCommerce store agent
runtime/  shared service deployed at woocommerce.alkax.io

Runtime configuration:

DATABASE_URL=postgresql://...
ALKAX_API_URL=https://<alkax-api-host>
ALKAX_WOOCOMMERCE_SERVICE_KEY=<control-plane service identity>
ALKAX_WOOCOMMERCE_PLUGIN_SIGNING_KEY=<plugin signing root>

The Alkax backend receives the matching:

WooCommerceIntegration:AppUrl=https://woocommerce.alkax.io
WooCommerceIntegration:ServiceKey=<same control-plane service identity>

Validation:

php -l integrations/woocommerce/plugin/alkax-for-woocommerce.php
node --check integrations/woocommerce/plugin/assets/address-autocomplete.js

cd integrations/woocommerce/runtime
npm install
npm test
npm run typecheck
npm run build

For the WooCommerce provider API, see the WooCommerce address autocomplete documentation.