> ## Documentation Index
> Fetch the complete documentation index at: https://docs.illumichat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WooCommerce Integration

> Connect your WooCommerce store and turn your assistant into an AI-powered e-commerce agent

Connect your WooCommerce store to IllumiChat and transform your AI assistant into an e-commerce agent that helps customers browse products, track orders, manage carts, and update their account — all through natural conversation.

<Note>
  **No manual coding required.** Install the free IllumiChat WordPress plugin and the chat widget appears on your storefront automatically.
</Note>

## What Your Customers Can Do

Once connected, your assistant can handle real shopping conversations:

<CardGroup cols={2}>
  <Card title="Browse Products" icon="magnifying-glass">
    "Do you have any running shoes under \$100?"

    Your assistant searches your WooCommerce catalog and returns real products with names, prices, and links.
  </Card>

  <Card title="Track Orders" icon="truck">
    "Where's my order #1042?"

    Customers can check order status by order number or the email address they used at checkout.
  </Card>

  <Card title="Manage Carts" icon="cart-shopping">
    "Add the blue hoodie in size M to my cart"

    Your assistant can create a cart, add or remove items, and share a checkout link.
  </Card>

  <Card title="Update Account Info" icon="user">
    "Can you update my shipping address?"

    Look up customer records and update contact details and addresses.
  </Card>
</CardGroup>

## Prerequisites

* An IllumiChat workspace with **Admin** access
* A WooCommerce store (WordPress self-hosted or managed)
* **WooCommerce 7.0+** and **WordPress 6.0+**
* WordPress admin access

***

## Setup: Two Paths

There are two ways to connect, depending on where you start. Both end up in the same place.

### Path A — Start from IllumiChat (Recommended)

Use this if you're creating a new assistant or connecting via the Channels settings page.

#### Step 1: Connect your store

<Tabs>
  <Tab title="New assistant (wizard)">
    1. Click **New Assistant** and choose **WooCommerce** as your platform in the type step
    2. Configure your assistant's name and system prompt
    3. In the Share step, enter your full store URL — e.g. `https://yourstore.com` — and click **Connect Store**
  </Tab>

  <Tab title="Existing assistant">
    1. Open your assistant's **Settings → Channels → WooCommerce**
    2. Enter your full store URL and click **Connect**
  </Tab>
</Tabs>

IllumiChat redirects your browser to a WooCommerce consent screen:

> *"Would you like to grant \[IllumiChat] read\_write access to your store?"*

Click **Approve**. WooCommerce sends your store credentials directly to IllumiChat's server — you never handle API keys. You'll be redirected back to IllumiChat automatically.

#### Step 2: Download and install the WordPress plugin

The WordPress plugin is what puts the chat widget on your storefront.

1. After connecting, IllumiChat shows a **Download Plugin** button — click it to download `illumichat-wordpress.zip`
2. In your **WordPress admin**, go to **Plugins → Add New Plugin → Upload Plugin**
3. Click **Choose File**, select the downloaded `.zip`, and click **Install Now**
4. Click **Activate Plugin**

<Warning>
  **Critical: flush your permalink cache after activating.**
  Go to **Settings → Permalinks** in WordPress and click **Save Changes** — without changing anything. WordPress must register the plugin's REST API endpoint before IllumiChat can call it. Skipping this step causes a "Plugin endpoint returned 404" error.
</Warning>

#### Step 3: Push the widget to your storefront

Back in IllumiChat, click **Install widget via plugin**.

IllumiChat calls your store's plugin endpoint, which stores your assistant ID and enables the widget. The chat widget will now appear on every page of your storefront.

That's it. Your assistant is live.

***

### Path B — Start from WordPress (Plugin-first)

Use this if you've already installed the plugin and want to connect from within WordPress.

#### Step 1: Install and activate the plugin

Download `illumichat-wordpress.zip` from your IllumiChat dashboard or the channels page. Then:

1. In **WordPress admin → Plugins → Add New Plugin → Upload Plugin**, upload the zip and activate it
2. Go to **Settings → Permalinks** and click **Save Changes** (required to register the plugin's REST API endpoint)

#### Step 2: Configure the plugin

Go to **WooCommerce → IllumiChat** in your WordPress admin.

You'll see a settings form with:

| Field              | What to enter                                                                                |
| ------------------ | -------------------------------------------------------------------------------------------- |
| **Assistant ID**   | The UUID of your IllumiChat assistant (found in your assistant's Settings page)              |
| **IllumiChat URL** | Leave as the default (`https://app.illumichat.com`) unless you're on a custom domain         |
| **Cookie consent** | Check this to gate widget load on visitor cookie consent (CookieYes / Complianz / WPConsent) |

Enter your Assistant ID and click **Save settings**.

#### Step 3: Connect to WooCommerce

After saving your Assistant ID, a **Connect IllumiChat** button appears.

Click it. You'll be redirected to WooCommerce's consent screen:

> *"Would you like to grant \[IllumiChat] read\_write access to your store?"*

Click **Approve**. WooCommerce sends credentials to IllumiChat and redirects you back to the WordPress plugin settings page, which now shows:

> *Connected. Assistant ID: \[your-uuid]. Widget on storefront: **Enabled**.*

The widget is live on your storefront immediately.

***

## Widget on Storefront

Once the widget is enabled, the WordPress plugin uses WordPress's `wp_enqueue_scripts` hook to inject a loader script into every storefront page footer — no theme edits required.

The script is automatically excluded from **WP Rocket's** JS delay and combine lists. For other caching plugins (LiteSpeed Cache, W3 Total Cache), exclude the widget loader URL from any "Delay JS" or "Combine JS" rules, then flush your cache.

### Manual Snippet (no plugin)

If you prefer not to use the plugin, copy the embed snippet from your WooCommerce channel settings page and paste it before the `</body>` tag in your theme's `footer.php` or via a snippet plugin like **WPCode**.

***

## AI Actions

Each action can be enabled or disabled independently from **Settings → Channels → WooCommerce**.

| Action               | Default | Description                                                  |
| -------------------- | ------- | ------------------------------------------------------------ |
| **Product Search**   | On      | Searches your catalog; returns product name, price, and link |
| **Order Tracking**   | On      | Looks up order status by order number or email               |
| **Cart Management**  | Off     | Creates carts, adds/removes items, shares checkout link      |
| **Customer Updates** | Off     | Looks up and updates customer billing/shipping/contact info  |

<Note>
  **Cart Management** requires the **CartFlows** or **Cart Abandonment Recovery** plugin on your WooCommerce store. WooCommerce does not natively expose abandoned cart data via its REST API.
</Note>

**Example conversations — Product Search:**

* "What laptops do you have?"
* "Show me dresses under \$50"

**Example conversations — Order Tracking:**

* "Where's my order #1042?"
* "Can you check my recent order? My email is [jane@example.com](mailto:jane@example.com)"

**Example conversations — Cart Management:**

* "Add the blue hoodie in medium to my cart"
* "What's in my cart right now?"

**Example conversations — Customer Updates:**

* "Update my shipping address to 123 Main St, New York, NY 10001"
* "What email do you have on file for me?"

***

## Analytics

Track usage from the **Channels → WooCommerce** analytics dashboard.

| Metric            | What it counts                            |
| ----------------- | ----------------------------------------- |
| Product Searches  | Times the assistant searched your catalog |
| Order Lookups     | Order status inquiries                    |
| Cart Actions      | Cart creates, additions, and removals     |
| Customer Updates  | Customer data lookups and modifications   |
| Webhooks Received | Store events delivered by WooCommerce     |

Filter by **7 days**, **30 days**, or **90 days**.

***

## Managing Your Integration

**Enable / Disable** — Toggle the integration on or off without losing your configuration. When disabled, AI actions and the widget stop, but the store stays connected.

**Disconnect Store** — Removes stored credentials. Reconnect at any time via the OAuth flow.

**Test Connection** — Verifies your credentials are valid and the store is reachable.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="&#x22;Install widget via plugin&#x22; returns an error (404)">
    The plugin's REST endpoint wasn't found. Work through this checklist in order:

    1. **Flush permalinks** — In WordPress, go to **Settings → Permalinks** and click **Save Changes**. This is required after activating any plugin that adds REST routes. It's the most common cause of this error.
    2. **Confirm the plugin is active** — In WordPress admin, go to **Plugins** and verify IllumiChat shows as "Active".
    3. **Check WooCommerce is active** — The plugin's REST endpoint authenticates via WooCommerce's API middleware. WooCommerce must be installed and active.
    4. **Check for REST API security plugins** — Wordfence, "Disable REST API", and similar plugins can block all REST endpoints. Temporarily disable them to test.
    5. **Check permalink structure** — "Plain" permalinks (`?p=123`) disable the REST API entirely. Choose any other option under Settings → Permalinks.
  </Accordion>

  <Accordion title="Widget not appearing on the storefront">
    * Verify the plugin is active and you clicked **Install widget via plugin** successfully (check for a green success message in IllumiChat)
    * **Caching plugins**: flush your cache and exclude the widget loader URL from JS delay/combine rules. WP Rocket is handled automatically; for other plugins (LiteSpeed, W3TC), add the exclusion manually.
    * **Cookie consent**: if cookie consent is enabled in the plugin settings, the widget waits for visitor consent. Test in an incognito window or disable the consent toggle temporarily.
    * **Hosting CSP / firewall**: some managed hosts block external scripts. Whitelist `app.illumichat.com` (or your IllumiChat URL) in your hosting firewall or CSP header.
  </Accordion>

  <Accordion title="&#x22;unable to send the consumer data&#x22; on the WooCommerce consent screen">
    WooCommerce couldn't POST credentials back to IllumiChat after you clicked Approve. Causes:

    * **Firewall blocking outbound POST**: your hosting provider blocks outbound HTTP connections from the server. Contact your host to whitelist IllumiChat's IP range, or try on a different network.
    * **Incorrect store URL**: the URL you entered must match your WordPress site URL exactly (check under **WordPress admin → Settings → General → WordPress Address**).
    * **Session expired**: the OAuth session has a 15-minute window. If you took more than 15 minutes on the consent screen, start over.
  </Accordion>

  <Accordion title="AI actions not working in conversations">
    * Confirm the store status is **Connected** (green) on the Channels overview
    * Check that the specific action toggle is **on** — e.g., Product Search defaults to On but Cart Management defaults to Off
    * Click **Test Connection** to verify credentials are still valid
    * If the test fails, disconnect and reconnect to issue fresh credentials
  </Accordion>

  <Accordion title="The Connect button in the WordPress plugin is greyed out">
    You need to save an **Assistant ID** first. Enter your assistant's UUID in the Assistant ID field on the **WooCommerce → IllumiChat** settings page and click **Save settings** — the Connect button will then become active.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Widget Customization" icon="paintbrush" href="/guides/widget-customization">
    Customize the look and feel of the chat widget on your storefront.
  </Card>

  <Card title="Effective Prompts" icon="wand-magic-sparkles" href="/guides/effective-prompts">
    Write better system prompts to get the most out of your WooCommerce assistant.
  </Card>
</CardGroup>