Question 1

How does list_orders work?

Accepted Answer

list_orders lets customers see their recent order history from your Shopify store. The AI asks for the customer email address, which is used to search Shopify. Up to 10 orders are returned by default, sorted by most recent. Returns order number, order total, financial status (paid, pending, refunded), and fulfillment status (fulfilled, unfulfilled, partial). Optional filters include financial_status and fulfillment_status. Internal Shopify order IDs are never exposed — only the human-facing order number (e.g., #1042) is shared.

Question 2

How does get_order work? (with identity verification)

Accepted Answer

get_order retrieves full details for a specific order and uses a two-step identity verification process before releasing any data. Flow: customer provides order number, AI asks for the email address associated with the order, the order is looked up in Shopify, then verification fires with Step 1 (order number confirmed with numeric match) and Step 2 (email address confirmed with phonetic/fuzzy match). Both steps pass means full order details are shown; any step fails means access is denied after a maximum of 2 attempts per step and the session ends. Returns line items with quantities and prices, order totals, shipping address, and financial and fulfillment status. Internal Shopify order IDs are never shown.

Question 3

How does cancel_order work? (two-step: verify then confirm)

Accepted Answer

cancel_order is a destructive action that cannot be undone. It requires both identity verification and an explicit confirmation before anything is submitted. Full flow: customer states they want to cancel and provides their order number, identity verification fires immediately before cancellation with Step 1 (confirm order number, numeric match) and Step 2 (confirm email address, phonetic match), after both steps pass the AI asks "Are you sure you want to cancel this order? This cannot be undone," then customer says yes and the order is cancelled or says no and nothing happens. An optional cancel reason can be collected (customer, inventory, fraud, declined, other). Identity is always re-verified for this action even if the customer was already verified earlier in the same session.

Question 4

How does update_order work?

Accepted Answer

update_order lets you write an internal note or update tags on a Shopify order. These fields are internal and not visible to the customer in their own Shopify account. Flow: customer requests a note or tag update, identity verification fires with Step 1 (confirm order number, numeric match) and Step 2 (confirm email address, phonetic match), both steps pass and update is applied immediately with no further confirmation needed. Important: updating tags in Shopify replaces all existing tags — if the customer wants to add a tag, the AI first calls get_order to retrieve the current tag list, then includes both existing tags and the new one in the update call.

Question 5

How does list_fulfillments work? (tracking info)

Accepted Answer

list_fulfillments retrieves shipping and tracking information for an order. Identity verification fires before any tracking data is released. Flow: customer asks about shipping or tracking, AI asks for order number and email address, verification fires with Step 1 (order number numeric match) and Step 2 (email phonetic match), verification passes and fulfillment data is returned. Returns tracking numbers, carrier name, tracking URL (if available from the carrier), and fulfillment status. If the tracking URL is null, the AI informs the customer that tracking information is not yet available and suggests checking back later.

Question 6

How does list_refunds work?

Accepted Answer

list_refunds checks whether a refund has been issued on a specific order. Identity verification fires before any refund data is released. Flow: customer asks about a refund, AI asks for order number and email address, identity verification fires (order number numeric match plus email phonetic match), verification passes and refund records are returned. Returns refund amount, date the refund was processed, and refund status. If no refund has been issued, the AI informs the customer naturally without exposing internal order IDs.

Question 7

How does create_refund work?

Accepted Answer

create_refund initiates a refund on a specific line item within an order. It goes through full identity verification and a final confirmation before anything is submitted to Shopify. Flow: customer says they want a refund, AI calls get_order first to retrieve current line items and complete identity verification, AI collects which item to refund, quantity to refund, and optional reason for refund, identity verification fires (order number numeric match plus email phonetic match), AI asks for final confirmation, customer confirms and refund is initiated in Shopify. By default, Shopify sends a refund confirmation email to the customer — this can be disabled in the action configuration.

Question 8

What happens if an order cannot be cancelled?

Accepted Answer

cancel_order may fail if the order is already fulfilled (shipped), already cancelled, if the payment is being processed and has not yet been captured, or if the store fulfillment service has locked it. In these cases, Shopify returns an error which the AI surfaces clearly to the customer. For example: "This order has already been shipped and cannot be cancelled. You may need to request a return instead." The AI never silently fails — it always tells the customer what happened and, where relevant, suggests an alternative action. Identity verification still fires even if the cancellation ultimately fails.

Question 9

What happens when list_orders finds no results?

Accepted Answer

If no orders are associated with the provided email address, the AI tells the customer naturally: "I wasn't able to find any orders linked to that email address." The AI may ask the customer to double-check the email spelling or try an alternative email they might have used at checkout. No error is shown — empty results are handled gracefully and the conversation continues.

Question 10

What happens if create_refund fails?

Accepted Answer

A refund may fail if the order has already been fully refunded, if the specific line item has already been refunded for the requested quantity, or if the order payment method does not support refunds via API (e.g., cash on delivery). In all cases, Shopify returns a descriptive error and the AI relays it to the customer clearly. If a refund is not possible through the integration, the AI suggests the customer contact the store directly to resolve the issue.

Question 11

What happens if the customer provides the wrong order number or email during verification?

Accepted Answer

Each verification step allows a maximum of 2 attempts. After 2 failed attempts on any step, the session ends immediately. The AI delivers a polite closing message: "I'm sorry, I wasn't able to verify your identity. Please contact our support team for further assistance." No data is shared and no action is taken, regardless of how far along the conversation was before the failure. The 2-attempt limit applies per step — failing step 1 twice ends the session before step 2 is ever reached.

Question 12

How do lookup_discount_code and list_price_rules work?

Accepted Answer

These two actions handle discount and promotion inquiries. Neither requires identity verification since they only return store-wide offer information. lookup_discount_code validates a specific discount code and returns whether it is active, along with the discount type and value. Valid codes are confirmed with the discount details; invalid or expired codes get a clear response. Lookup is case-insensitive and strips leading/trailing spaces. list_price_rules lists currently active promotions: it automatically filters out future promotions not yet started, expired promotions, fully-redeemed code pools, and internal or staff promotions — only customer-facing, currently valid deals are returned.

Order Management

What is returned

Optional filters

Privacy

Example