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 — inspect approved products, variants and their enabled Store Page.
- Check an order — return the authorized record and available fulfillment information.
- Answer policy questions — use approved content with a refresh process.
- Assess a return request — 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.
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
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.
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:
Retain secret.id as SECRET_ID, then set the test 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:
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.
Run the saved request once
Create the saved API request
Retain apiTool.id as API_TOOL_ID and resolve unresolvedReferences.
Inspect and execute it
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:
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.
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.
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:
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.
Run the saved request once
Create the saved API request
Retain apiTool.id as API_TOOL_ID, save the same value as PRODUCT_TOOL_ID now, and resolve unresolvedReferences.
Inspect and execute it
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
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.
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:
Compile the Draft
Resolve unresolvedReferences, then compile the Environment:
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.
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.
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:
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.
Run the saved request once
Create the saved API request
Retain apiTool.id as API_TOOL_ID, save the same value as ORDER_TOOL_ID now, and resolve unresolvedReferences.
Inspect and execute it
Require success: true, error: null and truncated: false, then inspect output.status and output.body. A Voiceflow HTTP 200 alone is not provider success.
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.
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
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.
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
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
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.
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.
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.
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.
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.
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.