> ## 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.

# Wix Stores integration

> Connect Voiceflow to Wix Stores so your agent can find products, read a permitted order and its fulfillment records, and apply confirmed merchant-approved changes.

## Overview

Connect Voiceflow to Wix Stores so your agent can find products, read a permitted order and its fulfillment records, and apply confirmed merchant-approved changes. Use API tools for live records and Knowledge for approved public product and policy answers.

- **[Find a product](#finding-products)** — use the site’s actual catalog version and inspect selected options.
- **[Check an order and tracking](#looking-up-orders)** — read the GUID authorized by your application.
- **[Correct a shipping destination](#updating-orders)** or **[cancel an eligible order](#cancelling-orders)** — confirm the exact action and verify the saved result.
- **[Answer policies](#product-and-policy-knowledge)** and **[review a return request](#assess-return-requests)** — use approved content and trusted fulfillment data.

The merchant’s API key authorizes administrative site access. Your application must separately establish which customer and order the agent may access.

<a id="connecting-wix-stores"></a>

## Connecting Wix Stores

Authorize the intended site and detect its catalog version.

Use a dedicated test site/project. This walkthrough is for a merchant operating their own site with an API key; a distributed Wix app has a separate OAuth authorization flow.

### Prepare the site key

### 1. Create the site-restricted key

The Wix account owner/co-owner opens **API Keys Manager**, generates a key and restricts it to the intended site and operations. Obtain the site GUID from the dashboard URL after `/dashboard/`. Follow [Wix API-key setup](https://dev.wix.com/docs/go-headless/authentication/admin/generate-an-api-key).

### 2. Select the permissions needed for this journey

For catalog detection choose **Read v3 catalog (PII)** (`SCOPE.STORES.CATALOG_READ_LIMITED`). Add **Read Products** for V1 or **Read products in v3 catalog** for V3, and **Read Orders** for order/fulfillment reads. Use a separate **Manage Orders** key for confirmed writes. The merchant must approve those privileges before configuring each path.

| Header | Value |
| --- | --- |
| `Authorization` | Raw API key through the local **authorization** input; no Bearer prefix. |
| `wix-site-id` | Fixed merchant-approved site GUID. |
| `Content-Type` | `application/json` for JSON requests. |

These are [site-level API-key headers](https://dev.wix.com/docs/develop-websites-sdk/code-your-site/authorization/make-rest-api-calls-with-an-api-key); omit `wix-account-id` for these requests.

#### 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 **wix_api_key**. Creating the default also writes Main’s Published value, so start in the dedicated test project and set the intended Draft override.

Create API requests through **Agent → Global tools → + → API call**. The **authorization** input gets the Secret as a provided value; the site header stays fixed in the request.

#### 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 `WIX_API_KEY` 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='wix_api_key'
jq -n --arg name "$SECRET_NAME" --arg value "$WIX_API_KEY" \
  '{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 "$WIX_API_KEY" --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='wix_api_key'
jq -n --arg name "$SECRET_NAME" --arg value "$WIX_API_KEY" \
  '{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 "$WIX_API_KEY" --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.

### Verify the site catalog

#### Studio

In **Tools → Create tool → API call**, create **Check Wix catalog version**:

| Request field | Value |
| --- | --- |
| Method | `GET` |
| URL | `https://www.wixapis.com/stores/v3/provision/version` |
| Header: Authorization | `{authorization}` |
| Header: wix-site-id | `YOUR_WIX_SITE_GUID` |
| Header: Content-Type | `application/json` |

Choose **Run**, supply **authorization** from Secret **wix_api_key** and verify the intended site. This is a setup check; keep it off the agent’s Global tools.

#### Developer

Download [wix-catalog-version.json](/examples/ecommerce/providers/wix-catalog-version.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": "{wix_api_key}"
  }
}
```

#### 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.

Read `catalogVersion` (in Code, `output.body.catalogVersion`): **V1_CATALOG** and **V3_CATALOG** require different product requests below. **STORES_NOT_INSTALLED** stops this store workflow. Check the [catalog-version contract](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-versioning/get-catalog-version).

### Repair site access or rotate the key

Check the owning account, site header, permissions and runtime Secret value.

A 401/403 or unexpected site needs inspection of the account owning the key, its allowed sites/scopes and the fixed site GUID. Rotate/revoke in Wix, update the appropriate Voiceflow Secret default and Draft/Published values, then repeat known catalog/order reads. Changing an Environment does not change a fixed site header. Deleting a Voiceflow request is not key revocation or Knowledge removal.

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

## Finding products

Use the installed catalog version and verify selected-product facts.

Complete [Connecting Wix Stores](#connecting-wix-stores) first to verify the site and prepare its read credential.

Detect the [catalog version](#verify-the-site-catalog) first. V1 uses a JSON-string filter; V3 uses a nested search object. The worked example finds three visible shirt candidates and keeps hidden/merchant-only information out of the answer.

### Prepare the product query

Have your implementing developer use [prepare-commerce-payload.mjs](/examples/ecommerce/prepare-commerce-payload.mjs), calling `wixProductSearch(catalogVersion, query)`. It returns the complete serialized request as **payload**, preserves quotes/literal brace text and rejects a missing catalog version. Its 100-character query rule and three-candidate limit are illustrative merchant choices.

In Studio, create **wix_catalog_payload** in **More → Variables** with an empty default. The application prepares and supplies it before the tool runs. Bind the API tool’s **payload** input to that provided variable rather than asking the model to write a raw JSON request. Code prepares the same payload locally below.

### Search the installed catalog

#### V1 catalog

Use **POST** `https://www.wixapis.com/stores-reader/v1/products/query`, with **Read Products** permission. The prepared body has this shape:

```json
{
  "includeHiddenProducts": false,
  "includeMerchantSpecificData": false,
  "includeVariants": true,
  "query": {
    "filter": "{\"name\":{\"$contains\":\"shirt\"}}",
    "paging": {
      "limit": 3,
      "offset": 0
    }
  }
}
```

#### Studio

Create **Find Wix V1 products** with the site/authorization headers and a raw JSON body containing `{payload}`. Bind **authorization** to **wix_api_key** and **payload** to **wix_catalog_payload** as provided values, then run a shirt question.

| Request field | Value |
| --- | --- |
| Method | `POST` |
| URL | `https://www.wixapis.com/stores-reader/v1/products/query` |
| Header: Authorization | `{authorization}` |
| Header: wix-site-id | `YOUR_WIX_SITE_GUID` |
| Header: Content-Type | `application/json` |
| Body mode | `Raw → JSON` |
| Body | `{payload}` |

Wix V1 product request with site headers and a prepared JSON payload — Use the V1 endpoint and backend-prepared JSON-string filter.

#### Developer

Download [wix-products-v1.json](/examples/ecommerce/providers/wix-products-v1.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`.

Download the payload helper beside this definition and prepare `inputs.json`:

```sh
node prepare-commerce-payload.mjs wix-search V1_CATALOG shirt > 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` 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.

Read `products[]` (Code: `output.body.products`). Compare `name`, `priceData.currency`, `discountedPrice`, any `priceRange`, returned variations and `productPageUrl.base` + `path`. Preserve a range as a range and inspect variant stock before a selected-option claim. Use `totalResults`/paging to recognize an incomplete candidate set. See [V1 Query Products](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v1/catalog/query-products).

#### V3 catalog

Use **POST** `https://www.wixapis.com/stores/v3/products/search`, with **Read products in v3 catalog** permission. Name/free-text search uses **Search Products**; Query Products has a different filter contract. The prepared body is:

```json
{
  "search": {
    "search": {
      "expression": "shirt",
      "fields": [
        "name"
      ],
      "mode": "AND"
    },
    "filter": {
      "visible": {
        "$eq": true
      }
    },
    "cursorPaging": {
      "limit": 3
    }
  },
  "fields": [
    "URL",
    "CURRENCY",
    "PLAIN_DESCRIPTION"
  ]
}
```

#### Studio

Create **Find Wix V3 products** with the site/authorization headers and raw `{payload}` JSON body. Bind **authorization** to **wix_api_key** and **payload** to **wix_catalog_payload** as provided values, then run a shirt question.

| Request field | Value |
| --- | --- |
| Method | `POST` |
| URL | `https://www.wixapis.com/stores/v3/products/search` |
| Header: Authorization | `{authorization}` |
| Header: wix-site-id | `YOUR_WIX_SITE_GUID` |
| Header: Content-Type | `application/json` |
| Body mode | `Raw → JSON` |
| Body | `{payload}` |

Wix V3 product search request with site headers and a prepared JSON payload — Use V3 Search Products with the required returned fields.

#### Developer

Download [wix-products-v3.json](/examples/ecommerce/providers/wix-products-v3.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`.

Download the payload helper beside this definition and prepare `inputs.json`:

```sh
node prepare-commerce-payload.mjs wix-search V3_CATALOG shirt > 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` 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.

Read `products[]` and `pagingMetadata.hasNext`/`cursors.next`. The requested fields supply `currency`, `url.url` and `plainDescription`; the latter contains HTML. `actualPriceRange` spans variants.

Search results omit variants. Re-read the selected product before making an option-specific claim.

#### Studio

Create **Read selected Wix V3 product** as a separate request, using an ID from the search result:

| Request field | Value |
| --- | --- |
| Method | `GET` |
| URL | `https://www.wixapis.com/stores/v3/products/{product_id}` |
| Header: Authorization | `{authorization}` |
| Header: wix-site-id | `YOUR_WIX_SITE_GUID` |
| Header: Content-Type | `application/json` |

#### Developer

Download [wix-product-v3.json](/examples/ecommerce/providers/wix-product-v3.json) as `tool.json`. Save `{"inputs":{"authorization":"{wix_api_key}","product_id":"RETURNED_SELECTED_ID"}}` as `inputs.json`, replacing the selected ID with one returned by search. Repeat the create/schema/execute calls above with these files. Save the created ID as `SELECTED_PRODUCT_TOOL_ID` before reusing `API_TOOL_ID`; keep the search request’s `PRODUCT_TOOL_ID` unchanged.

Inspect `product.variantsInfo.variants` before an option-specific price or availability claim. See [V3 Search Products](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/search-products) and [Get Product](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/get-product).

### Let the agent use the product read

#### Studio

### 1. Prepare the current query

Reuse **wix_catalog_payload**, created before the search. Have your developer call the downloadable `wixProductSearch` helper with the detected V1/V3 catalog and the shopper’s query.

The backend sends `variables: {"wix_catalog_payload": PREPARED_JSON_STRING}` on the [conversation action](/docs/api-reference/v4interact/interact-non-stream#streaming-action) before the product call. For the builder test, have the developer seed the helper’s `shirt` payload.

### 2. Provide the inputs

Attach only the product request matching the site’s catalog version. Open each input’s **Default value** and select:

| Tool input | Provided value |
| --- | --- |
| **authorization** | Secret **wix_api_key** |
| **payload** | Variable **wix_catalog_payload** |

Keep both inputs enabled and check **Value provided**. Set the **Trigger** to use the prepared catalog query.

### 3. Test a search and a refinement

Inspect the first call and its candidates. Change the shopper’s query, have the backend replace the payload, then confirm the second call uses the new query. The agent cannot rewrite this provided input. If preparation fails, stop the catalog call instead of reusing the previous payload.

#### Developer

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

Create the prepared-payload variable with an empty default:

```sh
jq -n --arg name 'wix_catalog_payload' \
  '{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 @-
```

Your implementing backend calls the supplied `wixProductSearch` helper with the verified catalog generation and query. It supplies `variables: {"wix_catalog_payload": PREPARED_JSON_STRING}` on the first [conversation action](/docs/api-reference/v4interact/interact-non-stream#streaming-action), before the agent can call the product request. For the worked test use `shirt` and the actual V1/V3 generation. Confirm the session variable is populated; an empty variable definition is not a prepared query. Before each relevant follow-up query, rebuild and replace the variable on that conversation action. The agent cannot modify a provided input. If preparation rejects an empty/invalid query, stop the catalog call and ask for a valid requirement; do not reuse a stale payload.

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": {
    "authorization": {
      "apiToolInputVariableID": "AUTH_INPUT_ID",
      "required": false,
      "defaultValue": "{wix_api_key}"
    },
    "payload": {
      "apiToolInputVariableID": "PAYLOAD_INPUT_ID",
      "required": false,
      "defaultValue": "{wix_catalog_payload}"
    }
  }
}
```

#### 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. Then change the shopper query, replace the prepared variable and verify a different payload is sent. Test empty results, an unmet requirement and failed preparation too. Standalone execution alone does not verify agent routing.

### Recheck the selected V3 product

For V3, the separate Get Product request must also be available to the agent. V1 uses the variants returned by its configured query.

#### Studio

Attach **Read selected Wix V3 product** in **Agent → Global tools**. Bind **authorization** to **wix_api_key** as a provided value; let the agent supply **product_id** from a V3 search result. Test an option-specific question and inspect the second call and `product.variantsInfo.variants` before the recommendation.

#### 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": "Read the returned Wix V3 product ID before an option-specific price or availability claim.",
  "inputVariables": {
    "authorization": {
      "apiToolInputVariableID": "AUTHORIZATION_INPUT_ID",
      "required": false,
      "defaultValue": "{wix_api_key}"
    },
    "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 inspect the second call and `product.variantsInfo.variants` before the recommendation.

Return the verified storefront product URL so the buyer can select options, check current availability and finish checkout. A candidate result or generated URL does not reserve inventory. [Help shoppers choose products](/docs/guides/integrations/commerce/help-shoppers-choose-products) owns the full comparison journey.

### The product query fails or misses an option

Check catalog generation, filter encoding, permissions and the selected-product response.

Confirm V1 versus V3 using the actual site probe. In V1, `query.filter` must be a JSON string; in V3 the search/filter objects and selected fields differ. Inspect 400/403 responses and hidden-product rules. Re-read the selected product before recommending its option; the first three candidates are not the whole catalog.

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

## Looking up orders and tracking

Read the permitted order and its separately recorded fulfillments.

First complete [Connecting Wix Stores](#connecting-wix-stores) to prepare the read credential for this store.

The application authenticates the customer and resolves the permitted **order GUID** and buyer association. The visible order number is not that API ID. Keep this mapping application-owned; the administrative key does not enforce the shopper’s ownership.

### 1. Prepare the authorized order input

#### Studio

In **More → Variables**, create **wix_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: {"wix_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 'wix_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: {"wix_order_id":"VERIFIED_ORDER_API_ID"}`. An unchecked browser value is not an authorization mapping.

### 2. Read the permitted order

#### Studio

Create **Read permitted Wix order** as **GET** `https://www.wixapis.com/ecom/v1/orders/` plus provided **order_id**. Use **Read Orders** and the fixed site header. Bind **authorization** to the Secret and **order_id** to **wix_order_id**, then choose **Run** in the request editor with a permitted test order ID and the read Secret. This checks the request before the agent-routing test below.

| Request field | Value |
| --- | --- |
| Method | `GET` |
| URL | `https://www.wixapis.com/ecom/v1/orders/{order_id}` |
| Header: Authorization | `{authorization}` |
| Header: wix-site-id | `YOUR_WIX_SITE_GUID` |
| Header: Content-Type | `application/json` |

#### Developer

Download [wix-order.json](/examples/ecommerce/providers/wix-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": "{wix_api_key}",
    "order_id": "265c7d98-a7c3-48c4-89cd-bbdc00921eab"
  }
}
```

#### 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 identity and returned order

Require HTTP 200 and `order.id` matching the authorized GUID; Code reads `output.body.order`. Verify the buyer association before returning relevant line items, currency or recorded statuses. Keep billing/contact data and internal fields private.

### 4. Read the order’s fulfillment records

#### Studio

Create **Read permitted Wix fulfillments** with **Read Orders** permission and the same authorized order input:

| Request field | Value |
| --- | --- |
| Method | `GET` |
| URL | `https://www.wixapis.com/ecom/v1/fulfillments/orders/{order_id}` |
| Header: Authorization | `{authorization}` |
| Header: wix-site-id | `YOUR_WIX_SITE_GUID` |
| Header: Content-Type | `application/json` |

Inspect the returned order ID before sharing tracking.

#### Developer

Download [wix-fulfillments.json](/examples/ecommerce/providers/wix-fulfillments.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": "{wix_api_key}",
    "order_id": "265c7d98-a7c3-48c4-89cd-bbdc00921eab"
  }
}
```

#### 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 `FULFILLMENTS_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 `FULFILLMENTS_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.

### Make the permitted order read available to the agent

Use the order request you just tested. In Code, use its saved `ORDER_TOOL_ID` and the input IDs belonging to that request:

#### Studio

### 1. Provide the credential and order ID

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

| Tool input | Provided value |
| --- | --- |
| **authorization** | Secret **wix_api_key** |
| **order_id** | Variable **wix_order_id** |

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

Wix API tool with the site key bound to a named Secret — Bind the Wix key and the application-authorized order GUID.

Wix API tool with the application-provided order GUID — Read the order GUID established by the authenticated application.

### 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 Wix order authorized by the signed-in application when the customer asks about that order.",
  "inputVariables": {
    "authorization": {
      "apiToolInputVariableID": "AUTH_INPUT_ID",
      "required": false,
      "defaultValue": "{wix_api_key}"
    },
    "order_id": {
      "apiToolInputVariableID": "ORDER_INPUT_ID",
      "required": false,
      "defaultValue": "{wix_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.

### Make the fulfillment read available

The order read and fulfillment read are separate API resources.

#### Studio

Attach **Read permitted Wix fulfillments** in **Agent → Global tools**. Bind **authorization** to **wix_api_key** and **order_id** to the same provided **wix_order_id** used for the order read. Keep both out of model collection. Ask for tracking in a Draft conversation and inspect that the fulfillment tool receives the authorized GUID. Test an order with multiple fulfillments and one with none; do not invent a carrier event.

#### Developer

Use `FULFILLMENTS_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 `FULFILLMENTS_TOOL_ID`; use this request's actual `variables[].id` values. Save this body as `additional-attachment.json`:

```json
{
  "type": "api",
  "apiToolID": "FULFILLMENTS_TOOL_ID",
  "target": {
    "global": true
  },
  "description": "Read recorded fulfillments when the customer asks about tracking for the application-authorized Wix order.",
  "inputVariables": {
    "authorization": {
      "apiToolInputVariableID": "AUTHORIZATION_INPUT_ID",
      "required": false,
      "defaultValue": "{wix_api_key}"
    },
    "order_id": {
      "apiToolInputVariableID": "ORDER_ID_INPUT_ID",
      "required": false,
      "defaultValue": "{wix_order_id}"
    }
  }
}
```

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. Ask for tracking in a Draft conversation and inspect that the fulfillment tool receives the authorized GUID. Test an order with multiple fulfillments and one with none; do not invent a carrier event.

| Result | Interpretation |
| --- | --- |
| `orderWithFulfillments.orderId` | Must match the permitted order. In Code, read it under `output.body`. |
| `fulfillments[].trackingInfo` | Use the returned `trackingNumber`, `shippingProvider` and `trackingLink` for that shipment. |
| `FULFILLED` order with an empty fulfillment list | Can result from manual fulfillment; not evidence of a missing parcel or carrier delivery. |

Fulfillment creation time/informational status is not independent delivery telemetry. For payment/refund questions, use the actual merchant transaction outcome; cancellation alone is insufficient. See [Get Order](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/get-order) and [fulfillment records](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-fulfillments/list-fulfillments-for-single-order).

Test a permitted order, missing order and wrong buyer/returned ID. Stop disclosure on association failure and use the [support-request path](/docs/guides/integrations/help-desks/create-and-route-support-requests).

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

## Updating a shipping destination

Apply the customer-confirmed destination and verify the saved order.

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

The merchant provisions a separate key with **Manage Orders**, restricted to this site. Store it as **wix_write_api_key** using the [credential setup](#prepare-the-site-key) and the intended Draft/Published values. The application authorizes the order and checks merchant eligibility before the confirmed Workflow path runs.

Update **shippingInfo.logistics.shippingDestination** for the shipping address. Changing only **recipientInfo** changes recipient details, not the shipping destination. A destination change can also update recipient details unless they were independently set.

### 1. Confirm the complete destination

Read the current permitted order, preserve unchanged address/contact fields and confirm the intended correction. This fictional JSON follows the provider’s shipping-destination structure:

```json
{
  "order": {
    "shippingInfo": {
      "logistics": {
        "shippingDestination": {
          "address": {
            "country": "CA",
            "subdivision": "CA-ON",
            "city": "Toronto",
            "postalCode": "M5V 2T6",
            "addressLine": "123 Example Street",
            "addressLine2": ""
          },
          "contactDetails": {
            "firstName": "Maya",
            "lastName": "Chen"
          }
        }
      }
    }
  }
}
```

### 2. Apply the bounded update

#### Studio

Create **Update confirmed Wix shipping destination** as **PATCH** `https://www.wixapis.com/ecom/v1/orders/` plus the permitted **order_id**. Use the fixed site header, write Secret and raw `{payload}` JSON. Create **wix_confirmed_payload** with an empty default and have the application populate it using `stringifyToolJSON` from [prepare-commerce-payload.mjs](/examples/ecommerce/prepare-commerce-payload.mjs).

In the confirmed Workflow path, add the saved **API call** tool. Provide the write credential, authorized order ID and confirmed payload; keep the mutation off unconfirmed Global tools.

| Request field | Value |
| --- | --- |
| Method | `PATCH` |
| URL | `https://www.wixapis.com/ecom/v1/orders/{order_id}` |
| Header: Authorization | `{authorization}` |
| Header: wix-site-id | `YOUR_WIX_SITE_GUID` |
| Header: Content-Type | `application/json` |
| Body mode | `Raw → JSON` |
| Body | `{payload}` |

Confirmed Wix shipping-destination Workflow with provided API inputs — Map the authorized order and complete confirmed shipping destination.

#### 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 [wix-address.json](/examples/ecommerce/providers/wix-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) and prepare a controlled test with the permitted GUID:

```sh
node prepare-commerce-payload.mjs confirmed-write wix_write_api_key 265c7d98-a7c3-48c4-89cd-bbdc00921eab < 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. Re-read and verify the saved result

Require HTTP 200, the expected `order.id` and destination fields, then GET the same order again. An address change does not establish that an existing shipment was rerouted. Keep a rejected change on the merchant review path.

See [Update Order](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/update-order). Pending or rejected orders can fail preconditions. After an unknown result, inspect the actual saved destination before considering another write.

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

## Cancelling orders

Confirm cancellation, inventory and notification effects before execution.

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

The merchant provisions a separate key with **Manage Orders**, restricted to this site. Store it as **wix_write_api_key** using the [credential setup](#prepare-the-site-key) and the intended Draft/Published values. The application authorizes the order and checks merchant eligibility before the confirmed Workflow path runs.

This worked request sets **restockAllItems: true** and **sendOrderCanceledEmail: false**. Confirm those exact effects and the permitted order with the customer. Cancellation is separate from a refund; the endpoint has no refund parameter.

### 1. Run the confirmed cancellation once

#### Studio

Create **Cancel confirmed Wix order** as **POST** `https://www.wixapis.com/ecom/v1/orders/` plus the provided **order_id** and `/cancel`. Use the write Secret, fixed site header and body `{"restockAllItems":true,"sendOrderCanceledEmail":false}`. Place its API call step on the authorized confirmed Workflow path.

| Request field | Value |
| --- | --- |
| Method | `POST` |
| URL | `https://www.wixapis.com/ecom/v1/orders/{order_id}/cancel` |
| Header: Authorization | `{authorization}` |
| Header: wix-site-id | `YOUR_WIX_SITE_GUID` |
| Header: Content-Type | `application/json` |
| Body mode | `Raw → JSON` |
| Body | `{"restockAllItems":true,"sendOrderCanceledEmail":false}` |

Confirmed Wix cancellation Workflow with the authorized order input — Confirm the fixed restock and notification behavior before cancellation.

#### 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 [wix-cancel.json](/examples/ecommerce/providers/wix-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": "{wix_write_api_key}",
    "order_id": "265c7d98-a7c3-48c4-89cd-bbdc00921eab"
  }
}
```

#### 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. Check the actual order and payment separately

Require the expected `order.id` and `order.status: "CANCELED"` after a successful provider response, then read the same order again. Verify any payment/refund outcome independently before reporting money returned.

| Provider precondition | Next action |
| --- | --- |
| `428 ORDER_HAS_AUTHORIZED_TRANSACTION` | Merchant must resolve the authorized transaction through its payment workflow before cancellation. |
| `428 ORDER_IS_PENDING` or `ORDER_IS_REJECTED` | Stop this cancellation path and route merchant review. |
| Timeout or unknown response | Inspect the order and payments before considering another call; no caller idempotency guarantee was established. |

See [Cancel Order](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/cancel-order). To change restock/email behavior, prepare and test a separate merchant-approved request rather than letting the model invent effects.

<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 Wix Stores 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.

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.

Live product questions in this recipe also need the [prepared-query producer](#prepare-the-product-query) connected to your conversation channel. Your developer must send the current **wix_catalog_payload** on each relevant conversation action. The standard Widget installation snippet does not run the backend helper or provide that per-turn wiring.

Verify that developer-owned path before enabling the product tool in the storefront. Without it, start with approved Knowledge and store-page links; installing the launcher alone does not complete the live catalog journey.

### 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

The merchant opens Wix **Settings → Custom Code → + Add Custom Code**. Paste the complete snippet, name it **Voiceflow widget**, select the intended pages and choose **Body – end**. For a persistent site-wide launcher, choose loading once per visit, then **Apply**. Wix requires a published site with a connected domain for this route. Follow [Wix’s dashboard instructions](https://support.wix.com/en/article/wix-editor-embedding-custom-code-on-your-site).

Use the page-level Custom Code route for the floating launcher. A small HTML Embed iframe confines it to that element. The Widget snippet does not gain Wix administrative API access or authenticated member identity; your application must supply any verified order association separately. See [Custom Code scope](https://dev.wix.com/docs/overview/site-features-tools/about-custom-code).

### 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.
