Skip to main content

WooCommerce Adapter Status

Source-backed status note for WooCommerce work in apps/backend/src/ecommerce/.

Use this page to avoid confusing reserved schema/supporting design with shipped runtime behavior.

Current runtime status​

WooCommerce is not started at runtime (reserved schema/planning only).

Do not describe WooCommerce as "in progress" or merchant-available until an adapter is registered and connect/webhook/PWA paths are verified together.

What exists today:

  • the ecommerce_provider persistence enum includes woocommerce
  • repository types accept records whose provider value is woocommerce
  • the provider port is platform-neutral enough for a future adapter
  • Swagger on EcommerceConnectionResponseDto.provider lists ["shopify", "woocommerce"] for response documentation only
  • a planning reference exists at apps/docs/docs/ecommerce/woocommerce-adapter-reference.md

What does not exist today:

  • no apps/backend/src/ecommerce/infrastructure/woocommerce/ adapter
  • no woocommerce entry in EcommerceProviderFactory
  • no WooCommerce webhook controller
  • no credential-based connect endpoint or DTO (ConnectEcommerceDto accepts only shopify)
  • no PWA WooCommerce credential form or "Connect WooCommerce" settings step

Until those pieces are implemented and registered, API consumers should treat woocommerce as a reserved forward-compatibility value. A successful connect or webhook path for WooCommerce is not possible with the current factory and DTO surface.

Source-backed provider matrix​

ConcernShopifyWooCommerce
Factory registrationshopify -> ShopifyAdapternot registered
Connect flowOAuth through GET /ecommerce/oauth/url and GET /ecommerce/oauth/callbacknot implemented
Accepted connect DTO/provider enumConnectEcommerceDto accepts only shopifynot accepted
Connection response Swagger enumdocuments shopifyalso documents woocommerce even though connect cannot create one
Webhook routePOST /ecommerce/webhooks/shopifyno route
Webhook parserorders/create produces an EcommerceOrder; inventory_levels/update returns nullno parser
PWA connect UIShopify OAuth cardno WooCommerce credential form

Swagger response enums and persistence enums are not proof of a shipped adapter. Always check EcommerceProviderFactory and ConnectEcommerceDto before treating a provider as runnable.

Architecture boundary​

The domain port should stay provider-neutral:

  • product and collection push
  • inventory level update
  • order pull and acknowledge
  • webhook signature verification
  • webhook payload parsing

WooCommerce-specific HTTP details belong in an infrastructure adapter. A future implementation should not put WordPress/WooCommerce request shapes into domain entities unless another provider needs the same concept.

Application-level branching may still be needed for connection setup because the current port models OAuth methods, while WooCommerce setup is expected to be credential-based rather than redirect-based.

Expected implementation shape​

A future WooCommerce implementation should add:

  1. WoocommerceAdapter under apps/backend/src/ecommerce/infrastructure/.
  2. Provider registration in EcommerceProviderFactory.
  3. A credential-based interface path for store URL, Consumer Key, and Consumer Secret.
  4. Webhook registration and a WooCommerce webhook controller using the WooCommerce signature header.
  5. PWA setup UI for credential entry and connection testing.
  6. Tests mirroring the Shopify adapter, webhook controller, service, and polling coverage.

Keep these changes in the ecommerce module boundary. Do not modify FEL, MCP, or PSA provider ports for WooCommerce-specific behavior.

Operational risks to plan for​

WooCommerce stores are self-hosted, so operational behavior varies more than Shopify. The future adapter should surface clear sync-log errors for:

  • REST API access blocked by WordPress or hosting configuration
  • missing or invalid REST API keys
  • unsupported WooCommerce REST API versions
  • webhook delivery failures
  • product or stock updates blocked by security plugins

Do not document WooCommerce as available to merchants until the adapter, backend routes, and PWA connection flow are all verified together.