How to Connect Shopify

The Shopify integration lets your AI search published online-store products and, after the customer verifies the order email, look up that customer's Shopify orders. You can also enable refund-status and return-status reads, plus protected write actions: shipping-address changes, cancellation (with refund and restock), return requests, and full monetary refunds.

Availability: BUSINESS, ENTERPRISE, and active 14-day trials.

Connecting Shopify and selecting product or order tools does not turn on write actions. Select each write tool, then enable its action rule. Shopify and WooCommerce do not offer the same actions.

This connection uses a custom app in Shopify Admin. That is not a Shopify App Store listing.

Overview

After a correct setup, customers can:

Ask catalog questions without verifying an email
Verify the email on the order, then look up matching orders, refund records, or return records
Confirm eligible address changes, cancellations, return requests, or refunds in a secure form when you have enabled that tool and its rule

Voxe uses the Shopify Admin GraphQL API. Automatic address changes and cancellations only proceed when Shopify still shows a safely pre-fulfillment, merchant-managed state that Voxe can verify. Voxe does not edit external carrier labels.

Before you connect

Use a BUSINESS or ENTERPRISE plan, or an active 14-day trial
Create a custom app in Shopify Admin → Settings → Apps and sales channels → Develop apps
Grant the Admin API scopes that match the tools you will enable (see Required permissions)
Install the app on the store and copy the Admin API access token and the app API secret key (entered in Voxe as APP Secret Key)
Know the store domain (your-store or your-store.myshopify.com)
Decide which tools and action rules to enable

Note: Each workflow can have its own Shopify connection.

Required permissions

A Shopify tool runs only when it is enabled in Voxe (write tools also need their action rule) and the custom app token has the matching Admin API scopes. Selecting a tool in Voxe does not grant Shopify scopes. Installing a custom app does not enable Voxe tools.

Grant scopes on the custom app before you install it and copy the token. If you enable additional tools later, add the extra scopes on the custom app, reinstall or update the app so the token includes them, then replace the Voxe credentials (store domain, access token, and APP secret key together).

Scopes below are the official Admin API names for the GraphQL operations Voxe actually runs.

Product search

GraphQL: products (active, published titles; variants and shop currency)
Scope: read_products
Voxe does not write products, so write_products is not required.

Order lookup

GraphQL: orders (order, shipping address, line items, fulfillments and tracking when Shopify returns them)
Scope: read_orders
This is the ordinary order-read scope. It covers Shopify's default window of orders from about the last 60 days. It is not the same as read_all_orders (see below).

Refund status

GraphQL: orders { refunds { transactions } }
Scope: read_orders

Return status

GraphQL: orders { returns }
Scope: read_returns
Without this scope, return-status reads cannot run.

Shipping-address change

GraphQL: order preflight including fulfillmentOrders and fulfillments; mutation orderUpdate (shipping address); follow-up order read for the saved address
Scopes: read_orders, write_orders, and read_merchant_managed_fulfillment_orders
orderUpdate requires write_orders. Voxe only automates merchant-managed unfulfilled orders, so it must be able to read those fulfillment orders.

Cancellation

GraphQL: order preflight including payments, refunds, returns, fulfillment orders, and fulfillments; mutation orderCancel (customer reason, notify customer, restock, refund original payment methods); later job/order read until Shopify confirms cancellation
Scopes: read_orders, write_orders, read_merchant_managed_fulfillment_orders, plus read_returns because cancellation preflight reads return history
orderCancel requires write_orders.

Full monetary refund

GraphQL: order preflight including transactions, refunds, and returns; mutation refundCreate
Scopes: read_orders, write_orders, and read_returns (preflight reads return history)
Grant write_orders on the custom app for refund creates.

Return request

GraphQL: order preflight; returnableFulfillments; mutation returnRequest (one fulfilled item)
Scopes: read_orders, read_returns, write_returns
returnRequest requires write_returns. Shopify's returnableFulfillments query documentation does not currently name a separate scope; grant the return scopes with this tool. If Shopify rejects the query, the return request cannot be automated.

Minimum scope sets (choose one)

Catalog only (Search Shopify products):

read_products

Order and other read-only tools (order lookup and refund status; add product search if you also want catalog):

read_orders
read_products if product search is also enabled
read_returns only if Check verified Shopify return status is enabled

All currently supported Shopify commerce tools (catalog, order lookup, refund status, return status, address change, cancellation, return request, and refund):

read_products
read_orders
write_orders
read_merchant_managed_fulfillment_orders
read_returns
write_returns

If you enable only some write tools, start from order/read-only and add:

Address change: write_orders and read_merchant_managed_fulfillment_orders
Cancellation: write_orders, read_merchant_managed_fulfillment_orders, and read_returns
Refund: write_orders and read_returns
Return request: read_returns and write_returns

You do not need write_products, write_merchant_managed_fulfillment_orders, or customer-directory scopes for the tools Voxe currently offers.

Older than 60 days — optional, not a standard install scope: Shopify custom apps normally see orders from about the last 60 days. read_all_orders is a separate Shopify permission. You must request access from Shopify and, if they approve it, add it in addition to read_orders or write_orders. Do not add it unless you need lookups or actions on older orders. Most stores do not need it for a first connection.

If a required scope is missing or later revoked, lookups and writes fail closed. Chat should hand off to your team and should not treat this as a failed customer verification or retry the same request. Saving tools in Voxe does not restore Shopify permissions — update the custom app scopes and replace the token.

Connecting the integration

In Shopify Admin, create or open the custom app, set Admin API scopes, install the app, and copy the access token and API secret key
In Voxe, go to Dashboard → Integrations → Add Integration → Business Data Integrations
Select the workflow for this store
Choose Shopify
Enter:
Store domain — your-store or your-store.myshopify.com
Admin API access token
APP Secret Key — the custom app API secret key
Select the Shopify tools to attach
If you selected a write tool, open Shopify action automation, turn the matching rule on, and set its limits. For address changes check Allow changes to merchant-managed, unfulfilled orders; for cancellations check Merchant-managed, unfulfilled orders only
Save, then enable the integration under Your Integrations

Changing an existing connection

Leave every credential field blank to keep the current connection.

To replace it, fill the required credential fields together (store domain, access token, and APP secret key) in the same save. Do not change only the domain. Do this after expanding Shopify scopes so the new token includes them.

After you save (test the connection)

There is no separate Shopify "Test Connection" button. After the integration is enabled under Your Integrations:

Open that support chat
If product search is enabled, ask about a published product (no verification)
If order lookup is enabled, ask about a known recent test order so the verification link appears
If a write tool is enabled, use only a safe test order. Do not test cancellations or refunds on live customer orders

If catalog questions fail, check read_products. If recent order lookup fails after verification, check read_orders and that the token belongs to this shop. If writes go to support immediately, the custom app is likely missing write_orders or fulfillment-order/return scopes, or those scopes were revoked.

Available tools

Read-only (no secure confirmation)

Search Shopify products — no verification
Look up verified Shopify order — email verification
Check verified Shopify refund status — email verification
Check verified Shopify return status — email verification; needs read_returns

Protected write actions (verification and secure confirmation)

Change verified Shopify shipping address
Cancel verified Shopify order
Request verified Shopify return
Refund verified Shopify order

Unsupported

Shopify customer-directory or account-profile management
Partial refunds, item-level refunds, or restock-on-refund
Approving or declining returns (a request is not approval)
Editing carrier labels or 3PL fulfillments
Address changes or cancellations after fulfillment has started

Tool-by-tool behavior

Search Shopify products

What it does: Searches active products published to the online store. Returns title, description, URL, variants (up to 20) with SKU, base price, availability, and options. Five products per page.
Typical use: Catalog questions
Verification / confirmation: Neither
Scope: read_products
Limits: Additional variants may exist. Returned prices are store base prices; checkout confirms market pricing, tax, shipping, and availability.
Does not: Draft products, inventory writes, or discounts

Look up verified Shopify order

What it does: After verification, finds orders whose order email matches. Can return number, created/cancelled times, payment and fulfillment display status, shipping address when Shopify returns one, totals, line items (up to 20), and up to five fulfillments with tracking when present.
Typical use: Order status and "where is my order?"
Verification / confirmation: Verification only
Scope: read_orders
Filters: Optional order number or store-local date YYYY-MM-DD. Multiple matches must be narrowed. Voxe asks rather than picking the newest order.
Limits: Lookup considers a small match set (three). More matches require a number or date. Shopify ordinarily returns about the last 60 days of orders. Older orders need Shopify-approved read_all_orders in addition to read_orders; that is optional and not part of a standard Voxe install.
Does not: List every historical order unbounded, or treat chat email as identity

Check verified Shopify refund status

What it does: Reads refund records and payment transaction statuses for the verified order.
Typical use: "Was my refund created?"
Verification / confirmation: Verification only
Scope: read_orders
Does not: Prove that funds have arrived in a bank account, or create a refund

Check verified Shopify return status

What it does: Reads return name, status, and timestamps for the verified order.
Typical use: "What's the status of my return?"
Verification / confirmation: Verification only
Scope: read_returns
Does not: Create, approve, or refund a return

Change verified Shopify shipping address

What it does: Updates the order shipping address in Shopify when the order is still unfulfilled and merchant-managed.
Typical use: Correct a delivery address before fulfillment starts
Verification / confirmation: Both
Scopes: read_orders, write_orders, read_merchant_managed_fulfillment_orders
Settings: Enable Address changes. Set maximum order age. You must check Allow changes to merchant-managed, unfulfilled orders or automation will not execute. Optional: allow or block orders that already have refunds or returns.
Safety Voxe always applies: Display fulfillment must be unfulfilled, with no fulfillment records. Fulfillment orders must all be OPEN and UNSUBMITTED at a merchant-managed location (not a fulfillment service). 3PL or in-progress fulfillment goes to support. Voxe rechecks this immediately before writing.
Changes: Shopify order shipping address
Does not change: Saved account addresses, carrier labels, or external warehouse systems
Human review: Fulfillment started, external fulfillment, missing fulfillment-order data, or a saved address that does not match what was confirmed

Cancel verified Shopify order

What it does: Cancels the Shopify order, restocks inventory, notifies the customer, and refunds original payment methods — only before fulfillment, for a fully paid order within your refund limit.
Typical use: Customer cancels an unfulfilled paid order that still meets your rules
Verification / confirmation: Both
Scopes: read_orders, write_orders, read_merchant_managed_fulfillment_orders, read_returns
Settings: Enable Cancellations. Set maximum order age, Maximum refund, and Currency. Merchant-managed unfulfilled checkbox is required. Existing refund/return toggles still do not allow duplicate refunds.
Safety: Same pre-fulfillment floor as address changes. Financial status must be paid, with one supported successful capture/sale matching the order total and remaining refundable amount. Manual/offline gateways and pending transactions go to review.
Changes: Cancellation in Shopify (may stay "processing" until Shopify finishes the job). Refund and restock are requested with that cancellation.
Does not: Claim bank settlement, or cancel orders that have already entered fulfillment
Human review: Shopify still processing, job finished without confirmed cancellation, payment complexity, or fulfillment review

Request verified Shopify return

What it does: Submits a Shopify return request for one fulfilled item and quantity, with a customer reason. Status is requested; you still approve or decline in Shopify.
Typical use: Customer wants to start a return on a fulfilled item
Verification / confirmation: Both
Scopes: read_orders, read_returns, write_returns
Settings: Enable Return requests. Set maximum order age. Existing refund/return toggles apply. This action does not use the fulfillment checkbox used by address/cancel.
Changes: A requested return in Shopify
Does not: Approve the return, issue a refund, or restock. Items beyond the form need a person.
Human review: No supported returnable items, or Shopify errors

Refund verified Shopify order

What it does: Creates a full monetary refund of the current order total to the original payment, within your maximum refund and currency.
Typical use: Full refund when the order is still eligible and has a simple supported payment
Verification / confirmation: Both
Scopes: read_orders, write_orders, read_returns
Settings: Enable Full refunds. Set age, maximum refund, and currency. Existing refund/return toggles do not authorize a second full refund.
Safety: Paid status, one successful sale/capture, matching remaining refundable amount, no pending transactions. Not a restock and not a cancellation.
Changes: A Shopify refund record
Does not: Confirm bank timing, restock, or cancel the order
Human review: Complex payments, existing refunds when disallowed, or unconfirmed Shopify results

Settings

Write tools appear under Shopify action automation after you select the matching tool. Rules default off. Maximum order age is 1 to 2160 hours (the form starts at 24 hours until you change it). Maximum refund defaults to 0 until you set a limit — leave it at 0 and refunds/cancellations that check the amount will not automate.

For each write action:

Enabled
Maximum order age (hours)
Maximum refund and Currency — cancellations and full refunds (the full order amount must fit)
Automate orders with existing refunds / existing returns — still subject to Shopify eligibility; they do not authorize duplicate refunds
Allow changes to merchant-managed, unfulfilled orders (address changes) / Merchant-managed, unfulfilled orders only (cancellations) — required for those actions. Allows automation only while the order remains merchant-managed and eligible for updates. Orders that have entered external fulfillment or shipment processing require support.

Shopify eligibility and supported payment limits still apply even when a checkbox is on.

Customer verification

Private Shopify tools prove the email on the Shopify order. Chat profile email is not identity.

Required for: order lookup, refund status, return status, and every write action. Product search is public.

The customer experience matches WooCommerce: a 10-minute link in chat, email plus six-digit code in the secure form only, about 10 minutes of reuse in that conversation, automatic resume after success. Multiple orders are narrowed with a number or store-local date. A new verification is needed when the window ends, the email must change, or the conversation is no longer the same active thread.

Do not collect verification codes in chat.

Protected actions

request → verification if needed → identify the order → eligibility → secure confirmation → fresh recheck → operation → result

Confirmation is the secure form from chat (10 minutes), not a chat "yes"
Address changes are collected on that form
After confirm, Voxe re-reads Shopify and repeats eligibility because fulfillment or payment may have changed
Shopify cancellations can remain in progress; the AI should check status later rather than submitting a second cancellation
Failed, unknown, changed, expired, and fulfillment-started outcomes are not retried

Shipping-address changes

Automatic address changes are limited to orders that remain safely pre-fulfillment in the Shopify state Voxe can verify:

Unfulfilled display status
No fulfillment records yet
Merchant-managed fulfillment orders still OPEN and UNSUBMITTED
Not assigned to a fulfillment service / 3PL that Voxe can see

If fulfillment has started, tell the customer the address can no longer be changed automatically and continue in support. Voxe does not modify external carrier labels.

Refunds, cancellations, and returns

These are separate Shopify tools:

Cancel — unfulfilled, merchant-managed, paid order; includes refund of original payment methods and restock; may be asynchronous
Refund — full monetary refund only; no restock or cancel
Return request — requested return for one fulfilled item; not approval and not a refund
Refund status / return status — reads only

Do not assume WooCommerce has the same return tools.

Human escalation

Hand off when the customer asks for a person, when verification or confirmation expired, when Shopify fulfillment or payment state is ineligible, when a required scope is missing, when a cancellation job cannot be confirmed, or when the result is failed, unknown, or changed.

Hide Branding

Same Hide Branding control as the chat widget: Dashboard → Integrations → Add Integration → Chat Widget Script.

Off: VoxeDesk branding on verification and confirmation pages
On: merchant identity Voxe has for that support chat

See How to Set Up the Chat Widget.

Limitations

Selected tools and enabled rules only. Both the Voxe tool and the Shopify scope must be present.
Shopify's ordinary custom-app window is about 60 days of orders. read_all_orders is optional and requires Shopify approval; it is not a default Voxe scope.
Bounded catalog and order match sets; customers may need a number or date
Address/cancel automation only for verified merchant-managed pre-fulfillment
3PL and in-progress fulfillment are not automated
Simple payment shape required for automatic refund/cancel
Return requests are not approvals
Missing Admin API scopes fail closed
Voxe will not write when the fresh Shopify read fails safety checks

Troubleshooting

Connection / credentials: Domain, Admin API token, and APP secret key must belong to an installed custom app on that shop. Replace them together.
Insufficient scopes: Chat should hand off to your team and should not treat this as a verification problem. Add the missing scopes on the custom app, reinstall or update it, then replace the token in Voxe. Saving tools in Voxe does not grant Shopify permissions. The same applies if scopes are later revoked.
Older orders not found: Recent orders should work with read_orders. Orders older than about 60 days need Shopify-approved read_all_orders in addition; do not add that scope unless you need it.
Wrong shop: The store domain must match the shop that issued the token.
Tool not enabled: Select the tool and, for writes, enable the rule (including merchant-managed for address/cancel, and a real maximum refund where required).
Verification / confirmation: Latest chat link, code only in the form, 10-minute expiry.
Order not found: Email must match the order. For recent orders, confirm read_orders. Older orders may be outside Shopify's ordinary 60-day window.
Multiple matches: Provide order number or date.
Fulfillment started: Address and cancel automation stop. Continue in support or Shopify admin.
Blocked by settings: Age, amount, currency, existing refund/return policy, or merchant-managed checkbox off.
Cancellation still processing: Wait and check status; do not submit another cancel.
Needs human review: Unconfirmed writes, complex payments, 3PL fulfillment, or return items not listed on the form.

Security and customer data

Store the Admin API token only in the integration credential fields.
Verified order email is the identity for private tools.
Do not ask customers to paste access tokens or verification codes into chat.

What's next

Business Data Integrations Overview — Business Data across platforms
How to Connect WooCommerce — WooCommerce permissions and actions differ
How to Set Up the Chat Widget — Hide Branding
How System Messages Work — tool instructions are attached when the integration is active