Connect WooCommerce end to end

WooCommerce is the self-hosted WordPress e-commerce option in the Integrations catalog. Unlike the OAuth-backed entries (Shopify, HubSpot), WooCommerce connects with a REST API key pair — you generate a consumer key and consumer secret in WordPress admin and paste them into a dialog. No consent screen, no redirect. This guide walks the whole flow: generating the key pair, connecting, understanding what syncs, building messaging flows off the events, and revoking cleanly when you’re done.

The connect step is owner/admin only — it’s the only step that touches store credentials. Everything after connect (syncs, event ingest) is automatic.

1. Where to find it

Open Settings → Integrations. In the discovery sidebar pick Ecommerce — the WooCommerce card sits alongside Shopify. The card’s CTA reads Paste API key, not “Connect,” because there is no OAuth consent step for this integration.

2. What does it do?

Once connected, Orbit syncs your WooCommerce customers, orders, and products on a scheduled poll and ingests them into your contact list and CDP event stream. Two messaging patterns become available immediately:

Post-purchase flows — order created / updated events land as woocommerce.order events you can trigger on (thank-you, review request, fulfillment follow-up) over SMS or WhatsApp.
Abandoned-cart recovery — checkout/cart events let you fire a drip with a recovery link, over SMS or WhatsApp.

3. Generate the consumer key pair in WordPress

Do this first, in the WordPress admin of the store you want to connect:

In WordPress admin, go to WooCommerce → Settings → Advanced → REST API.
Click Add key.
Give the key a description (e.g. “Orbit”), pick the WP user it will run as, and set Permissions to Read/Write.
Click Generate API key. WordPress shows the Consumer key (starts with ck_) and Consumer secret (starts with cs_) — shown exactly once. Copy both before leaving the page.

Store readiness checklist — the v3 REST API needs all of these:

WooCommerce 3.6 or newer (the v3 API namespace the integration probes).
Permalinks set to a “pretty” mode (Settings → Permalinks — anything except Plain). With Plain permalinks the REST endpoints return 404.
HTTPS on the storefront. The consumer secret never travels over plain HTTP; connect rejects http:// URLs.
The REST API must be reachable over the public internet (no maintenance-mode plugin or IP allow-list blocking /wp-json/).

4. Connect with Paste API key

In Settings → Integrations, click Paste API key on the WooCommerce card.
The connect dialog asks for three values:
- Store URL — the full storefront origin, e.g. https://store.example.com. Must be HTTPS.
- Consumer key — the ck_ value from Step 3.
- Consumer secret — the cs_ value from Step 3 (entered into a masked password field).
Expand Where do I find these? inside the dialog if you need the WP admin path again — it restates the exact WooCommerce → Settings → Advanced → REST API steps.
Click Connect. Orbit validates the pair against your store by calling GET /wp-json/wc/v3/orders?per_page=1, and only stores the key pair when that probe returns success. Both halves are encrypted before they’re written.

A successful connect flips the WooCommerce card to Connected. Re-running connect with a new key pair replaces the stored one — use it to rotate keys.

5. What gets ingested after connect

Customers → upserted into your Orbit contact list (email, phone, name) on the scheduled sync, so segments and campaigns can address them.
Orders → normalized event records. Order created / updated events are ingested into the CDP event stream as woocommerce.order, which is what flows and audiences trigger on.
Products → kept current for catalog-level personalization in messages.

The sync runs on Orbit’s schedule — no webhooks to configure in WooCommerce, no plugins to install.

6. Using the events: flows on SMS/WhatsApp

Every ingested order event is a flow trigger you can wire in Flows:

Post-purchase — trigger on woocommerce.order (created / updated), wait a fixed window, then send a thank-you or review request on SMS or WhatsApp. Because customer sync and order events share the same contact record, the message addresses the right person.
Abandoned cart — trigger on the cart/checkout event, delay to give the buyer a chance to finish, check the order hasn’t closed, then send the recovery link over SMS or WhatsApp.

For the trigger, condition, and channel-node shapes see Flows recipes — substitute the WooCommerce event as the trigger. To rename or reshape event properties per destination (e.g. a downstream webhook subscription), use Event field mappings — note the in-dashboard mappings page currently redirects to the Integrations hub, and the capability runs at the API level today.

7. Consumed event envelopes

When you wire a Business Event trigger or subscribe a CDP destination, you code against the event’s normalized record, not the operator’s wording above. These are the envelopes a developer actually consumes after connect — connect stays console-only; the shapes below are the downstream contract. woocommerce.order event — as ingested into the CDP event stream. Order created/updated rows arrive as track events with event_name: "woocommerce.order"; the properties are the store’s normalized order record, so segment predicates and message personalisation address these exact keys:

{
  "type": "track",
  "event_name": "woocommerce.order",
  "contact_id": "contact_02a3f1c9d4e5",
  "properties": {
    "id": "1042",
    "number": "1042",
    "status": "processing",
    "currency": "USD",
    "customer_id": "128",
    "email": "anna@customer.example",
    "phone": "+15551234567",
    "total": "79.98",
    "total_tax": "6.40",
    "payment_method": "cod",
    "payment_method_title": "Cash on delivery",
    "line_items": [
      {
        "id": "881",
        "product_id": "51",
        "variation_id": null,
        "name": "Ceramic pour-over dripper",
        "quantity": 2,
        "sku": "COFFEE-DRIP-01",
        "price": "39.99",
        "subtotal": "79.98",
        "total": "79.98"
      }
    ],
    "date_created": "2026-09-26T11:02:41",
    "date_modified": "2026-09-26T11:03:12",
    "date_completed": null
  }
}

Field notes:

Money fields (total, total_tax, each line item’s price/subtotal/total) are decimal strings in the store’s currency — do a numeric conversion before a threshold predicate (e.g. “total > 100”).
customer_id is the store’s customer id when the buyer has one; guest checkouts carry null and the order binds to the contact by email/phone instead. date_completed stays null until the order is marked complete.
Re-polls of the same order version collapse on a stable idempotency key; a modified order emits a fresh event version.

The same event on a CDP subscription (cdp.event.ingested) webhook. If you subscribe a URL destination at webhooks with the event filter on woocommerce.order, the egress envelope is the standard webhooks shape — the normalized order lands verbatim under data.properties:

{
  "id": "evt_77b2c4d8e1a5",
  "type": "cdp.event.ingested",
  "created_at": "2026-09-26T11:03:31.118Z",
  "data": {
    "event_name": "woocommerce.order",
    "contact_id": "contact_02a3f1c9d4e5",
    "properties": {
      "id": "1042",
      "number": "1042",
      "status": "processing",
      "currency": "USD",
      "customer_id": "128",
      "email": "anna@customer.example",
      "phone": "+15551234567",
      "total": "79.98",
      "total_tax": "6.40",
      "payment_method": "cod",
      "payment_method_title": "Cash on delivery",
      "line_items": [],
      "date_created": "2026-09-26T11:02:41",
      "date_modified": "2026-09-26T11:03:12",
      "date_completed": null
    }
  }
}

(line_items is truncated above to show the envelope — in production it carries the full array from the order sample.) Verify the HMAC signature per Webhook Security before consuming. Cart-recovery envelope. The abandoned-cart path in Section 6 is driven by the same mechanism with a recovery step attached. A storefront-side signal (your own POST /cdp/track, and abandoned-checkout companions when your store registers them) lands as its own track event and enters the recovery drip the same way — for example a woocommerce.cart_abandoned event carrying the cart:

{
  "type": "track",
  "event_name": "woocommerce.cart_abandoned",
  "contact_id": "contact_02a3f1c9d4e5",
  "properties": {
    "email": "anna@customer.example",
    "phone": "+15551234567",
    "recovery_url": "https://store.example.com/cart?recover=ck_...",
    "cart_total": "79.98",
    "line_items": [ { "product_id": "51", "name": "Ceramic pour-over dripper", "quantity": 2 } ]
  }
}

The flow waits its delay, checks the matching woocommerce.order event hasn’t landed for the same contact (order closed), then sends the recovery_url over SMS or WhatsApp. Triggering a flow on the event (curl). A Business Event flow declares the WooCommerce event as its trigger and gates on a property (status) before sending — the filter runs against the same property keys shown above:

curl -X POST https://api.orbit.devotel.io/api/v1/flows \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "WooCommerce post-purchase thank-you",
    "trigger_type": "event",
    "definition": {
      "trigger": { "type": "event", "event": "woocommerce.order" },
      "nodes": [
        {
          "id": "paid_only",
          "type": "condition",
          "data": { "field": "status", "operator": "equals", "value": "processing" }
        },
        { "id": "wait_2h", "type": "delay", "data": { "amount": 2, "unit": "hours" } },
        {
          "id": "thank_you_sms",
          "type": "sendSms",
          "data": {
            "to": "{{phone}}",
            "body": "Thanks for order {{number}} — we will text tracking when it ships."
          }
        }
      ],
      "edges": [
        { "source": "paid_only", "sourceHandle": "yes", "target": "wait_2h" },
        { "source": "wait_2h", "target": "thank_you_sms" }
      ]
    }
  }'

trigger_type: "event" plus definition.trigger.event names the exact string above; an imprecise match (e.g. woocommerce_order) simply never fires.

8. Health monitoring

The WooCommerce card badge in the Integrations catalog shows Connected (or Errored if the stored credential stops validating).
Open the card’s drawer to inspect sync health — last sync time and any error the scheduled sync surfaced.
If the card shows Errored, the usual cause is a rotated or revoked key in WordPress. Upload a fresh pair via Connect with Paste API key; re-running connect replaces the stored credential and clears the error state.

9. Test and rollback

Test before building flows — the cleanest end-to-end check is a dry-run checkout:

Add a product to cart on your store and abandon it at checkout (or place a low-value test order).
Watch the contact and event records land in Orbit — the cart/order event should appear on the synced customer.
Build your flow trigger against that verified event.

Rollback — to disconnect:

In the Integrations catalog, open the WooCommerce card and use Revoke (the disconnect action on the card/drawer).
This deletes the stored credential from Orbit, flips the card back to Available, and stops syncs.
Revoke does not touch WordPress. The consumer key you generated still exists in WP admin and is still valid for anything else using it — delete it yourself under WooCommerce → Settings → Advanced → REST API if you want it fully revoked.

10. Limits and error taxonomy

Quirks specific to the REST-key integration:

HTTPS required — http:// store URLs are rejected at connect; the consumer secret never travels unencrypted.
Woo ≥ 3.6 — the probe hits the v3 API namespace; older Woo versions won’t answer.
Pretty permalinks required — Plain permalinks make /wp-json/wc/v3/* return 404; connect fails.
Public reachability — store URLs that resolve to private/internal addresses (loopback, RFC-1918, cloud metadata endpoints) are rejected for safety, so a VPC-internal staging store can’t be connected directly.
Read/Write permission — a Read-only key connects but limits what future features can do; generate new keys with Read/Write.

Connect error codes and what they mean:

Error code	Cause	Fix
`WOO_INVALID_URL` / `WOO_HTTPS_REQUIRED`	Malformed URL or plain HTTP	Re-enter the full `https://` storefront URL
`WOO_UNREACHABLE`	Network/timeout reaching the store	Confirm the site is up and the REST API is enabled; check for maintenance-mode or IP allow-lists
`WOO_AUTH_FAILED`	WP rejected the key pair	Regenerate the key in WooCommerce → Settings → Advanced → REST API and confirm Read/Write
`WOO_REST_NOT_FOUND`	404 from the v3 endpoint	WooCommerce not installed/activated, or permalinks set to Plain
`WOO_VALIDATION_FAILED`	Store returned a non-2xx status	Check the store URL and key permissions
`WOO_INVALID_STORE_URL`	URL points to a private/internal/host-blocked address	Use the publicly reachable store address

11. If you’re coming from the Shopify guide

Shopify connects with OAuth (consent redirect, automatic webhook registration) — the dashboard-driven alternative for managed stores. Pick WooCommerce’s key-pair flow when the store is self-hosted WordPress and you want full control over the credential’s lifecycle in WP admin. Both ingest into the same contact + event model, so the flow patterns transfer between them — see Connect Shopify for the OAuth side.

Connect Shopify — the OAuth alternative for managed stores.
Flows recipes — trigger/condition shapes for cart-recovery and post-purchase drips.
Event field mappings — reshape event properties per downstream destination.

WhatsApp

Developer console

Contact center

Guides

Messaging Controls

Audience & Support Tools

Connect WooCommerce: REST key pair, order events, and cart recovery

Connect WooCommerce end to end

1. Where to find it

2. What does it do?

3. Generate the consumer key pair in WordPress

4. Connect with Paste API key

5. What gets ingested after connect

6. Using the events: flows on SMS/WhatsApp

7. Consumed event envelopes

8. Health monitoring

9. Test and rollback

10. Limits and error taxonomy

11. If you’re coming from the Shopify guide

​Connect WooCommerce end to end

​1. Where to find it

​2. What does it do?

​3. Generate the consumer key pair in WordPress

​4. Connect with Paste API key

​5. What gets ingested after connect

​6. Using the events: flows on SMS/WhatsApp

​7. Consumed event envelopes

​8. Health monitoring

​9. Test and rollback

​10. Limits and error taxonomy

​11. If you’re coming from the Shopify guide

​Related reading

Connect WooCommerce end to end

1. Where to find it

2. What does it do?

3. Generate the consumer key pair in WordPress

4. Connect with Paste API key

5. What gets ingested after connect

6. Using the events: flows on SMS/WhatsApp

7. Consumed event envelopes

8. Health monitoring

9. Test and rollback

10. Limits and error taxonomy

11. If you’re coming from the Shopify guide

Related reading