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

# Squarespace Commerce integration

> Connect Voiceflow to Squarespace Commerce so your agent can compare approved products, read a permitted order and answer from approved product and policy content.

## Overview

Connect Voiceflow to Squarespace Commerce so your agent can compare approved products, read a permitted order and answer from approved product and policy content. API tools provide live reads; Knowledge and the return-assessment Function support policy answers and merchant review.

- **[Help choose a product](#finding-products)** — inspect approved products, variants and their enabled Store Page.
- **[Check an order](#looking-up-orders)** — return the authorized record and available fulfillment information.
- **[Answer policy questions](#product-and-policy-knowledge)** — use approved content with a refresh process.
- **[Assess a return request](#assess-return-requests)** — explain the policy result and route merchant authorization.

The website API key is an administrative credential. Your authenticated application establishes which order the customer may access. A return assessment or read-only result does not authorize a refund or order change.

<a id="connecting-squarespace-commerce"></a>

## Connecting Squarespace Commerce

Authorize the website and verify the read permissions you will use.

Start with an editable test project and a merchant administrator who can generate an API key for the intended website. The administrator must confirm that the website exposes the specific **Products** and **Orders** read permissions; [current plan eligibility](https://support.squarespace.com/hc/en-us/articles/236297987-Squarespace-API-keys) varies by API and plan. Stop if the needed control is absent rather than assuming a key grants all Commerce APIs.

### Prepare the website key

### 1. Generate the read-only key

In the website’s **Developer tools → Developer API Keys**, select **Generate Key**, name it and choose **Products: Read Only** and **Orders: Read Only** for this walkthrough. Select **Next** and copy the key. See [API-key setup](https://support.squarespace.com/hc/en-us/articles/236297987-Squarespace-API-keys) and [authentication](https://developers.squarespace.com/commerce-apis/authentication-and-permissions).

### 2. Keep the request tied to the intended website

Use HTTPS with **Authorization** = `Bearer ` plus the tool-local **token** input, and **User-Agent** = `VoiceflowCommerce/1.0`. The key belongs to one website. Obtain a permitted test order’s API ID and authenticated customer association from your application.

#### 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 **squarespace_token**. Creating the default also writes Main’s Published value; use the dedicated test project and set its intended Draft override.

Create API requests through **Agent → Global tools → + → API call**. Bind **token** to that Secret as a provided value, keeping it out of model collection.

#### 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 `SQUARESPACE_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='squarespace_token'
jq -n --arg name "$SECRET_NAME" --arg value "$SQUARESPACE_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 "$SQUARESPACE_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='squarespace_token'
jq -n --arg name "$SECRET_NAME" --arg value "$SQUARESPACE_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 "$SQUARESPACE_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 website

#### Studio

In **Tools → Create tool → API call**, create **Verify Squarespace website**:

| Request field | Value |
| --- | --- |
| Method | `GET` |
| URL | `https://api.squarespace.com/1.0/authorization/website` |
| Header: Authorization | `Bearer {token}` |
| Header: User-Agent | `VoiceflowCommerce/1.0` |

Choose **Run**, supply **token** from Secret **squarespace_token** and verify the website before configuring product or order tools. Keep this setup check off Global tools.

#### Developer

Download [squarespace-website.json](/examples/ecommerce/providers/squarespace-website.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": {
    "token": "{squarespace_token}"
  }
}
```

#### 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 200 and compare returned **id**, **siteId**, **title**, **url** and **currency** with the intended merchant site. In Code these are under `output.body`; the response is a direct object. Website IDs do not supply product, Store Page or customer order IDs. See [site information](https://developers.squarespace.com/commerce-apis/retrieve-basic-site-info).

### Rotate or revoke website access

Update the runtime Secret and repeat a known read for the intended website.

Generate a replacement key with the same required read permissions, update the relevant Voiceflow Secret default and Draft/Published values, and verify website/product/order reads before revoking the old key. Squarespace’s trash control beside the key revokes it after confirmation. Removing a request or revoking the key does not remove already imported Knowledge; review indexed content separately.

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

## Finding products

Compare approved products and confirm that their Store Page is enabled.

Complete [Connecting Squarespace Commerce](#connecting-squarespace-commerce) first to verify the site and prepare its read credential.

Use current [Products v2](https://developers.squarespace.com/commerce-apis/products). Start from merchant-approved API product IDs; a broad administrative catalog read can include hidden products. A product must have **isVisible: true** and an enabled parent Store Page before this recommendation flow treats it as purchasable.

### Prepare the approved product IDs

The merchant or implementing developer produces the allowed IDs before the agent’s request:

### 1. List products and Store Pages

Create two read-only saved requests for merchant preparation. In Studio use **Tools → Create tool → API call** and **Run**; keep these administrative discovery requests off Global tools.

| Request field | Product list | Store Page list |
| --- | --- | --- |
| Method | `GET` | `GET` |
| URL | `https://api.squarespace.com/v2/commerce/products` | `https://api.squarespace.com/1.0/commerce/store_pages` |
| Authorization header | `Bearer {token}` | `Bearer {token}` |
| User-Agent header | `VoiceflowCommerce/1.0` | `VoiceflowCommerce/1.0` |

Supply **token** from Secret **squarespace_token**. In Code, download [squarespace-product-list.json](/examples/ecommerce/providers/squarespace-product-list.json) as `tool.json` and save `{"inputs":{"token":"{squarespace_token}"}}` as `inputs.json`. Run the create/schema/execute calls below with those files. Then replace `tool.json` with [squarespace-store-pages.json](/examples/ecommerce/providers/squarespace-store-pages.json), repeat with the same token-only inputs and inspect each response separately before proceeding.

### 2. Approve the actual storefront products

Read **products[]** and **storePages[]**, joining **product.storePageId** to **storePage.id**. Approve only visible products on enabled Store Pages and compare their URLs/content with the store. Each list has independent **pagination.hasNextPage**, **nextPageCursor** and **nextPageUrl**; add its returned cursor as a **cursor** query parameter to that list request when another page is needed. Preserve the fixed provider host/headers. Keep the resulting CSV of approved product IDs merchant-owned.

### Read the approved candidates

The exact-product request accepts at most 50 comma-separated API IDs. Use a small approved set for the customer’s question:

#### Studio

Create **Read approved Squarespace products** as **GET** `https://api.squarespace.com/v2/commerce/products/` plus tool input **product_ids**. Add the website Authorization and User-Agent headers. Provide **product_ids** from the merchant’s approved CSV, and **token** from **squarespace_token**. Run a test product question.

| Request field | Value |
| --- | --- |
| Method | `GET` |
| URL | `https://api.squarespace.com/v2/commerce/products/{product_ids}` |
| Header: Authorization | `Bearer {token}` |
| Header: User-Agent | `VoiceflowCommerce/1.0` |

Approved Squarespace product request with Bearer authorization and User-Agent — Read the merchant-approved product IDs from the current Products v2 API.

#### Developer

Download [squarespace-products.json](/examples/ecommerce/providers/squarespace-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": {
    "token": "{squarespace_token}",
    "product_ids": "691300000000000000000031,691300000000000000000032"
  }
}
```

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

Require HTTP 200 and the intended IDs in **products[]** (Code: `output.body.products`). Recheck visibility and the parent Store Page before using the returned **url** for shopping continuation.

| Product information | How to use it |
| --- | --- |
| `variants[].id`, `attributes`, `sku` | Identify the actual selected option; product and variant IDs have different roles. |
| `variants[].pricing` | Preserve each returned currency/value and compare the matching variant’s price. |
| `variants[].stock` | Distinguish `unlimited` from a numeric quantity; recheck the selected option. |
| Product type and `url` | Physical, service, gift-card and digital shapes differ; send the buyer to the returned storefront page. |

### Let the agent use the product read

#### Studio

### 1. Choose the approved product IDs

For a small fixed set, use the merchant-approved CSV directly as the **product_ids** input’s provided **Default value**. This needs no per-query application variable; review the set when products or Store Pages change.

For a dynamic set, create **squarespace_product_ids** in **More → Variables** with an empty default. Have the developer supply the approved CSV on the conversation action before the product read.

### 2. Bind and test the read

Keep **Read approved Squarespace products** attached in **Agent → Global tools**. Provide **token** from Secret **squarespace_token** and **product_ids** from the fixed CSV or prepared variable. Both input rows should show **Value provided**.

Set a **Trigger** for comparing the approved candidates, run a Draft product question and compare the answer with the returned products.

#### Developer

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

For a fixed set, put the merchant-approved CSV directly in `inputVariables.product_ids.defaultValue` in the attachment below and skip variable creation. For a dynamic set, create the merchant-approved CSV variable:

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

The merchant/developer supplies the approved IDs from the product/Store Page checks above. For the dynamic set, your application sets `variables: {"squarespace_product_ids":"APPROVED_ID_1,APPROVED_ID_2"}` on the first [conversation action](/docs/api-reference/v4interact/interact-non-stream#streaming-action) before product retrieval. Verify it holds the approved set; do not let the model choose administrative catalog 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. The body below uses the dynamic variable; for a fixed set replace `inputVariables.product_ids.defaultValue` with your approved CSV:

```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": {
    "token": {
      "apiToolInputVariableID": "TOKEN_INPUT_ID",
      "required": false,
      "defaultValue": "{squarespace_token}"
    },
    "product_ids": {
      "apiToolInputVariableID": "PRODUCT_IDS_INPUT_ID",
      "required": false,
      "defaultValue": "{squarespace_product_ids}"
    }
  }
}
```

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

The shopper selects options and reviews actual availability/totals in the store. This manual uses product-page continuation rather than assuming a variant-cart permalink. [Help shoppers choose products](/docs/guides/integrations/commerce/help-shoppers-choose-products) covers comparison and recommendation checks.

### A product is missing or cannot be purchased

Check the API ID, visibility, Store Page and catalog pagination.

Compare the exact API IDs with the approved catalog export; the website ID and a product slug are not substitutes. A 404 is not a stock result. A hidden product or disabled Store Page must not be recommended as available. Follow each list’s own cursor when preparing the approved set and repeat the selected-product check after catalog changes. See [website organization](https://developers.squarespace.com/commerce-apis/website-overview).

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

## Looking up orders

Read the permitted order and interpret its payment and fulfillment fields.

First complete [Connecting Squarespace Commerce](#connecting-squarespace-commerce) to prepare the read credential for this store.

Have the authenticated application supply the permitted **order API ID** and customer association. The displayed **orderNumber** is a different identifier. An API key, email match or shopper-supplied order number does not establish access.

### 1. Prepare the authorized order input

#### Studio

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

### 2. Read the exact authorized order

#### Studio

Create **Read permitted Squarespace order** as **GET** `https://api.squarespace.com/1.0/commerce/orders/` plus provided **order_id**, with the website Authorization and User-Agent headers. Bind **token** to the Secret and **order_id** to **squarespace_order_id**. Choose **Run** in the request editor with one permitted test order ID and the read Secret, then inspect the standalone response.

| Request field | Value |
| --- | --- |
| Method | `GET` |
| URL | `https://api.squarespace.com/1.0/commerce/orders/{order_id}` |
| Header: Authorization | `Bearer {token}` |
| Header: User-Agent | `VoiceflowCommerce/1.0` |

#### Developer

Download [squarespace-order.json](/examples/ecommerce/providers/squarespace-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": {
    "token": "{squarespace_token}",
    "order_id": "691300000000000000000727"
  }
}
```

#### 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. Check identity before returning details

Require HTTP 200 and matching **id** plus the application-authorized customer/order association. The response is the Order directly: Code uses **output.body.id**, not `output.body.result`. Return only relevant line items, amounts and statuses; keep **internalNotes**, billing data and unrelated personal fields private.

### 4. Explain the state you actually verified

Use the returned fulfillment information and available tracking URL for that shipment. Fulfilled/shipped timestamps are not proof of delivery. If the customer requests a change, cancellation or refund, use the merchant support/review path rather than representing an order read as a mutation.

| Order field | Interpretation |
| --- | --- |
| `fulfillmentStatus`, `fulfillments[].trackingUrl` | Recorded fulfillment state and the available store/carrier link. |
| `paymentState`, payment/refund totals | Read together. `REFUNDED` can represent a partial refund; it does not by itself establish the amount or funds receipt. |
| `customerId` | Compare with the application’s permitted customer association; guest-order access also needs an explicit mapping. |

Use [Check an order](/docs/guides/integrations/commerce/check-an-order) for the customer journey. See [Orders](https://developers.squarespace.com/commerce-apis/orders) and [payment/fulfillment interpretation](https://developers.squarespace.com/commerce-apis/orders-overview).

### 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 Squarespace order** under **Agent → Global tools**. Keep both inputs enabled. Open each input’s **Default value** and select:

| Tool input | Provided value |
| --- | --- |
| **token** | Secret **squarespace_token** |
| **order_id** | Variable **squarespace_order_id** |

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

Squarespace API tool with the website token bound to a named Secret — Bind the website key and the application-authorized order ID.

Squarespace API tool with the application-provided order ID — Read the exact order ID 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 Squarespace order authorized by the signed-in application when the customer asks about that order.",
  "inputVariables": {
    "token": {
      "apiToolInputVariableID": "AUTH_INPUT_ID",
      "required": false,
      "defaultValue": "{squarespace_token}"
    },
    "order_id": {
      "apiToolInputVariableID": "ORDER_INPUT_ID",
      "required": false,
      "defaultValue": "{squarespace_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 lookup is missing or unavailable

Inspect access and the exact record before falling back to merchant support.

Test an authorized order, unknown API ID and failed customer association. Stop disclosure on a mismatch. Order-list defaults can exclude pending, failed, partially paid and refund-pending payment states, so an absent list item is not proof that the order does not exist; this flow uses the exact authorized ID. Inspect 401 authentication, 402 website expiry, 403 permissions and 404 record errors. On 429, follow the documented cooldown and retry reads conservatively; avoid turning a failed read into a status promise. [Response errors](https://commerce-apis.squarespace.com/commerce-apis/responses-error-handling) and [rate limits](https://commerce-apis.squarespace.com/commerce-apis/rate-limits) describe provider behavior.

<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 Squarespace Commerce 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

The merchant opens the website’s **Code Injection** panel and places the complete snippet in **Footer**, retaining existing code, then **Save**. This requires a plan with Code Injection; verify current [Code Injection eligibility and steps](https://support.squarespace.com/hc/en-us/articles/205815908-Customize-parts-of-your-site-with-code-injection). Saving this site-wide panel can affect the public site immediately; use the approved test/launch scope.

Footer injection runs before the closing body tag. Checkout pages do not support this custom-code route. Test the actual storefront in a fresh session, since editor previews can suppress scripts. For selected pages, choose the supported page-specific scope and remove duplicate site-wide copies. The Widget does not gain Squarespace administrative API access or customer identity from being embedded.

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