WooCommerce

Connect your self-hosted WooCommerce store so your AI agent can answer product questions, look up a shopper’s order, recommend in-stock items, and send order-status updates — all from your synced catalog and order data.

WooCommerce works on every plan, including the free trial. There is nothing to buy or upgrade to before you connect a store.

What you get

Catalog Q&A — answers from your real products, variants, prices, and current availability
Order lookup (WISMO) — shoppers check “where is my order?” with their order number plus the email or phone on the order
Recommendations — suggestions limited to products that are actually in stock
Order-status updates — shipping updates in the same chat, for shoppers who opt in
Current inventory — prices and stock from your synced catalog, kept up to date by webhooks
Checkout handoff — send a ready-to-buy shopper to your own WooCommerce checkout

Prerequisites

A self-hosted WooCommerce store you administer
Your store URL (for example, https://your-store.com)
An Owner or Admin account on your Cuneiform Chat workspace — connecting a store is an admin action
At least one agent, or room in your plan to create one (see Your store agent)

You do not need to install a plugin or write any code.

Your store URL, however you type it

Type the URL any way you like — we normalize it. The scheme, a leading www., a trailing slash, and the capitalization of the host are all ignored. A subdirectory install (example.com/shop) and a non-standard port are both preserved and both supported.

Connecting

There are two ways in, on the same card. Use the guided flow unless something blocks it.

Path A — the guided authorization (recommended)

Go to Commerce → WooCommerce.
Enter your store URL and click Connect.
Your browser goes to your own store’s WooCommerce approval screen. Approve it.
WooCommerce sends the keys back and you land on Commerce.

That’s it. The guided flow does three things the manual path does not: it requests the right permission for you, it registers the webhooks that keep your data fresh in real time, and it kicks off the initial catalog import.

The approval screen will say read/write, and that is intentional. WooCommerce will not let anything register webhooks with a read-only key — it rejects the request outright. Without webhooks there are no real-time catalog, stock, or order updates. The integration still never writes to your catalog, your inventory, or your existing orders; the write permission exists so we can register webhooks and, if you use in-chat checkout, create the pending order a shopper is about to pay for.

Path B — pasting API keys manually

If your store sits behind a firewall that blocks the redirect, expand Enter API keys manually and paste a consumer key and secret generated in WooCommerce → Settings → Advanced → REST API.

Generate them with Read/Write permission, and select Read/Write on our form too. A read-only key leaves you permanently without webhooks — see below.

We health-check the store before saving. A hard failure blocks the connection; a soft warning (a slow or partially-reachable store) connects anyway so you can fix it afterwards.

After a manual connect

The manual key path skips two things the guided flow does at connect: it does not register webhooks, and it does not start the initial catalog import. They recover on different schedules — and one of them only recovers if your key carries the right permission. Read both halves below.

Your catalog — press “Re-sync now”

Nothing is imported at connect. A background job reconciles catalogs daily, but that daily pass only fetches products changed since its own last run — and a store that never imported has no backlog to fetch, only new edits. The full import arrives with the weekly sweep, which can be up to seven days away.

Don’t wait for it. Open Commerce → WooCommerce → Catalog & Data and click Re-sync now. That runs the same import the guided flow would have run at connect, and it finishes in minutes.

Your webhooks — only if your key is Read/Write

Webhooks are not registered at connect either, but this one is repaired automatically on one condition. An hourly job re-attempts webhook registration for every connected store, so:

A Read/Write store recovers on its own, usually within the hour. You don’t have to do anything.
A read-only store never recovers. WooCommerce rejects every registration attempt from a read-only key. The job retries every hour and is refused every hour, indefinitely.

You can see this rather than having to infer it: Commerce → WooCommerce → Connection has a Webhook health panel, which will read “Subscriptions drifted” with “No events received yet.” The other symptom is behavioral — catalog, stock, and order changes only ever show up on the next scheduled sync instead of arriving as they happen.

The permission is what you told us it was

We record the permission you select; we don’t test the key to find out. If you paste a Read/Write key but leave the permission field blank, we record it as read-only — and both webhooks and multi-line checkout quietly degrade. If you select Read/Write but paste a read-only key, webhooks are rejected by your store every time.

If real-time updates or multi-line checkout are missing, this single field is the first thing to check. The fix is to Reconnect through the guided flow, which always requests the right permission.

What the integration does and doesn’t do

The integration is read-only where your store’s data is concerned. It never edits or deletes a product, never adjusts stock, never modifies or cancels an existing order, and never captures a payment. Payment always happens on your own WooCommerce checkout.

The one thing a Read/Write connection does write is a pending order, and only when a shopper checks out from inside a chat: instead of handing off one product at a time, the whole cart becomes a pending order in your store and the shopper is sent to pay for it. Nothing is charged, nothing is fulfilled, and the order is attributed to the conversation it came from so you can see where the sale started. See Checkout.

A read-only connection can’t create that pending order, so it hands off one line at a time instead. That is the practical difference between the two permissions, and the reason the guided flow always asks for Read/Write.

Features

One store, one store agent

You connect one WooCommerce store per workspace — and you can have a Shopify store connected at the same time (see Commerce).

At connect time, one agent becomes your store agent — chosen for you rather than by you. If you previously connected this same store, its old store agent is reclaimed, tuning and version history intact; otherwise a fresh one is created. That agent carries the WooCommerce tools; your other agents are unaffected. There is no per-agent switch to hunt for — the agent’s own page shows a read-only panel saying it’s managed by your store.

Older versions of this page told you to enable commerce for more agents under Commerce → Settings. That page no longer exists, and the per-agent switch went with it. Commerce is wired to the store agent chosen at connect.

Verified order lookup

Shoppers see order details only after providing the exact order number and the email or phone on the order. A wrong contact and a non-existent order return the same “couldn’t find it” answer with no details — anti-enumeration hardening that protects your customers. See Orders.

Current catalog and inventory

Prices and stock come from your synced catalog, so recommendations stay limited to what’s actually available. WooCommerce sends stock changes along with product updates rather than as separate inventory events, so a stock-only change lands with the next product update or the next sync. See Catalog & Knowledge.

Opt-in order-status updates

After a shopper verifies their order in chat, they can opt in to shipping updates on a supported channel. The shopper’s opt-in is the only gate — the update types are on by default on the WooCommerce connection, so there’s nothing to switch on first. See Orders.

Reconnect

Unlike Shopify, WooCommerce has a Reconnect button. Use it when you rotate or revoke your store’s API keys, or when you connected manually with the wrong permission and want to switch to the guided flow. It re-runs the approval on your store and replaces the stored keys in place.

What syncs from your store

WooCommerce has four built-in product types. All four sync, but they don’t all behave the same way in a conversation.

Type	What the agent can do with it
`simple`	Everything. Catalogued, priced, and addable to a cart — buyable while your store marks it purchasable and in stock.
`variable`	Everything. Every variation syncs with its own price and stock. The product’s price comes from its variations, and it counts as in stock while any variation is. What goes into a cart is the variation the shopper chose, not the parent product.
`grouped`	Catalogued and answerable. A grouped product has no price of its own, and its stock is the roll-up WooCommerce itself derives from its child products. The child products are the things actually sold.
`external`	Catalogued and answerable, never cart-buyable. The agent can answer questions about an affiliate product like any other — name, description, price — but it never hands the shopper your external link or your button text: those sync with the product and are stored, and nothing shows them in a conversation. An affiliate product is also always treated as unavailable for sale, so it can never be added to a cart. Shoppers reach it the way they always have, from your own storefront.

Anything else is treated as `simple`

Product types added by an extension are not modelled. Subscriptions, bookings, bundles, composite products — anything that isn’t one of the four above — falls through to the simple handling.

It is not rejected. It syncs, it’s catalogued, and the agent can answer about it and recommend it, carrying whatever price and stock the parent product row happens to hold. For these types that price is usually wrong, and often missing entirely.

If you rely on an extension product type, keep those products out of the synced catalog rather than letting the agent quote them, and tell us what you’re running — support@cuneiform.chat. Recommending a subscription at its parent-row price is worse than not mentioning it at all.

Prices and your store’s currency

Prices sync as the amounts your store holds, in your store’s own currency. We read that currency from your WooCommerce settings — never from the shopper — and shoppers see it as the three-letter code beside the amount: USD 19.99, EUR 19.99, BDT 1900.

A code rather than a symbol is deliberate. $ alone is the dollar of four different countries, and a confidently wrong symbol on a price is worse than an unmistakable code.

The currency is re-read on the nightly catalog reconcile, so if you change it in WooCommerce the quoted code follows within a day. Until that first nightly pass, a store connected before we started reading the setting quotes plain amounts with no code — the price is still correct, it just isn’t labelled yet.

A multicurrency plugin is not reflected. Extensions that show each shopper a different currency by geography do that inside your storefront. We store one currency per store — the base currency your settings name — so the agent quotes that same one to every shopper, wherever they are.

The amounts are still right in the currency they’re labelled with; they simply aren’t the converted figures the same shopper would see on your site. Checkout is unaffected: the shopper finishes on your own storefront, where your plugin does whatever it normally does.

Shipment-tracking plugins

Carrier and tracking numbers are read from one place: the record written by the official WooCommerce Shipment Tracking plugin, which Advanced Shipment Tracking (AST) writes to as well. Those two come through. Any other tracking plugin keeps its data somewhere else and is not read at all, so an order looks untracked even though your store shows a tracking number. See Orders.

Translated stores

Nothing in the sync is language-aware. If you run WPML or Polylang, each translated version of a product syncs as an ordinary separate product rather than as a translation of one, and the agent can surface any of them.

Security

No writes to your catalog, stock, or existing orders — the integration reads products, inventory, and orders, and never modifies them
Keys are encrypted at rest — your consumer key and secret are never stored in plain text
Tenant isolation — your catalog and orders are scoped to your workspace and never visible to anyone else’s
Verified order lookup — order details require the exact order number plus a matching email or phone
Opt-in notifications — shipping updates require an explicit per-shopper opt-in in chat
Secure checkout — payment completes on your own WooCommerce checkout; no card data passes through the agent

Troubleshooting

Connecting hangs or fails

The guided flow needs your browser to reach your store’s approval screen and your store to reach us with the keys. If it stalls, it’s usually a network or firewall problem, not your credentials. Firewalled store? Use the manual key path — and then read After a manual connect, because it leaves two things undone.

The catalog is empty right after connecting

If you connected manually, this is expected — nothing was imported. Click Re-sync now on the Catalog & Data tab.

If you used the guided flow, the first import backfills the whole catalog and can take a few minutes on a large store.

Product or stock changes take hours to show up

Your webhooks aren’t registered. Almost always this means the store was connected manually with a read-only key. Check the permission recorded on the connection, then Reconnect through the guided flow.

”This store is already connected to another account”

The same store is connected to a different workspace. Disconnect it there first, then connect it here. We refuse the takeover rather than silently moving the store.

The agent won’t answer product questions

Check you’re talking to the store agent — the one chosen at connect. Its agent page shows a read-only “managed by your store” panel. Other agents don’t carry the commerce tools.

Order lookup can’t find an order

The lookup is deliberately strict: it returns details only when the shopper gives the exact order number and an email or phone that matches the order.

No order-status updates are sent

The shopper has to opt in, in chat, on a supported channel. If they did, check the notification toggles on the WooCommerce connection — they’re on by default, but if the matching update type was switched off at some point, the opt-in alone won’t produce a message.

Disconnecting

Disconnect from Commerce → WooCommerce → Disconnect. Disconnecting:

Removes the stored connection and credentials, and the synced catalog
Clears the product knowledge built from that catalog
Removes the webhooks it registered on your store
Resets the store agent’s commerce grant, reverts its commerce persona if you never edited it, and archives the agent itself — reconnecting the same store reclaims it with its tuning and version history intact
Permanently deletes any Storefront scoped to that store, along with its analytics history. Storefronts you built by hand are untouched
Archives the commerce Agent Forms that came with the store
Deletes the AI quiz suggestions outright, so a future reconnect starts from a clean slate

If you still have a Shopify store connected, only the workspace-wide steps — archiving commerce Agent Forms and deleting quiz suggestions — are skipped. The WooCommerce store’s own catalog, product knowledge, Storefronts, analytics and store agent are always torn down.

FAQ

Do I need to be on a particular plan to connect WooCommerce?

No. WooCommerce works on every plan, including the free trial — catalog Q&A, order lookup, recommendations, and order-status updates all included.

Do I have to install a plugin?

No plugin. The guided flow is a one-time approval on your own store. You only paste API keys if your firewall blocks the redirect.

Why does the approval screen ask for write access?

Because WooCommerce refuses to register webhooks for a read-only key, and without webhooks nothing updates in real time. The integration still never changes your catalog, your stock, or your existing orders. What it writes is limited to the webhooks themselves, and one pending order for a shopper checking out from a chat — see Checkout.

Can I connect with a read-only key anyway?

You can, and catalog Q&A, order lookup, recommendations, and notifications all work. What you give up is real-time updates (webhooks can never register) and multi-line in-chat checkout. If you later want them, Reconnect through the guided flow.

Can all of my agents use WooCommerce, or just one?

One — the store agent chosen at connect time. That agent gets the WooCommerce tools; the others are unaffected.

Does the agent ever change my store?

It never edits products, never adjusts inventory, never modifies or cancels existing orders, and never takes payment. On a Read/Write connection it can create one thing: a pending order for a shopper who is checking out from a chat, which they then pay for on your own checkout.

Commerce overview — what connecting a store gives you
Shopify — the other supported platform
Catalog & Knowledge — how the catalog syncs and stays fresh
Orders — order lookup and status updates
Checkout — including the permission-dependent difference