Build with

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

Studio

The commerce agent combines product tools, Knowledge and merchant-policy functions. Photo:

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

1

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

Start Shopify authorization in the project that will use the store. Photo:
2

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.

3

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

1

Add the action

In Agent, select + beside Global tools or open a Playbook’s tool picker, then choose the Shopify action.

2

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

1

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.

2

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.

3

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:

4

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.

1

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.

2

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.

Search one product type with a small candidate limit. Photo:

Code

Require success: true, error: null and truncated: false before using output.data. An HTTP 200 alone does not establish a successful action.

3

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.

1

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.

2

Run Get order

Studio

Add Shopify → Get order to the intended path. Configure email and orderNumber, then run the lookup.

Configure the verified customer email and exact order number. Photo:

Code

Require success: true, error: null and truncated: false before using output.data. An HTTP 200 alone does not establish a successful action.

3

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.

1

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.

2

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.

Configure the confirmed shipping-address change before testing Update order. Photo:

Code

Require success: true, error: null and truncated: false before using output.data. An HTTP 200 alone does not establish a successful action.

3

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.

1

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.

2

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.

Review the cancellation inputs and restock choice before the confirmed action. Photo:

Code

Require success: true, error: null and truncated: false before using output.data. An HTTP 200 alone does not establish a successful action.

3

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

1

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.

Open Knowledge base in the project that will use the catalog. Photo:
2

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.
Select the approved Shopify products and their refresh schedule. Photo:
3

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

1

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

2

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

1

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.

2

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.

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.

1

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.

Use the generated Widget snippet for this project. Photo:
2

Install it in the test theme

In Shopify admin:

  1. Open Online Store → Themes, find the test theme and choose … → Edit code.
  2. Open Layout → theme.liquid.
  3. 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.

3

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.

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