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

# WooCommerce

> Let your assistant answer product and order questions from your WooCommerce shop.

Let your assistant look up products with price and stock, tell callers the status of their order, and pass cancellation and return requests to your shop team as private order notes. Phone orders are optional. The assistant never cancels an order itself and never moves money.

## Set up your shop

1. Use a shop with an HTTPS address. In WordPress, open **Settings → Permalinks** and choose any option except **Plain**.
2. In WooCommerce, open **Settings → Advanced → REST API → Add key**. Choose a user with the shop manager role and the permission **Read** for questions, or **Read/Write** for request notes and phone orders.
3. Copy the consumer key (starts with `ck_`) and the consumer secret (starts with `cs_`). WooCommerce shows the secret once.
4. Open **Agent Tools → Marketplace → WooCommerce**. Enter the shop address, the consumer key and the consumer secret.
5. Choose **Add**. The connection is checked before it is saved: the key must read products and orders. Then assign the connection to your assistant.

To change the shop address or the keys later, remove the tool and connect again.

## What the assistant can do

Enabled by default:

* Search products by name or category, with price, stock and variants. Only published products that are visible in the catalog appear. The assistant never guesses a price.
* Tell the status, contents and total of an order, and find a caller's recent orders.
* Leave a cancellation request for your team.
* Leave a return or exchange request for your team.

Optional, choose it under **Edit**:

* Phone orders.

## Order privacy

The order number alone is never enough. The assistant shows an order when one of these holds:

* The caller's phone number matches the phone number of the order, and no other customer (another e-mail address) uses that number.
* The caller gives the e-mail address used for the order, or its delivery postcode.

If the details do not match, the assistant reveals nothing, not even whether the order exists. After three wrong answers in one conversation, it stops checking for an hour. A withheld number always leads to a question for the e-mail address or the postcode.

The assistant never reads out addresses, e-mail addresses, phone numbers, customer notes or refunds.

## Cancellation, return and exchange requests

A request is a private order note for your team (never visible to the customer). It carries a heading, the reason, which check passed, a callback number and a short reference. Example:

```text theme={null}
CANCELLATION REQUEST (Your brand)
Reason: Ordered twice by mistake
Identity check: caller phone number matched the order
Callback number: +491512345678
Ref: 4f2a9c1e
```

* **Cancellation requests** are possible while the order waits for payment, is on hold or is being prepared.
* **Return and exchange requests** are possible for completed orders. The note lists the products and the reason.

The assistant changes nothing in the order, creates no refund and no return label, and promises nothing: your team decides. Each order takes one request per kind; a second request for the same order is not written again. The note title shows your workspace brand.

## Phone orders

Phone orders are off by default. Turn them on under **Edit**.

The assistant collects up to five different simple products that are in stock, plus name, e-mail address and delivery address. It reads everything back and creates the order only after the caller says yes. Products with variants are not supported.

* The order starts as unpaid (**Pending payment**). Nothing is reserved before the customer pays.
* WooCommerce e-mails the customer the payment link in your shop's own design, as a customer note. The assistant never reads the link and never takes card or bank details.
* The assistant quotes the product prices as listed in your shop, without shipping. The payment page shows the final amount.
* The same order for the same e-mail address on the same day is created once.

Enable **Customer note** under **WooCommerce → Settings → Emails**, otherwise no link reaches the customer. If the note cannot be sent, the assistant says that the shop will send the payment details.

## Settings

Three settings belong to the connection:

* **Products per answer:** 3, 5 or 10 products (default 3).
* **Mention out-of-stock products:** whether sold-out products appear in answers (default yes).
* **Hand over phone orders above:** the order value in your shop currency above which the assistant offers to forward the caller to your team. 0 means no limit.

To change them, edit the connection under **Automations → Connections** or connect again. The tool selection (requests, phone orders) changes directly on the tool.

## Recognising callers

When the channel provides the caller's number, the assistant receives a short summary before the conversation: the first name, the latest order number with its status and date, and how many orders are open. This happens only when exactly one customer uses the number. The assistant gets no e-mail address, phone number, address or total from it.

The shop gets about 2.5 seconds for this lookup. A slow shop skips it, and the assistant asks for the order number instead.

## Test safely

Requests write real notes on real orders, and phone orders create real unpaid orders and send a real e-mail. Test with a test product, your own number and your own e-mail address, and delete the test order afterwards.

## Channels

Voice, web chat, WhatsApp, Messenger and email use the same tools. A matching caller number verifies an order only where the channel provides the number. Everywhere else, and when the number is withheld, the assistant asks for the e-mail address or the postcode.

## Automations

Connect **WooCommerce** under **Automations → Connections**, or import its Agent Tool connection. Every tool is available as an action. An automation started by a call or a text conversation (SMS, WhatsApp) knows the other party's number from that call itself. Other runs (webhook, schedule) have no caller: **Order status** needs an e-mail address or a postcode there, and **Caller's recent orders** reports that no number is available. Request and phone order actions need a **Confirmed by the caller** value that is true only after the caller said yes.

## API, MCP, CLI & SDK

`POST /api/v1/tools/integrations/woocommerce` · MCP `connect_integration` · CLI `famulor connect-integration woocommerce` · SDK `client.api.connectIntegration`.

```bash theme={null}
famulor connect-integration woocommerce --fields '{"shop_url":"https://shop.example.com","consumer_key":"ck_YOUR_KEY","consumer_secret":"'"$WC_SECRET"'"}'
```

```typescript theme={null}
import { Famulor } from 'famulor-sdk';

const client = new Famulor({ apiKey: process.env.FAMULOR_API_KEY });
const { data: tool } = await client.api.connectIntegration({
  path: { provider: 'woocommerce' },
  body: { fields: {
    shop_url: 'https://shop.example.com',
    consumer_key: 'ck_YOUR_KEY',
    consumer_secret: process.env.WC_SECRET,
  } },
});
console.log(tool.id);
```

Optional fields: `products_per_answer`, `mention_out_of_stock` and `phone_order_limit`.

## Troubleshooting

* **"This address does not lead to the WooCommerce REST API":** check the shop address. WordPress permalinks set to **Plain** also cause this; choose another option under **Settings → Permalinks**.
* **"The shop answered with a web page instead of data":** a security plugin or firewall blocks API requests. Allow requests to `/wp-json/wc/v3/` from outside.
* **"WooCommerce rejected the consumer key or secret":** the key was revoked, its user was deleted, or the key cannot read orders. Create a new key for a shop manager.
* **Requests fail and the log says the API key can only read:** a request note needs the permission **Read/Write**.
* **The connection check fails although the keys are right:** some hosts remove the Authorization header. Ask your host to let it through. The connection also tries a fallback on its own.
* **A caller's number finds no order:** the shop search compares the last 8 digits of the number. If your shop stores numbers with spaces, ask for the order number instead.

[WooCommerce REST API documentation](https://developer.woocommerce.com/docs/apis/rest-api/)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.