How to Connect WooCommerce

The WooCommerce integration lets your AI search published products and, after the customer verifies the order email, look up that customer's WooCommerce orders. You can also enable protected write actions: shipping-address changes, unpaid-order cancellation, and remaining-payment refunds.

Availability: BUSINESS, ENTERPRISE, and active 14-day trials.

Connecting WooCommerce does not turn on write actions. Select each tool, then enable its action rule. WooCommerce has no customer-directory tool and no return-request tool.

Overview

After a correct setup, customers can:

Ask catalog questions without verifying an email
Verify the email on the order, then look up matching orders
Confirm a shipping-address change, cancellation, or refund in a secure form when you have enabled that tool and its rule

Voxe uses the WooCommerce REST API. It only sees order and shipment evidence that WooCommerce returns on the order. Warehouse, 3PL, or carrier activity that is not stored on the order is not visible to Voxe.

Before you connect

Use a BUSINESS or ENTERPRISE plan, or an active 14-day trial
Have an HTTPS WooCommerce store URL (the store homepage, such as https://store.example.com)
Create REST API keys in WooCommerce → Settings → Advanced → REST API
Choose Read or Read/Write on the key to match the tools you will enable (see Required permissions)
Know which support chat / workflow should use this store
Decide which tools to enable. Write tools also need action rules

Note: Each workflow can have its own WooCommerce connection. Do not reuse one store connection across unrelated brands unless that is intentional.

Required permissions

A WooCommerce tool runs only when it is enabled in Voxe and the Consumer Key has the matching REST API permission. Selecting a tool in Voxe does not change the WooCommerce key. Creating a key in WooCommerce does not enable the tool in Voxe.

WooCommerce REST API keys offer Read, Write, or Read/Write. Voxe always looks up orders before it changes them, so a Write-only key is not enough for write tools.

Use this mapping when you generate the Consumer Key and Consumer Secret:

Search WooCommerce products — GET /wp-json/wc/v3/products and GET /wp-json/wc/v3/products/{id}/variations — Read
Look up verified WooCommerce order — GET /wp-json/wc/v3/orders and GET /wp-json/wc/v3/orders/{id}; refund records may also be read with GET /wp-json/wc/v3/orders/{id}/refunds — Read
Change verified WooCommerce shipping address — the order GETs above, then PUT /wp-json/wc/v3/orders/{id} (shipping fields only) — Read/Write
Cancel verified WooCommerce order — the order GETs above, then PUT /wp-json/wc/v3/orders/{id} with status cancelled — Read/Write
Refund verified WooCommerce order — the order and refund GETs above, then POST /wp-json/wc/v3/orders/{id}/refunds — Read/Write

Choose the key permission for the tools you will enable:

Catalog only (product search): Read
Read-only store access (product search and/or order lookup): Read
Any protected action (address change, cancellation, or refund), with or without the read tools: Read/Write

If you start with a Read key and later enable a write tool, create a new Read/Write key in WooCommerce, then replace the Voxe connection by submitting Store URL + Consumer Key + Consumer Secret together. Do not keep a Read key after enabling writes.

If the key is missing permission or is later revoked: Voxe does not complete the lookup or write. Chat should treat this as a store-connection problem for your team — not a failed customer verification — and should not retry the same request. Recreate a key with the permission above and replace all three credential fields together.

Connecting the integration

In WooCommerce, create a REST API key with the permission above. Copy the Consumer Key and Consumer Secret.
In Voxe, go to Dashboard → Integrations → Add Integration → Business Data Integrations
Select the workflow for this store
Choose WooCommerce
Enter:
WooCommerce URL — https://store.example.com (HTTPS). Do not put the key or secret in the URL.
Consumer Key
Consumer Secret
Select the tools to attach (see Available tools)
If you selected a write tool, open WooCommerce action automation, turn the matching rule on, and set its limits
Save, then enable the integration under Your Integrations

Changing an existing connection

Leave every credential field blank to keep the current store connection.

To replace the connection, enter the Store URL, Consumer Key, and Consumer Secret together in the same save. You cannot change only the URL. Partial credential updates are rejected so the store and keys cannot drift apart.

After you save (test the connection)

There is no separate WooCommerce "Test Connection" button. After the integration is enabled under Your Integrations:

Open that support chat
Ask about a published product you know exists (no verification should be required)
If order lookup is enabled, ask about a known test order so the verification link appears, then complete verification
If a write tool is enabled, use only a safe test order. Do not test refunds or cancellations on live customer orders

If product search fails immediately, check the store URL and that the key is Read or Read/Write. If lookups work but a write action goes to support, the key is likely still Read-only or was revoked.

Available tools

You choose tools in the integration form. Unselected tools are not available to the AI.

Read-only

Search WooCommerce products — no customer verification
Look up verified WooCommerce order — email verification required

Protected write actions (email verification and secure confirmation)

Change verified WooCommerce shipping address
Cancel verified WooCommerce order
Refund verified WooCommerce order

Unsupported

WooCommerce customer-directory or account lookup
WooCommerce return request or return status
Partial item refunds, restocking, or cancellation-plus-refund as one action
Changing a saved customer account address
Editing carrier labels or telling a warehouse to stop picking

Tool-by-tool behavior

Search WooCommerce products

What it does: Searches published products (not hidden catalog items). Returns title, description, URL, SKU, prices, stock status, attributes, and variation counts, five products per page.
Typical use: "Do you sell X?", "What colors does this come in?", "Is this in stock?"
Verification / confirmation: Neither
Woo permission: Read
Voxe settings: Enable Search WooCommerce products
Limits: Search text is bounded; extra variations may exist beyond what is listed (variantsHaveMore). Checkout still confirms price, tax, shipping, and availability.
Does not: Create products, change stock, or read draft/private products

Look up verified WooCommerce order

What it does: After email verification, finds orders whose billing email matches the verified address. Can return order number, status, totals, shipping address when present, line items (up to 20), and refund records.
Typical use: "Where is my order?", "What's on order 1234?"
Verification / confirmation: Verification required. No secure confirmation (read-only).
Woo permission: Read
Filters: Optional order number or order date (YYYY-MM-DD). Do not require both. Identity is always the verified email, not chat profile data.
Multiple orders: If more than one owned order matches, the customer must provide a number or date. Voxe does not pick the newest order or list every order in full.
Search limits: Lookup pages WooCommerce orders (50 per page, up to three pages). If that bound is not enough, the AI asks for a number or date instead of claiming there are no orders.
Does not: Look up other customers, change the order, or treat refund records as proof that money has arrived in a bank account. Tracking appears only when WooCommerce core order data includes it.

Change verified WooCommerce shipping address

What it does: After verification, eligibility, and confirmation, updates shipping fields on that WooCommerce order.
Typical use: Customer needs to correct a delivery address before the order is completed.
Verification / confirmation: Both
Woo permission: Read/Write
Settings: Action rule Address changes must be enabled. Configure Maximum order age (hours) and Eligible order statuses (pending, processing, on-hold only).
Safety Voxe always applies: Blocks cancelled, trash, failed, and completed orders; blocks when a completed date is present; blocks when shipping-line or order meta looks like tracking/shipment/fulfillment evidence. Status alone is not enough. processing does not mean the warehouse is idle.
Changes: Order shipping address in WooCommerce
Does not change: Billing address, saved account address, carrier labels, or warehouse instructions. Voxe cannot reroute a shipment that has already started.
Human review: Fulfillment evidence, ineligible status, missing shipping lines, or an order that changed while the customer was confirming

Cancel verified WooCommerce order

What it does: Sets the WooCommerce order status to cancelled after confirmation. This is not a refund.
Typical use: Customer wants to cancel an unpaid order (pending or failed) that has not been paid or shipped.
Verification / confirmation: Both
Woo permission: Read/Write
Settings: Action rule Order cancellation must be enabled. Eligible statuses you can select: pending and failed only.
Safety Voxe always applies: Paid, captured, processing, on-hold, completed, refunded, or fulfilled orders are never cancelled automatically. A payment date, transaction reference, or refund record blocks automation. Merchant settings cannot override those payment and fulfillment restrictions.
Changes: Order status to cancelled
Does not change: Payments, inventory restock, warehouse work, shipments, or carrier labels
Human review: Any paid or ambiguous payment state, fulfillment evidence, or a readback that does not show cancelled

Refund verified WooCommerce order

What it does: Creates a WooCommerce refund for the remaining paid amount through the WooCommerce payment API (api_refund). The amount comes from current WooCommerce totals and existing refund records, not from chat.
Typical use: Customer wants the remaining eligible payment refunded, within your maximum refund and currency.
Verification / confirmation: Both
Woo permission: Read/Write
Settings: Action rule Full remaining refund must be enabled. Set Maximum refund, Currency, Maximum order age, and eligible statuses (processing, completed, on-hold). A maximum of 0 blocks refunds until you set a real limit.
Safety Voxe always applies: Unpaid, pending, and failed orders are not refunded automatically. Offline methods cod, bacs, and cheque are never refunded automatically. Restock is off. The order is not cancelled. A return is not created. Inconsistent refund totals block automation.
Changes: A refund record and an attempted payment reversal through WooCommerce
Does not change: Inventory, order cancellation, returns, or bank/card settlement timing. A refund record is not proof that funds have arrived.
Human review: Unsupported gateways, totals Voxe cannot reconcile, or WooCommerce creating a refund record without confirming payment reversal

Settings

Write tools appear under WooCommerce action automation only after you select the matching tool. Defaults start off. There is no hidden extra age cap: the hours you save are the hours enforced (1 to 2160 hours). Default age when you first enable a rule in the form is 72 hours.

For each write action you can set:

Enabled — whether automation may run
Maximum order age (hours) — older orders are not automated
Eligible order statuses — chosen from the allowlist for that action; you can restrict further, not expand beyond it
Maximum refund and Currency — refunds only; the remaining WooCommerce amount must be within this limit and currency

Address-change status allowlist: pending, processing, on-hold. Completed dates or tracking/shipment-style evidence still block automation.

Cancellation status allowlist: pending, failed. Paid or refund-required orders are never auto-cancelled.

Refund status allowlist: processing, completed, on-hold. Unpaid orders and unsupported gateways still block automation.

Merchant settings cannot override a payment or fulfillment restriction that makes an action unsafe.

Customer verification

Private WooCommerce tools require the customer to prove the email on the order (billing email). The AI cannot skip this, and chat profile email is not identity.

When it is required: order lookup, address change, cancellation, and refund.

What the customer sees:

The AI uses the order tool. Voxe posts a verification link in the same chat.
The customer opens the form, enters the order email, and receives a six-digit code at that address.
They enter the code only in that form, never in chat.
The link and code expire in 10 minutes. After a successful verification, that conversation can reuse the verified email for about 10 minutes for further lookups and actions in the same flow.
Successful verification resumes the chat automatically. Customers should not paste codes into the conversation.

Multiple orders: Voxe asks for an order number or date. After they reply, the same tool continues with that filter. Verification is not restarted just because they supplied a number.

When they must verify again:

The 10-minute verified window ended
They need to use a different email (wait for a new verification link; a recent link is not re-sent immediately)
The conversation is no longer the same active support thread (for example after a handoff that starts a new handling cycle)

Do not share codes in chat. Codes in chat are not used as proof.

If no order matches the verified email, the customer can try a different email after a new verification. Repeated code requests can be rate-limited; wait before resending (about a minute) or contact your team if the limit is reached.

Protected actions

Enabled write actions follow:

request → verification if needed → identify the order → check eligibility → secure confirmation → fresh recheck → perform the operation → confirm the result

A chat "yes" is not confirmation. The customer uses the secure form linked from chat (expires in 10 minutes).
For address changes, the form collects the new address. Do not collect a new address in chat.
After confirm, Voxe reads the order again and repeats eligibility checks. The order may have been paid, completed, or shipped while they were confirming.
If the order or your rules changed, no write is sent. Ask for a fresh confirmation; email verification can still be valid.
Voxe does not retry failed, unknown, or blocked outcomes. Those need a person.
Only one unresolved change should run on an order at a time.

Cancellation readback must show status cancelled. Address readback must match the confirmed address. Refund readback must show a new refund for the confirmed remaining amount.

Shipping-address changes

Automatic address changes depend on:

The address-change tool and rule being enabled
The order status you allowed (pending, processing, and/or on-hold)
Order age
No completed date / completed status
No tracking or shipment-style evidence on shipping lines or order meta that Voxe inspects

WooCommerce core does not provide the same universal fulfillment model as Shopify. External warehouse, 3PL, or carrier activity may not appear on the order Voxe can read. Voxe will not change an address when the evidence it *can* see shows fulfillment has progressed, but it cannot guarantee that a warehouse has not started picking.

If you need a stricter bar, allow only pending (and optionally on-hold) rather than processing.

Voxe does not edit carrier labels and does not change the customer's saved account address.

Refunds, cancellations, and returns

Treat these as separate operations:

Cancel — unpaid eligible orders only; no payment refund
Refund — remaining paid amount through the payment API; no cancel, restock, or return
Returns — not available as a WooCommerce tool. Handle returns in your Help Desk or WooCommerce admin

Existing partial refunds reduce the remaining refundable amount. Nothing remaining to refund is reported without creating another refund.

Human escalation

The AI should hand off when automation cannot complete safely, including:

The customer asks for a person
Verification or confirmation expired
The order is no longer eligible (paid, fulfilled, wrong status, over your refund limit)
Fulfillment appears to have started
The provider result is failed, unknown, or unconfirmed
Payment method cannot be refunded through WooCommerce automatically

Do not instruct the AI to retry those outcomes.

Hide Branding

Secure verification and confirmation pages follow the Hide Branding toggle on Dashboard → Integrations → Add Integration → Chat Widget Script for that support chat. That is the same setting as the website chat widget.

Off: pages show VoxeDesk branding
On: pages use the merchant name Voxe already has for that support chat (or the store hostname if no business name is set)

See How to Set Up the Chat Widget. This is not controlled from a separate branding dashboard page.

Limitations

These are intentional safeguards, not missing "unlimited store admin" features:

Only selected tools run. Disabled action rules do not run even if the tool is selected. The WooCommerce key must also have Read or Read/Write for those tools.
Identity is verified order email, not a WooCommerce customer account browser.
Lookups are bounded (product pages of five; order search pages are capped). Large catalogs and high order volume need a number or date.
Voxe cannot see fulfillment systems that WooCommerce does not expose on the order.
Insufficient REST API permission stops reads or writes.
Protected mutations are blocked when current WooCommerce state fails the safety checks, even after the customer confirmed.
Unconfirmed write results are sent to your team; they are not retried automatically.

Troubleshooting

Connection / credentials: Confirm HTTPS URL, key, and secret. To change a connected store, submit URL + key + secret together. Enable the integration after saving.
Insufficient permissions: Chat should hand off to your team and should not treat this as a verification problem. A Read key cannot run address, cancel, or refund tools. Recreate the key as Read/Write and replace all three credential fields together. The same applies if the key is later revoked.
Wrong store: The URL must be the store Voxe should call. Replacing credentials without all three fields will not retarget the store.
Tool not enabled: Select the tool, save, and for writes also enable the action rule with a real refund limit if you use refunds.
Verification link/code: Use the latest link from chat, enter the code only in the form, and complete it within 10 minutes. Wait about a minute before requesting another code.
Confirmation expired: Request the action again in chat. Email verification may still be valid for a short time.
Order not found: The billing email must match. Guest orders still work when the billing email matches. Try a corrected number/date, not a different identity source.
Multiple matching orders: Provide an order number or YYYY-MM-DD date.
No longer eligible / fulfillment started: Status, payment, age, or shipment evidence changed. Handle manually. Restricting eligible statuses reduces how often processing orders are attempted.
Blocked by merchant settings: Age, status, refund maximum, or currency.
Provider/API failure: Check that WooCommerce REST API is reachable and the key is not revoked. Then handle the customer in the Help Desk.
Needs human review: Unconfirmed refunds, unpaid cancellation attempts on paid orders, or address updates that did not save as confirmed.

Security and customer data

Keys are stored as the integration credential, not pasted into chats or system messages.
Customers prove order email through the secure form. Codes in chat are ignored as proof.
Voxe returns order details only for the verified email after a successful unique match.
Do not ask customers to send card numbers, full credentials, or verification codes in the conversation.

What's next

Business Data Integrations Overview — how Business Data integrations work across platforms
How to Connect Shopify — Shopify tools and permissions differ from WooCommerce
How to Set Up the Chat Widget — Hide Branding for the widget and secure pages
How System Messages Work — tool instructions are attached when the integration is active