Overview
Connect Voiceflow to a Shopify store so your agent can find products, read orders and carry out confirmed order changes. Import product pages into Knowledge for descriptive answers. Use Functions for merchant-policy checks and shopping links when the job needs more than the connector.
Examples of when to use Shopify
- Compare products — retrieve candidates and explain which fits the shopper’s requirements.
- Answer product and policy questions — use approved content for descriptive answers.
- Check an order — return permitted order details and the store’s status link.
- Change an order or cancel it — execute a confirmed action and verify its outcome.
- Create a shopping link — send a confirmed variant selection to the store.
Studio
Code
The connector’s four catalog tools can run through the stable integration API or CLI. Shopify app authorization is project-scoped and starts in the browser. Functions, Knowledge and storefront links have their own setup below; a connector connection does not configure them.
Connecting Shopify
Install the Voiceflow app and connect the store to the intended project.
Use a test store and a separate test project before trying order changes. The merchant administrator must be able to install the app and approve its requested access. Store authorization belongs to the project; changing a Voiceflow Environment does not select another store.
Authorize the store
Open the Shopify connection
Open your project in Agent studio. Open Integrations under More in the project navigation, select Shopify and start the connection. You can also select Shopify while adding a tool from Agent → Global tools → +.
Install the app and choose the project
Follow Install the Voiceflow app to Shopify and approve installation for the intended store. Return to Voiceflow. When the project selector appears, choose the correct Workspace and Project, then Connect. If you started from a project, verify that the return flow connects that project.
Verify the connection with a read
Add Shopify → Get products and test a product handle you can inspect. Compare the returned product and store URL with Shopify. Stored connection status alone does not prove that the store will accept the action.
Configure Shopify tools
Studio
Add the action
In Agent, select + beside Global tools or open a Playbook’s tool picker, then choose the Shopify action.
Configure when it runs
Set the Trigger and input guidance. Use Capture response to save the result or a verified object path to a variable. For deterministic routing, use an Integration step in a Workflow.
Code
Prepare the test Environment
Use a Voiceflow bearer credential with access to your test project and Environment. Keep it on your backend or development machine. Set:
Use a current Voiceflow CLI if you choose CLI. API and CLI examples use the Environment’s saved Draft. Standalone execution does not attach a tool, compile an agent or publish a release.
Complete browser authorization above in the same project. The generic API-key connection operation cannot replace this app flow.
Discover the Shopify actions
Read the schemas before executing or attaching tools:
Read tools[].toolName, its inputs and integrationToolID. connected reports stored connection keys. A null integrationToolID means the action has not been added to this Environment; it can still run standalone.
Save the action for agent use
To let an agent call Get products, add its catalog definition and retain the returned integrationToolID:
Save this attachment as shopify-tool.json, replacing the ID:
Attach and test the Draft
Create the attachment once, then compile the Draft:
For one Playbook, replace the target with {"playbookID":"YOUR_PLAYBOOK_ID"}. Reuse an existing attachment when appropriate; creation is not an update. Run a Draft conversation to check that the agent actually calls the tool. Compilation does not publish the Environment; standalone execution alone does not test routing.
Reconnect or disconnect the store
Check the project and account before changing a shared store connection.
Use Integrations → Shopify to inspect and manage the connection. If authorization has expired or the app was removed, ask the merchant administrator to complete installation again, then repeat a read test. A project with an active store connection must be disconnected before switching to another store.
Disconnecting stops tools that use the store connection and disables refresh for imported Shopify documents. It does not remove already imported content from answers. Review that content separately in Knowledge. The Knowledge source and storefront embed also need their own verification after reconnection.
Finding products
Retrieve candidate products and compare the facts returned by the store.
Complete Connecting Shopify first to authorize the store and prepare the Code variables when using that view.
Use Get products (shopify_get_products) for a live catalog lookup. For a known product, search by its exact handle. Multiple search clauses are combined with OR, so adding filters can broaden the results.
Choose the search
Use productType: "Shirts" and limit: 3 for this candidate comparison, or one exact handle for a known product. The SKU field does not filter this action’s results.
Run Get products
Studio
Choose Shopify → Get products from Agent → Global tools → + or a Playbook’s tool picker. Set its Trigger, configure productType and limit, then run a product question.
Code
Require success: true, error: null and truncated: false before using output.data. An HTTP 200 alone does not establish a successful action.
Check the candidates before recommending
Inspect each product’s handle, title, status and onlineStoreUrl. Preserve the currency and treat priceRangeV2 as a range, not a selected variant’s price. In Code, products are in output.data.products.edges[].node. A broad Admin catalog search can include products unsuitable for the storefront. If a candidate has no verified onlineStoreUrl or its storefront visibility is uncertain, choose another returned candidate or ask the merchant to review it; do not invent a shopping URL.
The results include product IDs and aggregate totalInventory, rather than a purchasable variant ID or a selected size’s stock. Use the returned store link to let the shopper choose options.
Follow Help shoppers choose products for preference collection and comparison. Shopping links require a separate merchant-approved variant ID.
Product search fields and limits
Choose supported filters and recognize an incomplete result set.
products.pageInfo.hasNextPage means more matches exist. The connector exposes no cursor input, so the returned candidates may be incomplete.
Looking up orders
Read a permitted customer’s order without guessing its delivery state.
Complete Connecting Shopify first to authorize the store and prepare the Code variables when using that view.
Use Get order (shopify_get_order) to read one permitted order. Your application must establish the customer’s access before the lookup; email and order details are search criteria, not authentication.
Prepare the permitted order
Have your application supply the verified email, exact order number and authorized order ID. For a controlled builder test, choose one known test order you can inspect in Shopify.
Run Get order
Studio
Add Shopify → Get order to the intended path. Configure email and orderNumber, then run the lookup.
Code
Require success: true, error: null and truncated: false before using output.data. An HTTP 200 alone does not establish a successful action.
Verify the order and answer
Compare the returned ID with the application-authorized order ID before sharing any fields. Check the order name and line items against Shopify. No match means you cannot confirm the order’s status.
Use only the returned facts and offer statusPageUrl within the authorized customer session for further store-managed status.
The action does not return shipment events, a carrier tracking number, financial status or verified delivery time. Follow Check an order for the complete customer workflow.
The lookup returns no order or an unexpected match
Check the lookup criteria without exposing another customer’s record.
email is required, together with at least one of orderNumber, postalCode or creditCardLast4. Prefer the exact order number. The handler searches at most ten orders, filters postal codes afterward and returns the first match.
In Code, an absent output.data means no matching order was returned. Never treat an email-only search, a model-generated ID or the first match as access control. Stop disclosure when the returned ID does not match the permitted order and use your support fallback.
Updating orders
Apply a confirmed note or shipping-address change and inspect Shopify’s result.
Use Update order (shopify_update_order) after authorizing the customer and confirming the exact change. The current schema requires shippingAddress, including for a note-only change. A new note replaces the existing note.
Prepare the complete confirmed address
Use the permitted order lookup values from Looking up orders. Obtain all address fields you must preserve from Shopify or your trusted backend. Get order’s display address is incomplete; for a note-only change, supply the verified existing address.
Apply the confirmed change
Studio
Place Shopify → Update order on the confirmed-change path in a Workflow. Supply the permitted lookup values, complete address and optional replacement note. Run once with a dedicated test order.
Code
Require success: true, error: null and truncated: false before using output.data. An HTTP 200 alone does not establish a successful action.
Verify the saved change
Require an empty orderUpdate.userErrors and an orderUpdate.order.id matching the permitted order. In Code, these fields are under output.data. A successful execution wrapper can still contain Shopify business errors.
Check the full address and note in Shopify or your trusted backend. The returned display address omits street fields, and an address update does not prove an existing shipment was rerouted.
Follow Change or cancel an order to add confirmation and outcome checks around the action.
Update order fields
Preserve existing address fields and avoid replacing a note unintentionally.
Address fields include address1, address2, city, company, countryCode, provinceCode, zip, firstName, lastName and phone.
Cancelling orders
Cancel a confirmed order with the connector’s refund and restock behavior.
Complete Connecting Shopify first to authorize the store and prepare the Code variables when using that view.
Cancel order (shopify_cancel_order) sends reason CUSTOMER and refund: true. Restocking defaults to true. Explain these effects before asking for confirmation. Shopify decides whether cancellation is allowed; this action is not a separate partial-refund tool.
Confirm the cancellation
Authorize the customer’s access, check merchant policy and confirm the order, refund request and restock choice. Use a dedicated test order for the builder test.
Run Cancel order once
Studio
Place Shopify → Cancel order on the confirmed cancellation path. Set the permitted lookup values and explicit restock choice, then run it once.
Code
Require success: true, error: null and truncated: false before using output.data. An HTTP 200 alone does not establish a successful action.
Verify cancellation and the refund separately
Inspect the job result, then read the order again and check cancelledAt. Independently check the refund in Shopify before reporting money returned. A completed job does not prove the order was cancelled or that funds reached the customer.
The lookup inputs are the same as Get order. For the provider’s rules, see Shopify’s cancellation contract.
The cancellation fails or times out
Distinguish a rejected request from an action whose outcome is still unknown.
If the tool reports a provider error, keep the existing order state and route the case for support review. After a timeout, inspect the order and payment outcome before retrying. The connector supplies no idempotency key; another call can repeat a consequential request.
Import product knowledge
Choose the catalog pages your agent may use and keep their content current.
Import approved active product pages from the connected store. Knowledge is a snapshot for descriptive answers; use a live store check for current variant availability.
Select and verify product content
Find the import in the correct project
Open Agent studio, select the same project used by your agent or code, then Build → Knowledge base → Add data source → Shopify. Complete app installation when requested. An existing Shopify app connection can supply authorization; older Knowledge connections may require migration when reconnecting.
Select the source and import
In Import from Shopify, select approved Collections, Product types, Tags and Vendors, then check the matching count. Choose Folder, Refresh rate and retrieval metadata, then select Import data sources.
- Selections within one filter field are alternatives; different fields narrow the result together. This differs from Get products’ OR-based search.
- Never leaves refresh manual. Scheduled refresh depends on your workspace’s entitlement.
Wait for processing and inspect a product
Wait for the source and its product pages to finish processing. Open one expected product and compare its content and public URL with the store. An app connection or product count is not a finished import.
Studio
Return to Agent with Knowledge available, ask a question answered by the selected product page and inspect the source used. Also test a question the content cannot answer. Follow Answer product and policy questions to add policies and verify the complete answer path.
Code
Find the processed document
Use the project and Environment variables from Connecting Shopify. List the Draft documents:
Find the product in documents[], retain its Voiceflow id and require status.type: "SUCCESS".
Check retrieval and the agent answer
Query a fact from that product:
Compare answer.chunks[].documentID, source and content with the imported page. With synthesis disabled, answer.output is null. This diagnostic verifies retrieval; also run a Draft conversation to check the actual answer and fallback.
Maintain the managed source
Save source changes and re-sync
Open the Shopify source in Knowledge base, review its filters and schedule, then save changes. Select the source and choose Re-sync. This updates membership and refreshes retained product pages.
Check membership and freshness
Wait for processing, inspect added/removed products and compare a changed page’s text with the store. Check the intended Draft and release before rollout; matching membership alone does not prove freshness.
To recover an excluded product, open the parent source’s Filters → Excluded documents, select Restore, then Re-sync. When a source adopts matching older documents, review its membership rather than importing duplicates.
A product is missing or stale
Check authorization, active status, source filters, exclusions and processing.
Check the connected store, whether the product is active, the saved filter combination and excluded pages. Inspect any processing error before changing the filters. Refresh after fixing the source. If the app was disconnected, authorize it again and review the refresh schedule: reconnection alone does not prove imported text has been updated.
Create shopping links
Use an existing Function to turn an approved variant selection into a store link.
Use a Function with Shopify’s Cart and Checkout Permalinks to link a confirmed variant selection to the store. A link does not reserve stock or place an order.
Before setup, obtain the merchant’s advertised endpoint/version and approved numeric variant IDs. Get products returns product IDs, not this variant map. Keep merchant configuration out of shopper-controlled inputs.
Replace the fictional settings and illustrative merchant rules in build-shopping-link.mjs.
Studio
Create and test the Function
In Tools, create Build shopping link, paste the edited source, declare the inputs and outputs above, then save. Test a permitted selection and an unknown key.
Attach it after selection confirmation
Choose Agent → Global tools → + → Function and select the saved Function. Set a Trigger requiring a confirmed selection. Share only a nonempty shopping_url with result: "link_ready".
Code
Use the Voiceflow API variables for this Function. Generating a link does not require the store connector’s credentials.
Create the Function and its variables
Save build-shopping-link.mjs and create-function.mjs in one directory. Edit the merchant settings in the former. With Node 22+ and the variables from Connecting Shopify, run:
The helper calls the stable Function create and function-variable batch endpoints. It creates saved Draft resources without attaching or publishing them. Creation is not idempotent: inspect the project before rerunning after a failure.
Execute and inspect the saved Function
Require success: true, error: null, truncated: false and output.outputVars.result: "link_ready" before sharing output.outputVars.shopping_url. Unknown selections return an empty link. For agent invocation, attach the saved Function with Create tool, configure input guidance, then compile and test the Draft separately.
Open the resulting link in the intended test store and verify the variant, quantity and cart destination. Shopify may reduce or omit unavailable items. The buyer finishes the transaction in the store. Use the complete shopping-link workflow for the merchant setup and result checks.
Add the agent to your store
Install the current Widget snippet in a Shopify theme and verify the customer experience.
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.
Tool authorization and a visible storefront agent are separate checks. This path uses the existing Web chat Widget; it does not require a Shopify connector connection. Use a chat project you can edit, a test theme and a storefront owner with permission to edit its code.
Copy this project's Widget snippet
In Agent studio, choose the project, then open Widget → Installation. Copy the generated code with its copy control. Use the current project-specific snippet, including its generated verification settings, rather than a snippet from an example or another project. See Widget installation.
Install it in the test theme
In Shopify admin:
- Open Online Store → Themes, find the test theme and choose … → Edit code.
- Open Layout → theme.liquid.
- Paste the complete snippet immediately before
</body>, then save.
This assumes a Liquid theme with that layout; a custom storefront uses its own installation point. Follow Shopify’s theme code instructions for editor access and saving.
Verify the customer path before launch
The Widget needs a published production version. Publish only the version approved for the store, then preview the test theme in a fresh customer session.
- Check that the agent appears and completes a read-only product question.
- Test the permitted order-access path in that customer session.
- Have the store owner launch the theme after these checks. See Environments for Draft/release behavior.
A standalone tool call does not verify the customer client.
These Widget steps apply whether tools are authored through Studio or Code. A custom Chat client needs its own deployment and authentication.
For support escalation, use Human agent hand-off or Create and route support requests. Pass only the order context that the authenticated customer may share. Shopify tool authorization alone does not connect a help desk.