Build with

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.

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

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.

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.

These are site-level API-key headers; 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.

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

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 site catalog

Studio

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

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.

Code

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

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.

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.

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.

Finding products

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

Complete Connecting Wix Stores first to verify the site and prepare its read credential.

Detect the catalog version 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, 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

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

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.

Use the V1 endpoint and backend-prepared JSON-string filter. Photo:

Code

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

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.

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.

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

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.

Code

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:

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

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

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

Code

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:

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

Looking up orders and tracking

Read the permitted order and its separately recorded fulfillments.

First complete 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. 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: {"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.

Code

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

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

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:

Inspect the returned order ID before sharing tracking.

Code

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

1

Create the saved API request

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

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:

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

Bind the Wix key and the application-authorized order GUID. Photo:
Read the order GUID 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.

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.

Code

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:

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.

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 and fulfillment records.

Test a permitted order, missing order and wrong buyer/returned ID. Stop disclosure on association failure and use the support-request path.

Updating a shipping destination

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

First read the authorized order 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 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:

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.

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.

Map the authorized order and complete confirmed shipping destination. Photo:

Code

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 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 and prepare a controlled test with the permitted GUID:

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.

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. Pending or rejected orders can fail preconditions. After an unknown result, inspect the actual saved destination before considering another write.

Cancelling orders

Confirm cancellation, inventory and notification effects before execution.

First read the authorized order 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 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.

Confirm the fixed restock and notification behavior before cancellation. Photo:

Code

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

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.

See Cancel Order. To change restock/email behavior, prepare and test a separate merchant-approved request rather than letting the model invent effects.

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

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

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.

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.