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

# WooCommerce integration

> Connect Voiceflow to WooCommerce so your agent can compare public products, read a permitted customer’s order and carry out confirmed merchant-approved changes.

## Overview

Connect Voiceflow to WooCommerce so your agent can compare public products, read a permitted customer’s order and carry out confirmed merchant-approved changes. API tools read the store; Knowledge supplies approved descriptions and policies; Functions can assess a return request or build a bounded shopping link.

- **[Help choose a product](#finding-products)** — compare returned facts and recheck the selected variation.
- **[Check an order](#looking-up-orders)** — use the order authorized by your application.
- **[Correct an address](#updating-orders)** or **[cancel an eligible order](#cancelling-orders)** — confirm the action and verify the saved result.
- **[Record a review request](#record-review-request)** — retain a private note for the merchant.
- **[Continue shopping](#create-shopping-links)** — send the confirmed selection to the store for buyer review.

Public catalog GETs need no WooCommerce credential. Private order tools use a merchant-authorized REST key; neither that key nor an order number authenticates the shopper.

<a id="connecting-woocommerce"></a>

## Connecting WooCommerce

Prepare private order access separately from public catalog reads.

Use a dedicated test project/store and a merchant administrator who can manage WooCommerce API keys. Public product discovery can start at [Finding products](#finding-products) without a private key.

### Prepare the merchant credential

In WordPress **Settings → Permalinks**, choose a structure other than **Plain** before using these `/wp-json/wc/v3` URLs. See the [REST API requirements](https://developer.woocommerce.com/docs/apis/rest-api/).

### 1. Create a restricted test key

The merchant creates a dedicated WordPress user with the required WooCommerce capabilities. Open **WooCommerce → Settings → Advanced → REST API → Add Key**. Select that user, add a description and choose **Read** for order lookups. Generate and save the Consumer Key/Secret. Use a separate **Read/Write** key for the confirmed changes below. [WooCommerce authentication](https://developer.woocommerce.com/docs/apis/rest-api/authentication/) explains user permissions and key revocation.

### 2. Prepare authorization for the intended store

Use HTTPS and `/wp-json/wc/v3`. Your developer prepares `Basic ` followed by Base64 of `CONSUMER_KEY:CONSUMER_SECRET`. This is the full private authorization value, not shopper identity. Have the application supply a permitted test order’s numeric API ID and its customer association.

#### Studio

In the API request editor, add each braced name under **Input variables** first. Insert that local input in the URL, header, parameter or raw-body position shown as `{name}` below. Set its provided value separately in the attached tool; a local input is not itself a project variable or Secret.

In **More → Secrets**, create restricted **woocommerce_read_authorization** with that complete Basic value. Creating its default also writes Main’s Published value, so use the dedicated test project. Set the intended Environment’s Draft override when needed.

Continue to [Looking up orders](#looking-up-orders) to create the request and configure its provided inputs. You can set up public product reads independently.

#### Developer

<a id="voiceflow-api-setup"></a>

Use a [Voiceflow bearer credential](/docs/api-reference/authentication) with access to an editable test project and Environment. Keep it on your backend or development machine. Set:

```sh
export VF_TOKEN='YOUR_VOICEFLOW_BEARER_TOKEN'
export PROJECT_ID='YOUR_TEST_PROJECT_ID'
export ENVIRONMENT='main'
```

Use the current [Voiceflow CLI](/docs/cli/install) for CLI examples. Management and standalone tests use the saved Draft. A standalone request does not attach a tool, compile the agent or publish it.

Set `WOOCOMMERCE_AUTHORIZATION` in your shell to the merchant-provided credential described above. Creating a Secret default also writes **Main’s Published value**; perform initial setup in a dedicated test project.

#### API

```sh
export SECRET_NAME='woocommerce_read_authorization'
jq -n --arg name "$SECRET_NAME" --arg value "$WOOCOMMERCE_AUTHORIZATION" \
  '{name:$name,visibility:"restricted",defaultValue:$value}' |
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/secret?projectID=$PROJECT_ID" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' --data-binary @-
```

Retain `secret.id` as `SECRET_ID`, then set this test Environment’s Draft value:

```sh
jq -n --arg value "$WOOCOMMERCE_AUTHORIZATION" --arg env "$ENVIRONMENT" \
  '{value:$value,environmentAlias:$env,versionVariant:"draft"}' |
curl --fail-with-body --silent --show-error -X PUT \
  "https://realtime-api.voiceflow.com/v1/stable/secret/$SECRET_ID/value?projectID=$PROJECT_ID" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' --data-binary @-
```

#### CLI

```sh
export SECRET_NAME='woocommerce_read_authorization'
jq -n --arg name "$SECRET_NAME" --arg value "$WOOCOMMERCE_AUTHORIZATION" \
  '{name:$name,visibility:"restricted",defaultValue:$value}' |
vf secret create --project-id "$PROJECT_ID" --output-format json
```

Retain `secret.id` as `SECRET_ID`, then set the test Draft value:

```sh
jq -n --arg value "$WOOCOMMERCE_AUTHORIZATION" --arg env "$ENVIRONMENT" \
  '{value:$value,environmentAlias:$env,versionVariant:"draft"}' |
vf secret set-value --project-id "$PROJECT_ID" --secret-id "$SECRET_ID" --output-format json
```

Before serving traffic, [set the target Published Secret value](/docs/cli/commands/secret/set-value) with `versionVariant: "published"`, then [publish the tested Environment](/docs/documentation/deploy/environments/publishing). A Draft override does not configure Published.

### Rotate or revoke private access

Replace the runtime credential and repeat a read before retiring the old key.

Generate a replacement key in WooCommerce, update the relevant Voiceflow Secret default and Draft/Published values, then verify a known read before revoking the old key. Deleting its WordPress user or revoking the key breaks access. Changing an Environment does not change a fixed store URL. Removing a Voiceflow tool does not revoke the merchant key or delete imported Knowledge.

<a id="finding-products"></a>

## Finding products

Compare public catalog facts and recheck the selected variation.

Use WooCommerce’s public [Store API](https://developer.woocommerce.com/docs/apis/store-api/resources-endpoints/products/) for shopper product discovery. The example searches visible shirts; it requires no API key or nonce.

### 1. Configure a public product search

#### Studio

In **Agent → Global tools → + → API call**, create **Find WooCommerce products** with the fields below. This public request needs no merchant credential.

Add **search** under **Input variables**, then use that local input in the **search** parameter.

| Request field | Value |
| --- | --- |
| Method | `GET` |
| URL | `https://YOUR_STORE/wp-json/wc/store/v1/products` |
| Parameter: search | `{search}` |
| Parameter: catalog_visibility | `visible` |
| Parameter: page | `1` |
| Parameter: per_page | `3` |

Public WooCommerce product request with search and catalog visibility parameters — Configure the public catalog request and encoded query parameters.

#### Developer

Prepare the [Voiceflow API variables](#voiceflow-api-setup) first. Public Store API product reads do not require a WooCommerce key.

Download [woocommerce-products.json](/examples/ecommerce/providers/woocommerce-products.json) as `tool.json`. Replace the fictional store origin or site GUID where present. Create a separate saved request for this operation; use its returned `apiTool.id` as `API_TOOL_ID`.

Save these standalone test values as `inputs.json`, replacing fictional IDs with your permitted test records:

```json
{
  "inputs": {
    "search": "shirt"
  }
}
```

#### API

### 1. Create the saved API request

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/api-tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @tool.json
```

Retain `apiTool.id` as `API_TOOL_ID` and save the same value as `PRODUCT_TOOL_ID` now. Resolve any `unresolvedReferences`. Inspect its inputs with the [API-tool schema](/docs/cli/commands/api-tool/get-schema) before execution.

### 2. Run the saved request once

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/api-tool/$API_TOOL_ID/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @inputs.json
```

#### CLI

### 1. Create the saved API request

```sh
vf api-tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --output-format json < tool.json
```

Retain `apiTool.id` as `API_TOOL_ID`, save the same value as `PRODUCT_TOOL_ID` now, and resolve `unresolvedReferences`.

### 2. Inspect and execute it

```sh
vf api-tool get-schema --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$API_TOOL_ID" --output-format json

vf api-tool execute --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$API_TOOL_ID" --output-format json < inputs.json
```

Require `success: true`, `error: null` and `truncated: false`, then inspect `output.status` and `output.body`. A Voiceflow HTTP 200 alone is not provider success.

### 2. Compare the returned candidates

Require the expected public product and storefront `permalink`. In Code, candidates are `output.body[]` after HTTP 200. Compare `name`, descriptions, images and returned prices with the shopper’s requirements. Password-protected descriptions may be redacted; keep those products out of this worked recommendation.

### 3. List the parent product’s variations

Variations are excluded from the first search. Use the returned parent product ID; this example lists at most 20 variations. A missing option is not proof that it does not exist.

#### Studio

Create **Find WooCommerce variations** as a separate public API call:

| Request field | Value |
| --- | --- |
| Method | `GET` |
| URL | `https://YOUR_STORE/wp-json/wc/store/v1/products` |
| Parameter: type | `variation` |
| Parameter: parent | `{product_id}` |
| Parameter: per_page | `20` |

#### Developer

Download [woocommerce-variations.json](/examples/ecommerce/providers/woocommerce-variations.json) as `tool.json`. Save `{"inputs":{"product_id":"RETURNED_PARENT_ID"}}` as `inputs.json`, replacing the placeholder. Create and execute it with the API/CLI flow above. Save its returned `apiTool.id` immediately as `VARIATIONS_TOOL_ID` before reusing `API_TOOL_ID`; keep the search request’s `PRODUCT_TOOL_ID` unchanged.

Compare the returned IDs and attributes with the shopper’s selected option. Narrow the selection or continue in the store if you cannot confirm it.

### 4. Recheck the chosen product or variation

#### Studio

Create **Read WooCommerce selected product** as a separate public API call. Supply an ID returned by the product or variation result:

| Request field | Value |
| --- | --- |
| Method | `GET` |
| URL | `https://YOUR_STORE/wp-json/wc/store/v1/products/{product_id}` |

#### Developer

Download [woocommerce-product.json](/examples/ecommerce/providers/woocommerce-product.json) as `tool.json`. Save `{"inputs":{"product_id":"RETURNED_SELECTED_ID"}}` as `inputs.json`, replacing the placeholder. Create and execute it with the flow above, saving its returned ID as `SELECTED_PRODUCT_TOOL_ID` before reusing `API_TOOL_ID`. Keep `PRODUCT_TOOL_ID` unchanged.

Use this exact result for price, currency and availability claims.

### Let the agent use the product read

#### Studio

In **Agent → Global tools**, keep **Find WooCommerce products** attached. Describe when to search for product candidates and let the agent supply **search** from the shopper’s requirements. This public request has no merchant credential. Run a product question and compare the recommendation with the actual returned candidates.

#### Developer

Use `PRODUCT_TOOL_ID`, saved when you created the product request. It is separate from the order and selected-product request IDs.

Resolve this request’s actual input IDs:

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/api-tool-variable?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT&apiToolID=$PRODUCT_TOOL_ID" \
  -H "Authorization: Bearer $VF_TOKEN"
```

Match `variables[].name` to `id`. Save `product-attachment.json`, replacing its tool/input IDs:

```json
{
  "type": "api",
  "apiToolID": "YOUR_PRODUCT_API_TOOL_ID",
  "target": {
    "global": true
  },
  "description": "Find approved product candidates when the shopper asks for help choosing a product. Compare returned facts and use the verified storefront link.",
  "inputVariables": {
    "search": {
      "apiToolInputVariableID": "SEARCH_INPUT_ID",
      "required": true,
      "defaultValue": null
    }
  }
}
```

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @product-attachment.json
```

#### CLI

```sh
vf tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --output-format json < product-attachment.json
```

### 1. Compile the Draft

Resolve `unresolvedReferences`, then compile the Environment:

```sh
curl --fail-with-body --silent --show-error -X PUT \
  "https://realtime-api.voiceflow.com/v1/stable/environment/$ENVIRONMENT/compile?projectID=$PROJECT_ID" \
  -H "Authorization: Bearer $VF_TOKEN"
```

### 2. Test the agent’s product read

Run a Draft conversation with the stated test inputs and inspect the actual product tool call, result and recommendation. Test an empty result and an unmet requirement too. Standalone execution alone does not verify agent routing.

| Returned field | Interpretation |
| --- | --- |
| `prices.price`, `regular_price`, `sale_price` | Minor-unit strings. Use `currency_minor_unit` and preserve `currency_code`; `"4900"` with 2 minor digits means 49.00. |
| `prices.price_range` | Cross-variation range; a parent’s scalar price can be a minimum. |
| `is_in_stock`, `is_on_backorder`, `is_purchasable` | Check together on the selected variation. In stock can include backorders. |
| `low_stock_remaining: null` | Unknown/not applicable; neither zero nor unlimited stock. |

Use the returned product page or [shopping link](#create-shopping-links). Voiceflow’s server request does not inherit the buyer’s browser cart, tax location or currency-plugin session; the store owns final checkout totals.

### Make variation rechecks callable

Keep the variation-list and exact-product requests as separate tools. A product ID here comes from a returned public product; it is not an order identifier.

#### Studio

In **Agent → Global tools**, attach **Find WooCommerce variations**. Let the agent supply **product_id** from the parent product result. Test a variable parent and inspect the variation IDs/attributes returned before the agent chooses an option.

#### Developer

Use `VARIATIONS_TOOL_ID`, saved when you created this separate request. List its inputs with the API-tool-variable call above, replacing the API tool ID with `VARIATIONS_TOOL_ID`; use this request's actual `variables[].id` values. Save this body as `additional-attachment.json`:

```json
{
  "type": "api",
  "apiToolID": "VARIATIONS_TOOL_ID",
  "target": {
    "global": true
  },
  "description": "List variations for the returned public parent product before choosing an option.",
  "inputVariables": {
    "product_id": {
      "apiToolInputVariableID": "PRODUCT_ID_INPUT_ID",
      "required": true,
      "defaultValue": null
    }
  }
}
```

Replace the tool/input placeholders, then POST the body to the same `/v2/stable/tool` attachment endpoint above (or `vf tool create` with the same project and Environment). Resolve `unresolvedReferences` and compile the Environment again. Test a variable parent and inspect the variation IDs/attributes returned before the agent chooses an option.

#### Studio

Attach **Read WooCommerce selected product** separately. Let the agent supply **product_id** only from a returned product/variation result. Test an option-specific question and verify that the exact selected ID is re-read before the answer; route missing or unavailable options back to selection.

#### Developer

Use `SELECTED_PRODUCT_TOOL_ID`, saved when you created this separate request. List its inputs with the API-tool-variable call above, replacing the API tool ID with `SELECTED_PRODUCT_TOOL_ID`; use this request's actual `variables[].id` values. Save this body as `additional-attachment.json`:

```json
{
  "type": "api",
  "apiToolID": "SELECTED_PRODUCT_TOOL_ID",
  "target": {
    "global": true
  },
  "description": "Recheck the selected public product or variation ID before making price or availability claims.",
  "inputVariables": {
    "product_id": {
      "apiToolInputVariableID": "PRODUCT_ID_INPUT_ID",
      "required": true,
      "defaultValue": null
    }
  }
}
```

Replace the tool/input placeholders, then POST the body to the same `/v2/stable/tool` attachment endpoint above (or `vf tool create` with the same project and Environment). Resolve `unresolvedReferences` and compile the Environment again. Test an option-specific question and verify that the exact selected ID is re-read before the answer; route missing or unavailable options back to selection.

### The search is empty or incomplete

Check visibility, filters and pagination without inventing candidates.

The Store API exposes published products; a non-published exact product returns 404. Keep `catalog_visibility=visible` for this recommendation path. Increase `page` only when needed and inspect pagination headers such as `X-WP-TotalPages`; the first three results are not the full catalog. Verify installed version/extensions before relying on additional stock or custom filters. [Help shoppers choose products](/docs/guides/integrations/commerce/help-shoppers-choose-products) covers the complete comparison journey.

<a id="looking-up-orders"></a>

## Looking up orders

Return permitted order information without inventing delivery evidence.

First complete [Connecting WooCommerce](#connecting-woocommerce) to prepare the read credential for this store.

Have the authenticated application resolve the permitted numeric API order ID. A displayed order number, email search or `customer_id` supplied by the shopper is not authorization. For guest orders, `customer_id: 0` still needs an application-owned association.

### 1. Prepare the authorized order input

#### Studio

In **More → Variables**, create **woocommerce_order_id** with an empty default. Your developer must authenticate the customer, resolve an order they may access and populate this variable before the lookup.

For an app-driven conversation, pass `variables: {"woocommerce_order_id":"AUTHORIZED_API_ORDER_ID"}` on the [conversation action](/docs/api-reference/v4interact/interact-non-stream#streaming-action). Use one permitted test order; creating an empty variable alone does not supply an order ID.

#### Developer

Create the identity variable with an empty default; your authenticated backend supplies its permitted order ID on the first [conversation action](/docs/api-reference/v4interact/interact-non-stream#streaming-action) before a read can run:

```sh
jq -n --arg name 'woocommerce_order_id' \
  '{name:$name,color:"#515A63",defaultValue:""}' |
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/variable?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' --data-binary @-
```

For example, the backend action includes `variables: {"woocommerce_order_id":"VERIFIED_ORDER_API_ID"}`. An unchecked browser value is not an authorization mapping.

### 2. Read the permitted order

#### Studio

In **Agent → Global tools → + → API call**, create **Read permitted WooCommerce order** as **GET** `https://YOUR_STORE/wp-json/wc/v3/orders/` with the trusted **order_id** appended. Add **Authorization** through the tool-local **authorization** input and `Accept: application/json`. Bind that input to **woocommerce_read_authorization** and **order_id** to **woocommerce_order_id**. Choose **Run** in the request editor and supply the permitted test order ID and the named read Secret. Inspect this standalone response before testing the agent.

| Request field | Value |
| --- | --- |
| Method | `GET` |
| URL | `https://YOUR_STORE/wp-json/wc/v3/orders/{order_id}` |
| Header: Authorization | `{authorization}` |
| Header: Accept | `application/json` |

#### Developer

Download [woocommerce-order.json](/examples/ecommerce/providers/woocommerce-order.json) as `tool.json`. Replace the fictional store origin or site GUID where present. Create a separate saved request for this operation; use its returned `apiTool.id` as `API_TOOL_ID`.

Save these standalone test values as `inputs.json`, replacing fictional IDs with your permitted test records:

```json
{
  "inputs": {
    "authorization": "{woocommerce_read_authorization}",
    "order_id": "727"
  }
}
```

#### API

### 1. Create the saved API request

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/api-tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @tool.json
```

Retain `apiTool.id` as `API_TOOL_ID` and save the same value as `ORDER_TOOL_ID` now. Resolve any `unresolvedReferences`. Inspect its inputs with the [API-tool schema](/docs/cli/commands/api-tool/get-schema) before execution.

### 2. Run the saved request once

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/api-tool/$API_TOOL_ID/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @inputs.json
```

#### CLI

### 1. Create the saved API request

```sh
vf api-tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --output-format json < tool.json
```

Retain `apiTool.id` as `API_TOOL_ID`, save the same value as `ORDER_TOOL_ID` now, and resolve `unresolvedReferences`.

### 2. Inspect and execute it

```sh
vf api-tool get-schema --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$API_TOOL_ID" --output-format json

vf api-tool execute --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$API_TOOL_ID" --output-format json < inputs.json
```

Require `success: true`, `error: null` and `truncated: false`, then inspect `output.status` and `output.body`. A Voiceflow HTTP 200 alone is not provider success.

### 3. Verify the record before answering

Require HTTP 200 and returned `id` equal to the permitted API ID; in Code this is `output.body.id`. Check the customer association and relevant line items before disclosing details. Keep billing data and unrelated personal fields private.

| Order information | Customer use |
| --- | --- |
| `number`, `status`, `line_items` | Explain the matched order and recorded merchant state. |
| `currency`, totals, refunds | Preserve currency and distinguish recorded refund data from actual funds receipt. |
| `date_completed` | Completion is not proof of carrier delivery. |

Use [Check an order](/docs/guides/integrations/commerce/check-an-order) for the customer journey. Carrier tracking requires an actual fulfillment/extension contract verified for that store; core order status does not provide it.

### Make the permitted read available to the agent

Use the order request you just tested. In Code, use its saved `ORDER_TOOL_ID`; the public product request is a separate resource.

#### Studio

### 1. Provide the credential and order ID

Open **Read permitted WooCommerce order** under **Agent → Global tools**. Keep both inputs enabled. Open each input’s **Default value** and select:

| Tool input | Provided value |
| --- | --- |
| **authorization** | Secret **woocommerce_read_authorization** |
| **order_id** | Variable **woocommerce_order_id** |

Both rows should show **Value provided**. Keep these values out of model collection.

WooCommerce read credential bound to a named restricted Secret — Bind order access to a Secret and an application-provided order ID.

WooCommerce API tool with the application-provided order ID — Keep private order reads bound to the application-authorized record.

### 2. Test an order question

Set the tool’s **Trigger** to answer questions about the application-authorized order. Run a Draft conversation through your application, inspect the tool’s actual input ID and compare its answer with the same order in the store.

#### Developer

List this API tool’s input IDs:

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/api-tool-variable?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT&apiToolID=$ORDER_TOOL_ID" \
  -H "Authorization: Bearer $VF_TOKEN"
```

Match `variables[].name` to `id`. Save `attachment.json`, replacing both input IDs and the API tool ID:

```json
{
  "type": "api",
  "apiToolID": "YOUR_VOICEFLOW_API_TOOL_ID",
  "target": {
    "global": true
  },
  "description": "Read only the WooCommerce order authorized by the signed-in application when the customer asks about that order.",
  "inputVariables": {
    "authorization": {
      "apiToolInputVariableID": "AUTH_INPUT_ID",
      "required": false,
      "defaultValue": "{woocommerce_read_authorization}"
    },
    "order_id": {
      "apiToolInputVariableID": "ORDER_INPUT_ID",
      "required": false,
      "defaultValue": "{woocommerce_order_id}"
    }
  }
}
```

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' --data-binary @attachment.json
```

#### CLI

```sh
vf tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --output-format json < attachment.json
```

Resolve `unresolvedReferences`, then compile the Draft:

```sh
curl --fail-with-body --silent --show-error -X PUT \
  "https://realtime-api.voiceflow.com/v1/stable/environment/$ENVIRONMENT/compile?projectID=$PROJECT_ID" \
  -H "Authorization: Bearer $VF_TOKEN"
```

[Run a Draft conversation](/docs/cli/commands/conversation/send) with your application-provided identity. Reuse existing attachments where appropriate; creation is not an update. Compile and standalone execution do not publish.

### The order cannot be confirmed

Separate missing access, missing records and provider errors.

Test a permitted order, missing ID and wrong returned/customer ID. Stop disclosure on association failure or a mismatched ID. Inspect 401/403 credentials/capabilities and 404 records separately. Do not search unrelated customers or interpret a failed read as a delivery result.

<a id="updating-orders"></a>

## Updating orders

Apply a complete customer-confirmed shipping correction.

First [read the authorized order](#looking-up-orders) to prepare its provided input and verify the current record.

Before a write, the merchant supplies a separate Read/Write key. Store its complete Basic value as **woocommerce_write_authorization** using the [Secret setup](#prepare-the-merchant-credential), with the intended Draft/Published values. Your application authorizes the order and confirms merchant eligibility before the Workflow executes.

### 1. Prepare the confirmed shipping fields

Read the current permitted order and preserve address fields outside the intended correction. Confirm the complete destination with the customer. Send only approved `shipping` fields; omit payment flags such as `set_paid`. The fictional test body is:

```json
{
  "shipping": {
    "first_name": "Maya",
    "last_name": "Chen",
    "address_1": "123 Example Street",
    "address_2": "",
    "city": "Toronto",
    "state": "ON",
    "postcode": "M5V 2T6",
    "country": "CA"
  }
}
```

### 2. Run the bounded correction

#### Studio

Create **Update confirmed WooCommerce address** as a **PUT** API call to the permitted order URL. Add JSON content type and a raw JSON body containing the tool input `{payload}`. In **More → Variables**, create **woocommerce_confirmed_payload** with an empty default. Have your backend serialize the confirmed body with [prepare-commerce-payload.mjs](/examples/ecommerce/prepare-commerce-payload.mjs) and populate it before execution.

In the confirmed Workflow path, add the saved request through an **API call** tool step. Bind **authorization** to the write Secret, **order_id** to the application-owned order variable and **payload** to **woocommerce_confirmed_payload** as provided values. Keep this mutation off unconfirmed Global tools.

| Request field | Value |
| --- | --- |
| Method | `PUT` |
| URL | `https://YOUR_STORE/wp-json/wc/v3/orders/{order_id}` |
| Header: Authorization | `{authorization}` |
| Header: Accept | `application/json` |
| Header: Content-Type | `application/json` |
| Body mode | `Raw → JSON` |
| Body | `{payload}` |

Confirmed WooCommerce address Workflow with provided API inputs — Use trusted order and confirmed-payload values on the change path.

#### Developer

For this Code path, the authenticated backend must enforce order access, merchant eligibility and explicit confirmation **before** calling execute. Preparing JSON or running a saved request does not enforce those checks. Re-read the order before reporting success.

Download [woocommerce-address.json](/examples/ecommerce/providers/woocommerce-address.json) as `tool.json`. Replace the fictional store origin or site GUID where present. Create a separate saved request for this operation; use its returned `apiTool.id` as `API_TOOL_ID`.

Save the complete confirmed body above as `confirmed-body.json`. Download [prepare-commerce-payload.mjs](/examples/ecommerce/prepare-commerce-payload.mjs) beside it. Your backend uses its `stringifyToolJSON` helper to preserve JSON and literal brace text; it does not perform authorization. For this controlled test:

```sh
node prepare-commerce-payload.mjs confirmed-write woocommerce_write_authorization 727 < confirmed-body.json > inputs.json
```

#### API

### 1. Create the saved API request

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/api-tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @tool.json
```

Retain `apiTool.id` as `API_TOOL_ID`. Resolve any `unresolvedReferences`. Inspect its inputs with the [API-tool schema](/docs/cli/commands/api-tool/get-schema) before execution.

### 2. Run the saved request once

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/api-tool/$API_TOOL_ID/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @inputs.json
```

#### CLI

### 1. Create the saved API request

```sh
vf api-tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --output-format json < tool.json
```

Retain `apiTool.id` as `API_TOOL_ID` and resolve `unresolvedReferences`.

### 2. Inspect and execute it

```sh
vf api-tool get-schema --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$API_TOOL_ID" --output-format json

vf api-tool execute --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$API_TOOL_ID" --output-format json < inputs.json
```

Require `success: true`, `error: null` and `truncated: false`, then inspect `output.status` and `output.body`. A Voiceflow HTTP 200 alone is not provider success.

### 3. Verify the persisted address

Require HTTP 200, the permitted returned `id` and the expected `shipping` fields. Read that order again and compare the full destination. A saved address correction does not guarantee an existing shipment was rerouted.

Follow the [order contract](https://developer.woocommerce.com/docs/apis/rest-api/v3/orders/) and [change workflow](/docs/guides/integrations/commerce/change-or-cancel-an-order). After a timeout, inspect the actual order before considering another write.

<a id="record-review-request"></a>

## Record a request for review

Save a private order note without promising a return or refund.

First [read the authorized order](#looking-up-orders) to prepare its provided input and verify the current record.

Use a merchant-approved internal note after authorizing the order and confirming the customer’s request. This records work for staff; it does not create a help-desk conversation or notify a live teammate by itself.

Prepare a separate **Read/Write** key and create or reuse Secret **woocommerce_write_authorization** for its full Basic value using the [credential setup](#prepare-the-merchant-credential), with the intended Draft/Published values. In those setup examples, change `SECRET_NAME` to `woocommerce_write_authorization` and use the write key’s complete value.

Save this fictional test body as `confirmed-body.json`:

```json
{
  "note": "Customer confirmed a request for return review. No return or refund has been authorized.",
  "customer_note": false
}
```

#### Studio

Create or reuse **woocommerce_confirmed_payload** in **More → Variables**, keeping its default empty. Have the developer serialize the customer-confirmed private note with [prepare-commerce-payload.mjs](/examples/ecommerce/prepare-commerce-payload.mjs) and populate that variable before the Workflow call. The backend owns authorization and confirmation; creating an empty variable does not prepare the note.

Create **Record WooCommerce review request** as **POST** to `/wp-json/wc/v3/orders/` plus the permitted **order_id** and `/notes`. Use the write Secret, JSON content type and raw `{payload}`. Populate **woocommerce_confirmed_payload** with the backend-prepared, confirmed note. Call the saved API request from the authorized Workflow path, with all three inputs provided.

| Request field | Value |
| --- | --- |
| Method | `POST` |
| URL | `https://YOUR_STORE/wp-json/wc/v3/orders/{order_id}/notes` |
| Header: Authorization | `{authorization}` |
| Header: Accept | `application/json` |
| Header: Content-Type | `application/json` |
| Body mode | `Raw → JSON` |
| Body | `{payload}` |

Private WooCommerce review-note Workflow with provided API inputs — Keep a merchant-review note private and tied to the permitted order.

#### Developer

For this Code path, the authenticated backend must enforce order access, merchant eligibility and explicit confirmation **before** calling execute. Preparing JSON or running a saved request does not enforce those checks. Verify the created note ID, private flag and saved note before reporting success.

Download [woocommerce-note.json](/examples/ecommerce/providers/woocommerce-note.json) as `tool.json`. Replace the fictional store origin or site GUID where present. Create a separate saved request for this operation; use its returned `apiTool.id` as `API_TOOL_ID`.

Save the complete confirmed body above as `confirmed-body.json`. Download [prepare-commerce-payload.mjs](/examples/ecommerce/prepare-commerce-payload.mjs) beside it. Your backend uses its `stringifyToolJSON` helper to preserve JSON and literal brace text; it does not perform authorization. For this controlled test:

```sh
node prepare-commerce-payload.mjs confirmed-write woocommerce_write_authorization 727 < confirmed-body.json > inputs.json
```

#### API

### 1. Create the saved API request

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/api-tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @tool.json
```

Retain `apiTool.id` as `API_TOOL_ID`. Resolve any `unresolvedReferences`. Inspect its inputs with the [API-tool schema](/docs/cli/commands/api-tool/get-schema) before execution.

### 2. Run the saved request once

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/api-tool/$API_TOOL_ID/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @inputs.json
```

#### CLI

### 1. Create the saved API request

```sh
vf api-tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --output-format json < tool.json
```

Retain `apiTool.id` as `API_TOOL_ID` and resolve `unresolvedReferences`.

### 2. Inspect and execute it

```sh
vf api-tool get-schema --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$API_TOOL_ID" --output-format json

vf api-tool execute --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$API_TOOL_ID" --output-format json < inputs.json
```

Require `success: true`, `error: null` and `truncated: false`, then inspect `output.status` and `output.body`. A Voiceflow HTTP 200 alone is not provider success.

Require HTTP 201, retain the returned note `id` and verify `customer_note: false` in `output.body` and WooCommerce. Setting this flag true exposes/notifies the customer. An ambiguous POST can create duplicate notes; inspect the order’s existing notes before retrying. See [Order notes](https://developer.woocommerce.com/docs/apis/rest-api/v3/order-notes/).

<a id="cancelling-orders"></a>

## Cancelling orders

Change an eligible order’s status with explicit merchant approval.

First [read the authorized order](#looking-up-orders) to prepare its provided input and verify the current record.

Before a write, the merchant supplies a separate Read/Write key. Store its complete Basic value as **woocommerce_write_authorization** using the [Secret setup](#prepare-the-merchant-credential), with the intended Draft/Published values. Your application authorizes the order and confirms merchant eligibility before the Workflow executes.

Setting **`status: "cancelled"`** returns managed stock where inventory management applies and can still require a separate refund. Confirm cancellation with the customer, check current fulfillment and merchant policy, and keep refund handling with the merchant. Review **WooCommerce → Settings → Emails** and installed notification extensions before testing: a status change can trigger configured cancellation notifications. This request has no email-suppression flag. See [WooCommerce email settings](https://woocommerce.com/document/configuring-woocommerce-settings/emails/).

### 1. Run the confirmed cancellation

#### Studio

Create **Cancel confirmed WooCommerce order** as **PUT** to the permitted order URL, with the write Secret, JSON content type and fixed body `{"status":"cancelled"}`. Place its API call step only on the confirmed, authorized Workflow path. Bind the permitted ID and credential as provided values. Run once with a dedicated test order.

| Request field | Value |
| --- | --- |
| Method | `PUT` |
| URL | `https://YOUR_STORE/wp-json/wc/v3/orders/{order_id}` |
| Header: Authorization | `{authorization}` |
| Header: Accept | `application/json` |
| Header: Content-Type | `application/json` |
| Body mode | `Raw → JSON` |
| Body | `{"status":"cancelled"}` |

Confirmed WooCommerce cancellation Workflow with the authorized order input — Cancel only after authorization, merchant checks and explicit confirmation.

#### Developer

For this Code path, the authenticated backend must enforce order access, merchant eligibility and explicit confirmation **before** calling execute. Preparing JSON or running a saved request does not enforce those checks. Re-read the order before reporting success.

Download [woocommerce-cancel.json](/examples/ecommerce/providers/woocommerce-cancel.json) as `tool.json`. Replace the fictional store origin or site GUID where present. Create a separate saved request for this operation; use its returned `apiTool.id` as `API_TOOL_ID`.

Save these standalone test values as `inputs.json`, replacing fictional IDs with your permitted test records:

```json
{
  "inputs": {
    "authorization": "{woocommerce_write_authorization}",
    "order_id": "727"
  }
}
```

#### API

### 1. Create the saved API request

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/api-tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @tool.json
```

Retain `apiTool.id` as `API_TOOL_ID`. Resolve any `unresolvedReferences`. Inspect its inputs with the [API-tool schema](/docs/cli/commands/api-tool/get-schema) before execution.

### 2. Run the saved request once

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/api-tool/$API_TOOL_ID/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @inputs.json
```

#### CLI

### 1. Create the saved API request

```sh
vf api-tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --output-format json < tool.json
```

Retain `apiTool.id` as `API_TOOL_ID` and resolve `unresolvedReferences`.

### 2. Inspect and execute it

```sh
vf api-tool get-schema --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$API_TOOL_ID" --output-format json

vf api-tool execute --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$API_TOOL_ID" --output-format json < inputs.json
```

Require `success: true`, `error: null` and `truncated: false`, then inspect `output.status` and `output.body`. A Voiceflow HTTP 200 alone is not provider success.

### 2. Verify cancellation and payment separately

Require HTTP 200, the correct returned `id` and `status: "cancelled"`, then re-read the same order. Inspect the separate payment/refund outcome before reporting money returned. Manually setting an order to `refunded` is not proof that funds moved.

See [WooCommerce order-status behavior](https://woocommerce.com/document/managing-orders/order-statuses/). An unknown outcome needs investigation before retrying; keep a rejected or raced change on the merchant support path.

<a id="create-shopping-links"></a>

## Create shopping links

Offer the selected product or an approved add-to-cart link for buyer review.

The simplest next action is the returned product `permalink`. For a confirmed option, WooCommerce also supports [add-to-cart URLs](https://woocommerce.com/document/quick-guide-to-woocommerce-add-to-cart-urls/) using the selected variation ID. Generating a URL makes no cart or payment request; **opening it adds to the buyer’s browser cart**, and repeated clicks can add again.

### 1. Prepare the merchant-approved selection map

Download [build-woocommerce-link.mjs](/examples/ecommerce/build-woocommerce-link.mjs). Replace the fictional store origin and selection IDs with merchant-approved simple-product or variation IDs. Re-read the selected public product/variation and confirm its options and quantity before calling the Function.

### 2. Create and test the Function

#### Studio

In **Tools**, create **Build WooCommerce shopping link**, paste the edited source and declare string inputs **selection_key**, **quantity** and outputs **shopping_url**, **result**. Save and test an approved key/quantity and an unknown key. Attach through **Agent → Global tools → + → Function** only for confirmed selections.

Shopping-link Function with confirmed selection and quantity inputs — Pass an approved selection key and the customer-confirmed quantity.

#### Developer

Use the [Voiceflow API variables](#voiceflow-api-setup) for this Function. Generating a link does not require the store connector’s credentials.

Save the edited [build-woocommerce-link.mjs](/examples/ecommerce/build-woocommerce-link.mjs) and [create-function.mjs](/examples/ecommerce/create-function.mjs) in one directory. With Node 22+ and the Voiceflow variables from [Connecting WooCommerce](#connecting-woocommerce), create the Function and its declared input/output variables:

```sh
node create-function.mjs build-woocommerce-link > created-function.json
export FUNCTION_ID="$(node -p "JSON.parse(require('fs').readFileSync('created-function.json','utf8')).functionID")"
```

The helper creates saved Draft resources; it does not attach or publish them. Creation is not idempotent: inspect the project before rerunning after failure. Execute the actual returned ID:

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/function/$FUNCTION_ID/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data '{"inputs":{"selection_key":"trail-blue-small","quantity":"2"}}'
```

Require `success: true`, `error: null`, `truncated: false`, `output.outputVars.result: "link_ready"` and a nonempty `shopping_url`. For agent invocation, attach the saved Function through [Create tool](/docs/cli/commands/tool/create), bind its confirmed selection inputs, then compile and test Draft routing separately.

### 3. Check the buyer’s cart

Open the actual test link and verify the selected variation, quantity and store destination. The sample uses quantities 1–5 as a merchant rule. The shopper reviews actual availability, taxes and totals and completes checkout in the store. Use the product page when the mapping or availability cannot be confirmed.

### WooCommerce shopping-link Function source

Copy the complete implementation after replacing its fictional merchant settings.

```javascript
// Fictional merchant configuration: replace before saving this Voiceflow Function.
const STORE_ORIGIN = 'https://northstar.example';
const SELECTIONS = {
  // Use the selected variation ID for a variable product, not its parent ID.
  'trail-blue-small': '481',
  'trail-blue-medium': '482',
};

export default async function main(args) {
  const {selection_key, quantity} = args.inputVars;
  const id = Object.hasOwn(SELECTIONS, selection_key) ? SELECTIONS[selection_key] : null;
  // One to five is an illustrative merchant rule, not a WooCommerce limit.
  if (!id || !/^[1-5]$/.test(quantity)) {
    return {outputVars: {shopping_url: '', result: 'needs_selection'}};
  }
  const url = new URL('/', STORE_ORIGIN);
  url.searchParams.set('add-to-cart', id);
  url.searchParams.set('quantity', quantity);
  return {outputVars: {shopping_url: url.href, result: 'link_ready'}};
}
```

<a id="product-and-policy-knowledge"></a>

## Answer product and policy questions

Import approved content and verify the source used by the agent.

Use Knowledge for approved public product descriptions and policies. These imports are indexed snapshots; they do not establish current variant prices, stock or a customer’s order state. The WooCommerce API credential does not configure this source.

#### Studio

### 1. Import approved public pages

In [Agent studio](https://creator.voiceflow.com), open the intended project, then **Build → Knowledge base → Add data source → Web page(s)**. Paste merchant-approved public product or policy URLs, choose a supported refresh schedule and import.

Native public-page importer with an approved policy URL — Import approved public content separately from live order tools.

### 2. Check the processed source and answer

Wait for processing, open a document and compare its text with the approved page. In **Agent**, enable Knowledge and ask an answerable policy question, then an unsupported question. Check the source and fallback.

#### Developer

Prepare the [Voiceflow API variables](#voiceflow-api-setup), then import one approved public page. This URL import does not require the store’s API credential:

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/document/url?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data '{"url":"https://northstar.example/policies/returns","refreshRate":"weekly"}'
```

Retain `document.id` as `DOCUMENT_ID` and wait for processing:

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/document/$DOCUMENT_ID?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN"
```

Require `document.status.type: "SUCCESS"`; inspect `ERROR` rather than treating submission as completion. Query the intended policy:

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/knowledge-base/query?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data '{"version":"draft","question":"What should I do if my item arrived damaged?","synthesis":false,"chunkLimit":3}'
```

Compare `answer.chunks[].documentID`, `source` and `content` with the approved page. `answer.output` is null with synthesis disabled. Also [run a Draft conversation](/docs/cli/commands/conversation/send) to test the actual answer and fallback.

Use **Docs** or [text import](/docs/guides/integrations/commerce/answer-product-and-policy-questions) for approved text without a public URL. Keep private order pages out of the general-answer collection.

### Maintain the approved content

Refresh changed pages and remove obsolete answers before rollout.

Choose `daily`, `weekly`, `monthly` or `never` refresh as the workspace allows. Review the existing document before replacing it: URLs and file names are unique across Knowledge. Re-import/update that source, wait for processing and repeat the answer tests; remove withdrawn products and superseded policies. Follow the [document lifecycle](/docs/documentation/build/importing-data-sources) for updates, refresh and removal. Check the intended Draft/release separately from the store API connection.

<a id="assess-return-requests"></a>

## Assess return requests

Apply a merchant policy and route the result for review.

Use the existing [return-assessment workflow](/docs/guides/integrations/commerce/assess-a-return-request) with your approved policy. An assessment does not authorize a return, create a label or issue a refund.

| Input | Producer |
| --- | --- |
| Permitted order and final-sale status | Authenticated application and merchant records |
| Actual delivery timestamp | Trusted fulfillment source; order creation/completion is insufficient |
| Request time | Application-recorded timestamp |
| Condition and original packaging | Customer confirmation |

#### Studio

Create the Guide’s **Assess return request** Function in **Tools**, declare its five inputs and two outputs, then use a [Function step](/docs/documentation/build/steps/function) in a Workflow. Map trusted values and save **decision** and **reason** into conversation variables before routing.

Native Function step with verified return inputs and saved outputs — Assess the approved policy with trusted fulfillment data.

#### Developer

Create and execute the Guide’s downloadable Function with the same project/Environment as this manual. Read `output.outputVars.decision` and `reason`; the Guide supplies complete creation and standalone calls. Test missing data and the policy boundary before routing a customer request.

Route `eligible_for_review` for merchant authorization, `needs_review` for support investigation, and explain `outside_policy` with its reason. Pass only permitted context to [support](/docs/guides/integrations/help-desks/create-and-route-support-requests).

<a id="add-agent-to-store"></a>

## Add the agent to your store

Install the generated Widget snippet and verify the customer journey.

For private order questions, first complete [Looking up orders](#looking-up-orders) and connect its application-owned identity/input producer to this customer channel. The installation snippet alone does not establish the customer’s order access.

Use an editable chat project, an approved published production version and a merchant-authorized test storefront. Tool credentials belong in Voiceflow Secrets or your backend, never in the Widget snippet.

### 1. Copy this project’s generated snippet

In [Agent studio](https://creator.voiceflow.com), open the project, then **Widget → Installation**. Copy the complete current snippet, including generated verification settings. See [Widget installation](/docs/documentation/deploy/widget/embedding-the-chat-widget).

Native Widget Installation code card — Copy the generated Widget snippet for the project you will deploy.

### 2. Install it in the intended storefront

This path assumes a WordPress store where the merchant can install a site plugin and the active theme calls [wp_footer](https://developer.wordpress.org/reference/hooks/wp_footer/).

1. Give the WordPress developer the complete generated snippet and [voiceflow-wordpress-widget.php](/examples/ecommerce/voiceflow-wordpress-widget.php). The developer replaces its marked comment with that snippet, packages the file inside a `voiceflow-widget` folder as a ZIP and supplies the reviewed ZIP to the merchant.
2. In WordPress, the authorized merchant opens **Plugins → Add New Plugin → Upload Plugin**, chooses the ZIP, installs it and activates it. Follow [WordPress plugin installation](https://wordpress.org/documentation/article/manage-plugins/) for the current controls and hosting permissions.
3. Have the developer confirm which templates call the hook and where the plugin is installed. Verify the actual product, cart and checkout pages; a missing theme hook needs the developer’s approved installation point.

The template contains no Widget until the developer inserts the project-specific snippet. Keep provider keys out of it. This is a site deployment mechanism, separate from the WooCommerce API connection.

### 3. Verify in a fresh customer session

Open the actual storefront in a fresh logged-out/test session. Check desktop/mobile, navigation between pages, a read-only product question and your authenticated order path. A visible launcher or successful standalone request does not verify the whole customer journey. Remove duplicate installations and publish only the version approved for the store.
