Build with

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.

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.

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 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 and authentication.

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.

Code

Use a Voiceflow bearer credential with access to an editable test project and Environment. Keep it on your backend or development machine. Set:

Use the current Voiceflow CLI 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.

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

Before serving traffic, set the target Published Secret value with versionVariant: "published", then publish the tested Environment. A Draft override does not configure Published.

Verify the website

Studio

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

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.

Code

Download 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:

1

Create the saved API request

Retain apiTool.id as API_TOOL_ID. Resolve any unresolvedReferences. Inspect its inputs with the API-tool schema before execution.

2

Run the saved request once

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.

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.

Finding products

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

Complete Connecting Squarespace Commerce first to verify the site and prepare its read credential.

Use current Products v2. 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.

Supply token from Secret squarespace_token. In Code, download 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, 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.

Read the merchant-approved product IDs from the current Products v2 API. Photo:

Code

Download 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:

1

Create the saved API request

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 before execution.

2

Run the saved request once

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.

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.

Code

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:

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

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:

1

Compile the Draft

Resolve unresolvedReferences, then compile the Environment:

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

Looking up orders

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

First complete 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. Use one permitted test order; creating an empty variable alone does not supply an order ID.

Code

Create the identity variable with an empty default; your authenticated backend supplies its permitted order ID on the first conversation action before a read can run:

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.

Code

Download 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:

1

Create the saved API request

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 before execution.

2

Run the saved request once

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.

Use Check an order for the customer journey. See Orders and payment/fulfillment interpretation.

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:

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

Bind the website key and the application-authorized order ID. Photo:
Read the exact order ID established by the authenticated application. Photo:
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.

Code

List this API tool’s input IDs:

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

Resolve unresolvedReferences, then compile the Draft:

Run a Draft conversation 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 and rate limits describe provider behavior.

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

Import approved public content separately from live order tools. Photo:
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.

Code

Prepare the Voiceflow API variables, then import one approved public page. This URL import does not require the store’s API credential:

Retain document.id as DOCUMENT_ID and wait for processing:

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

Compare answer.chunks[].documentID, source and content with the approved page. answer.output is null with synthesis disabled. Also run a Draft conversation to test the actual answer and fallback.

Use Docs or text import 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 for updates, refresh and removal. Check the intended Draft/release separately from the store API connection.

Assess return requests

Apply a merchant policy and route the result for review.

Use the existing return-assessment workflow with your approved policy. An assessment does not authorize a return, create a label or issue a refund.

Studio

Create the Guide’s Assess return request Function in Tools, declare its five inputs and two outputs, then use a Function step in a Workflow. Map trusted values and save decision and reason into conversation variables before routing.

Assess the approved policy with trusted fulfillment data. Photo:

Code

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.

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 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, open the project, then Widget → Installation. Copy the complete current snippet, including generated verification settings. See Widget installation.

Copy the generated Widget snippet for the project you will deploy. Photo:
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. 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.

Use the up and down arrow keys to select a result, Enter to open it, and Escape to close the search.