Build with

Overview

Connect Voiceflow to WooCommerce so your agent can compare public products, read a permitted customer’s order and carry out confirmed merchant-approved changes. API tools read the store; Knowledge supplies approved descriptions and policies; Functions can assess a return request or build a bounded shopping link.

Public catalog GETs need no WooCommerce credential. Private order tools use a merchant-authorized REST key; neither that key nor an order number authenticates the shopper.

Connecting WooCommerce

Prepare private order access separately from public catalog reads.

Use a dedicated test project/store and a merchant administrator who can manage WooCommerce API keys. Public product discovery can start at Finding products without a private key.

Prepare the merchant credential

In WordPress Settings → Permalinks, choose a structure other than Plain before using these /wp-json/wc/v3 URLs. See the REST API requirements.

1

Create a restricted test key

The merchant creates a dedicated WordPress user with the required WooCommerce capabilities. Open WooCommerce → Settings → Advanced → REST API → Add Key. Select that user, add a description and choose Read for order lookups. Generate and save the Consumer Key/Secret. Use a separate Read/Write key for the confirmed changes below. WooCommerce authentication explains user permissions and key revocation.

2

Prepare authorization for the intended store

Use HTTPS and /wp-json/wc/v3. Your developer prepares Basic followed by Base64 of CONSUMER_KEY:CONSUMER_SECRET. This is the full private authorization value, not shopper identity. Have the application supply a permitted test order’s numeric API ID and its customer association.

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 woocommerce_read_authorization with that complete Basic value. Creating its default also writes Main’s Published value, so use the dedicated test project. Set the intended Environment’s Draft override when needed.

Continue to Looking up orders to create the request and configure its provided inputs. You can set up public product reads independently.

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

Rotate or revoke private access

Replace the runtime credential and repeat a read before retiring the old key.

Generate a replacement key in WooCommerce, update the relevant Voiceflow Secret default and Draft/Published values, then verify a known read before revoking the old key. Deleting its WordPress user or revoking the key breaks access. Changing an Environment does not change a fixed store URL. Removing a Voiceflow tool does not revoke the merchant key or delete imported Knowledge.

Finding products

Compare public catalog facts and recheck the selected variation.

Use WooCommerce’s public Store API for shopper product discovery. The example searches visible shirts; it requires no API key or nonce.

1

Configure a public product search

Studio

In Agent → Global tools → + → API call, create Find WooCommerce products with the fields below. This public request needs no merchant credential.

Add search under Input variables, then use that local input in the search parameter.

Configure the public catalog request and encoded query parameters. Photo:

Code

Prepare the Voiceflow API variables first. Public Store API product reads do not require a WooCommerce key.

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

2

Compare the returned candidates

Require the expected public product and storefront permalink. In Code, candidates are output.body[] after HTTP 200. Compare name, descriptions, images and returned prices with the shopper’s requirements. Password-protected descriptions may be redacted; keep those products out of this worked recommendation.

3

List the parent product’s variations

Variations are excluded from the first search. Use the returned parent product ID; this example lists at most 20 variations. A missing option is not proof that it does not exist.

Studio

Create Find WooCommerce variations as a separate public API call:

Code

Download woocommerce-variations.json as tool.json. Save {"inputs":{"product_id":"RETURNED_PARENT_ID"}} as inputs.json, replacing the placeholder. Create and execute it with the API/CLI flow above. Save its returned apiTool.id immediately as VARIATIONS_TOOL_ID before reusing API_TOOL_ID; keep the search request’s PRODUCT_TOOL_ID unchanged.

Compare the returned IDs and attributes with the shopper’s selected option. Narrow the selection or continue in the store if you cannot confirm it.

4

Recheck the chosen product or variation

Studio

Create Read WooCommerce selected product as a separate public API call. Supply an ID returned by the product or variation result:

Code

Download woocommerce-product.json as tool.json. Save {"inputs":{"product_id":"RETURNED_SELECTED_ID"}} as inputs.json, replacing the placeholder. Create and execute it with the flow above, saving its returned ID as SELECTED_PRODUCT_TOOL_ID before reusing API_TOOL_ID. Keep PRODUCT_TOOL_ID unchanged.

Use this exact result for price, currency and availability claims.

Let the agent use the product read

Studio

In Agent → Global tools, keep Find WooCommerce products attached. Describe when to search for product candidates and let the agent supply search from the shopper’s requirements. This public request has no merchant credential. Run a product question and compare the recommendation with the actual returned candidates.

Code

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

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. Test an empty result and an unmet requirement too. Standalone execution alone does not verify agent routing.

Use the returned product page or shopping link. Voiceflow’s server request does not inherit the buyer’s browser cart, tax location or currency-plugin session; the store owns final checkout totals.

Make variation rechecks callable

Keep the variation-list and exact-product requests as separate tools. A product ID here comes from a returned public product; it is not an order identifier.

Studio

In Agent → Global tools, attach Find WooCommerce variations. Let the agent supply product_id from the parent product result. Test a variable parent and inspect the variation IDs/attributes returned before the agent chooses an option.

Code

Use VARIATIONS_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 VARIATIONS_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 a variable parent and inspect the variation IDs/attributes returned before the agent chooses an option.

Studio

Attach Read WooCommerce selected product separately. Let the agent supply product_id only from a returned product/variation result. Test an option-specific question and verify that the exact selected ID is re-read before the answer; route missing or unavailable options back to selection.

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 verify that the exact selected ID is re-read before the answer; route missing or unavailable options back to selection.

The search is empty or incomplete

Check visibility, filters and pagination without inventing candidates.

The Store API exposes published products; a non-published exact product returns 404. Keep catalog_visibility=visible for this recommendation path. Increase page only when needed and inspect pagination headers such as X-WP-TotalPages; the first three results are not the full catalog. Verify installed version/extensions before relying on additional stock or custom filters. Help shoppers choose products covers the complete comparison journey.

Looking up orders

Return permitted order information without inventing delivery evidence.

First complete Connecting WooCommerce to prepare the read credential for this store.

Have the authenticated application resolve the permitted numeric API order ID. A displayed order number, email search or customer_id supplied by the shopper is not authorization. For guest orders, customer_id: 0 still needs an application-owned association.

1

Prepare the authorized order input

Studio

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

2

Read the permitted order

Studio

In Agent → Global tools → + → API call, create Read permitted WooCommerce order as GET https://YOUR_STORE/wp-json/wc/v3/orders/ with the trusted order_id appended. Add Authorization through the tool-local authorization input and Accept: application/json. Bind that input to woocommerce_read_authorization and order_id to woocommerce_order_id. Choose Run in the request editor and supply the permitted test order ID and the named read Secret. Inspect this standalone response before testing the agent.

Code

Download woocommerce-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 record before answering

Require HTTP 200 and returned id equal to the permitted API ID; in Code this is output.body.id. Check the customer association and relevant line items before disclosing details. Keep billing data and unrelated personal fields private.

Use Check an order for the customer journey. Carrier tracking requires an actual fulfillment/extension contract verified for that store; core order status does not provide it.

Make the permitted read available to the agent

Use the order request you just tested. In Code, use its saved ORDER_TOOL_ID; the public product request is a separate resource.

Studio

1

Provide the credential and order ID

Open Read permitted WooCommerce 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 order access to a Secret and an application-provided order ID. Photo:
Keep private order reads bound to the application-authorized record. 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 cannot be confirmed

Separate missing access, missing records and provider errors.

Test a permitted order, missing ID and wrong returned/customer ID. Stop disclosure on association failure or a mismatched ID. Inspect 401/403 credentials/capabilities and 404 records separately. Do not search unrelated customers or interpret a failed read as a delivery result.

Updating orders

Apply a complete customer-confirmed shipping correction.

First read the authorized order to prepare its provided input and verify the current record.

Before a write, the merchant supplies a separate Read/Write key. Store its complete Basic value as woocommerce_write_authorization using the Secret setup, with the intended Draft/Published values. Your application authorizes the order and confirms merchant eligibility before the Workflow executes.

1

Prepare the confirmed shipping fields

Read the current permitted order and preserve address fields outside the intended correction. Confirm the complete destination with the customer. Send only approved shipping fields; omit payment flags such as set_paid. The fictional test body is:

2

Run the bounded correction

Studio

Create Update confirmed WooCommerce address as a PUT API call to the permitted order URL. Add JSON content type and a raw JSON body containing the tool input {payload}. In More → Variables, create woocommerce_confirmed_payload with an empty default. Have your backend serialize the confirmed body with prepare-commerce-payload.mjs and populate it before execution.

In the confirmed Workflow path, add the saved request through an API call tool step. Bind authorization to the write Secret, order_id to the application-owned order variable and payload to woocommerce_confirmed_payload as provided values. Keep this mutation off unconfirmed Global tools.

Use trusted order and confirmed-payload values on the change path. 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 woocommerce-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 beside it. Your backend uses its stringifyToolJSON helper to preserve JSON and literal brace text; it does not perform authorization. For this controlled test:

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

Verify the persisted address

Require HTTP 200, the permitted returned id and the expected shipping fields. Read that order again and compare the full destination. A saved address correction does not guarantee an existing shipment was rerouted.

Follow the order contract and change workflow. After a timeout, inspect the actual order before considering another write.

Record a request for review

Save a private order note without promising a return or refund.

First read the authorized order to prepare its provided input and verify the current record.

Use a merchant-approved internal note after authorizing the order and confirming the customer’s request. This records work for staff; it does not create a help-desk conversation or notify a live teammate by itself.

Prepare a separate Read/Write key and create or reuse Secret woocommerce_write_authorization for its full Basic value using the credential setup, with the intended Draft/Published values. In those setup examples, change SECRET_NAME to woocommerce_write_authorization and use the write key’s complete value.

Save this fictional test body as confirmed-body.json:

Studio

Create or reuse woocommerce_confirmed_payload in More → Variables, keeping its default empty. Have the developer serialize the customer-confirmed private note with prepare-commerce-payload.mjs and populate that variable before the Workflow call. The backend owns authorization and confirmation; creating an empty variable does not prepare the note.

Create Record WooCommerce review request as POST to /wp-json/wc/v3/orders/ plus the permitted order_id and /notes. Use the write Secret, JSON content type and raw {payload}. Populate woocommerce_confirmed_payload with the backend-prepared, confirmed note. Call the saved API request from the authorized Workflow path, with all three inputs provided.

Keep a merchant-review note private and tied to the permitted order. 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. Verify the created note ID, private flag and saved note before reporting success.

Download woocommerce-note.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 beside it. Your backend uses its stringifyToolJSON helper to preserve JSON and literal brace text; it does not perform authorization. For this controlled test:

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 201, retain the returned note id and verify customer_note: false in output.body and WooCommerce. Setting this flag true exposes/notifies the customer. An ambiguous POST can create duplicate notes; inspect the order’s existing notes before retrying. See Order notes.

Cancelling orders

Change an eligible order’s status with explicit merchant approval.

First read the authorized order to prepare its provided input and verify the current record.

Before a write, the merchant supplies a separate Read/Write key. Store its complete Basic value as woocommerce_write_authorization using the Secret setup, with the intended Draft/Published values. Your application authorizes the order and confirms merchant eligibility before the Workflow executes.

Setting status: "cancelled" returns managed stock where inventory management applies and can still require a separate refund. Confirm cancellation with the customer, check current fulfillment and merchant policy, and keep refund handling with the merchant. Review WooCommerce → Settings → Emails and installed notification extensions before testing: a status change can trigger configured cancellation notifications. This request has no email-suppression flag. See WooCommerce email settings.

1

Run the confirmed cancellation

Studio

Create Cancel confirmed WooCommerce order as PUT to the permitted order URL, with the write Secret, JSON content type and fixed body {"status":"cancelled"}. Place its API call step only on the confirmed, authorized Workflow path. Bind the permitted ID and credential as provided values. Run once with a dedicated test order.

Cancel only after authorization, merchant checks and explicit confirmation. 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 woocommerce-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

Verify cancellation and payment separately

Require HTTP 200, the correct returned id and status: "cancelled", then re-read the same order. Inspect the separate payment/refund outcome before reporting money returned. Manually setting an order to refunded is not proof that funds moved.

See WooCommerce order-status behavior. An unknown outcome needs investigation before retrying; keep a rejected or raced change on the merchant support path.

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

This path assumes a WordPress store where the merchant can install a site plugin and the active theme calls wp_footer.

  1. Give the WordPress developer the complete generated snippet and voiceflow-wordpress-widget.php. The developer replaces its marked comment with that snippet, packages the file inside a voiceflow-widget folder as a ZIP and supplies the reviewed ZIP to the merchant.
  2. In WordPress, the authorized merchant opens Plugins → Add New Plugin → Upload Plugin, chooses the ZIP, installs it and activates it. Follow WordPress plugin installation for the current controls and hosting permissions.
  3. Have the developer confirm which templates call the hook and where the plugin is installed. Verify the actual product, cart and checkout pages; a missing theme hook needs the developer’s approved installation point.

The template contains no Widget until the developer inserts the project-specific snippet. Keep provider keys out of it. This is a site deployment mechanism, separate from the WooCommerce API connection.

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.