WooCommerce Integration

“Connected” is not the same as “correctly integrated”

Imagine two WooCommerce stores. Both expose orders, but one installs an extension that adds a custom status and metadata. At the same time, a webhook is retried after a timeout. If the connector simply receives JSON and writes status into internal state, several questions become unanswerable: Did the message really come from that store? What can the API key do? Is the retry the same event or a new event? What does the custom status mean? Are assumptions from Store A valid for Store B?

The lesson output is WooCommerce Connector Contract and Webhook Ledger v1. The goal is not merely to build a WooCommerce client; it is to make every WooCommerce-to-domain promotion reconstructible from explicit evidence.

COM-028 ownership boundary

COM-028 owns the WooCommerce-specific integration boundary: site identity, REST surface, credential scope, order/status mapping, webhook verification, delivery evidence, extension isolation and reconciliation. COM-029 owns provider-agnostic connector architecture. COM-027 owns Shopify-specific integration.

Three red lines:

1. WooCommerce status != canonical state
2. valid HMAC != business completion
3. same plugin name on two sites != same contract

Mental model: Site → REST/Auth → Order observation → Webhook verification → Site adapter → Mapping version → Dedupe/Reconcile → Canonical promotion

Auditable path:

site_ref → wc/v3 + credential_scope → order_id/order_key_ref/created_via/wc_status → webhook_id/topic/status → signature_check + payload_digest + delivery_attempt → custom namespace + extension assumption → mapping_version → reconciliation_state → canonical_order_state → evidence_ref

Each layer owns a different failure class. Do not fix signature failures in mapping. Do not solve a custom status by copying its string into the domain. Do not close a retry with “it is probably the same one.”

Separate FACT, INFERENCE and DESIGN

FACT: Current WooCommerce documentation identifies REST API v3 as the current and recommended REST API version for new integrations and exposes Orders under wc/v3.

FACT: A WooCommerce REST API key is associated with a WordPress user and an access level such as read, write or read_write. Over HTTPS, Consumer Key/Secret Basic Auth is documented.

FACT: A WooCommerce webhook has topic, status, delivery URL and secret semantics; the secret is used to produce an HMAC-SHA256 signature over the request body, and webhook headers include IDs such as webhook and delivery identifiers.

INFERENCE: Because stores can differ by plugins, custom statuses, metadata and workflows, two WooCommerce sites do not necessarily expose the same effective contract. Plugin/site assumptions should therefore be versioned and scoped.

DESIGN: MAKNOW requires mapping evidence, signature evidence, site namespace isolation and reconciliation before promoting a WooCommerce observation into canonical state. Those are local design rules, not WooCommerce requirements.

The 22-dimension WooCommerce contract

Gate 1 — Give the connector and site explicit identity

connector_id and site_ref bind evidence to one store and adapter. “WooCommerce production” is not enough identity.

Gate 2 — Pin the REST surface

rest_api_version must be explicit. For new integration work this lesson uses wc/v3 as the baseline. An endpoint alone is not the contract; version is part of the contract.

Gate 3 — Separate credential type from credential scope

Having a Consumer Key/Secret does not prove the key is permitted to perform the operation. credential_scope must match the required read/write behavior. Real secrets are never stored in the lesson artifact; only a reference and scope are recorded.

Gate 4 — Keep order identity distinct from display identity

order_id, order_key_ref and created_via answer different traceability questions. Keep order_key_ref as a bounded reference rather than unnecessarily copying sensitive operational values into learner-facing evidence.

Gate 5 — wc_status is an external observation

processing, on-hold, or a custom plugin status are WooCommerce facts. canonical_order_state comes only through a versioned mapping. Raw provider status must not directly drive downstream domain logic.

Gate 6 — Bump mapping version when meaning changes

If a plugin introduces awaiting-pickup, or changes the meaning of a metadata field, the previous mapping_version is no longer sufficient evidence. Until a new mapping is reviewed, the result is HOLD_MAPPING_VERSION.

Gate 7 — Verify the webhook before using it

webhook_id, webhook_topic and webhook_status describe message context. signature_check must verify the received raw body using the configured secret reference. Invalid or unknown verification yields HOLD_WEBHOOK_SIGNATURE.

Gate 8 — Signature proves authenticity, not business completion

A valid HMAC means the body is consistent with the configured secret. It does not prove fulfillment, canonical correctness or exactly-once delivery.

Gate 9 — Record payload digest and delivery attempt

payload_digest and delivery_attempt make replay/retry reasoning auditable. If the same delivery is applied twice, the connector is wrong even if both HTTP requests were successful.

Gate 10 — Namespace and site-scope extensions

custom_field_namespace and extension_assumption must show which plugin/field/status applies to which site. Do not reuse Store A assumptions on Store B without revalidation.

Gate 11 — Reconcile uncertainty before promotion

reconciliation_state shows how webhook evidence was closed against a REST snapshot, event ledger or another bounded method. Timeouts, retries and custom statuses must not silently become clean success.

Gate 12 — Missing decisive evidence fails closed

Unknown REST version, credential scope, signature, digest, mapping or reconciliation yields typed HOLD/PARTIAL states rather than optimistic acceptance.

Worked examples

1. Standard baseline → ACCEPT_CONNECTOR

Store A pins wc/v3, the credential has only the required scope, order identity is traceable, the webhook is active, signature is verified, digest is recorded, mapping is versioned and reconciliation is closed.

2. Webhook without valid signature → HOLD_WEBHOOK_SIGNATURE

A payload that looks like a real order is still unusable for promotion until authenticity is verified.

3. Plugin adds a status while map-v5 remains unchanged → HOLD_MAPPING_VERSION

Parsing the new string does not prove its canonical meaning.

4. A second delivery re-applies the same side effect → HOLD_RECONCILIATION

delivery_attempt=2 with the same digest must trigger dedupe/reconciliation, not a second business mutation.

5. Store A plugin assumption is reused on Store B → HOLD_EXTENSION_SCOPE

Same plugin name is not proof of same version, configuration or field semantics.

6. Transfer: a new wc-awaiting-pickup status

Scope the extension to the correct site, bump mapping version, re-check webhook evidence, and reconcile with a REST snapshot. If meaning cannot be mapped safely, keep HOLD rather than extending the canonical state model for adapter convenience.

Common failure modes

• one over-privileged Consumer Key for every operation;
• copying real secrets into examples or logs;
• writing wc_status directly into canonical state;
• assuming REST v3 makes every store’s effective contract identical;
• accepting a webhook because its URL/ID looks right;
• treating a valid signature as fulfillment success;
• applying a retried webhook twice;
• introducing a custom status without a mapping-version bump;
• reusing custom-field assumptions across sites;
• no REST pull/reconciliation path for uncertainty;
• unnecessarily copying order keys or customer data into evidence artifacts;
• copying the baseline result into transfer without recomputation.

Alternatives and trade-offs

REST-only polling: simple and controllable, but increases latency and API load. Strong for reconciliation, not always ideal for fast reaction.

Webhook-only: low latency, but duplicate/replay/missed delivery and disabled webhook states still need handling. It is not sufficient by itself.

Webhook + bounded REST reconciliation: more contract work, but better closes uncertainty and is the bounded pattern used here.

Raw WooCommerce model downstream: fast start, high coupling to plugin/site semantics.

Versioned site adapter: more design work, but keeps custom status/meta behavior at the site boundary and stabilizes downstream consumers.

Experienced bridge: sixteen review questions

1. What exactly are connector_id and site_ref?
2. Which rest_api_version is pinned?
3. Which user/permission scope owns the credential?
4. Is the operation read-only or does it require write access?
5. How are order_id and order_key_ref traced?
6. What assumption does created_via change?
7. How does wc_status map to canonical state?
8. What triggers a mapping-version bump?
9. What are webhook topic and status?
10. How was the signature verified against the raw body?
11. What is the payload digest?
12. How are duplicate deliveries detected?
13. Which namespace owns custom fields/statuses?
14. Which site/plugin version bounds the assumption?
15. How is uncertainty reconciled?
16. Can a reviewer reconstruct the decision from evidence_ref alone?

Guided and independent practice

The offline lab has eight fixtures: baseline, invalid signature, custom status without mapping bump, duplicate side effect, cross-site assumption reuse, insufficient credential scope, missing digest evidence and a correct custom-status transfer.

Independent task: a merchant installs an extension that introduces awaiting-pickup and a pickup_slot field. Update the adapter; state what remains site-specific, when mapping must change, what webhook/reconciliation evidence is required, and why another store’s baseline is not the oracle.

Verification evidence

A passing artifact fills all 22 dimensions or returns an explicit typed non-success state. No real secret is stored; REST version and credential scope are traceable; raw wc_status never becomes canonical truth directly; signature is checked before webhook acceptance; digest/attempt evidence makes duplicate behavior auditable; extension assumptions remain site-scoped; and transfer recomputes mapping independently.

The lab is fully synthetic and offline. It requires no network, API key, real store or customer data.

Assessment and transfer

To finish the lesson you must be able to:

1. explain COM-028’s boundary against COM-027 and COM-029;
2. build WooCommerce Connector Contract and Webhook Ledger v1;
3. pin wc/v3 and credential scope explicitly;
4. separate webhook authenticity from business correctness;
5. reject a custom status without a new mapping version;
6. reconcile duplicate delivery without duplicate side effects;
7. keep extension assumptions site-scoped;
8. rebuild a plugin/status transfer without polluting the canonical model.

References and freshness

• WooCommerce REST API v3 — rechecked 15 September 2026; FACT source for the current/recommended REST surface and wc/v3.
• WooCommerce Authentication — rechecked 15 September 2026; FACT source for API-key ownership and access level.
• WooCommerce Orders API — rechecked 15 September 2026; FACT source for order fields such as id, order_key, created_via and status.
• WooCommerce Webhooks — rechecked 15 September 2026; FACT source for topic/status/delivery URL, HMAC-SHA256 signature and delivery headers.
• WooCommerce Order Statuses — rechecked 15 September 2026; current context for core status semantics. Extension isolation and canonical promotion policy are MAKNOW DESIGN.