Question 1

How does list_products work and what are product cards?

Accepted Answer

list_products fetches up to 50 products from your Shopify store and presents them to the AI. The AI reads a text summary of all products (ID, name, type, tags, price range, and availability) to decide which ones to recommend. After deciding, the AI calls show_product_cards with the most relevant product IDs (up to 4). Product cards then appear in the chat widget below the AI text response. Each card shows: product image (grey placeholder if none), product title in bold, short description, price (single price or range if variants differ), a View link opening the Shopify product page in a new tab, and an out-of-stock badge for unavailable products. Card layout: 1 product shows full-width, 2 to 4 products show in a 2-column grid.

Question 2

How does get_product work?

Accepted Answer

get_product searches for a specific product by name. It is fully self-contained — no list_products call is needed first. The AI uses this when a customer asks about a particular product by name. It returns full product details: all variants, pricing per variant, availability, and the full description. For a single matching result, a product card is shown automatically in the widget. For multiple results, the AI presents all relevant ones. No identity verification is required — any visitor can trigger a product lookup. Works on partial names — "snowboard" will match "Complete Snowboard". Returns all variant-level detail so customers can see exactly which sizes or colours are available and at what price.

Question 3

How do list_collections and list_smart_collections work?

Accepted Answer

These two tools let the AI browse your store category structure. list_collections returns your custom product categories — the ones you create and manage manually in Shopify (e.g., "Accessories", "New Arrivals"). list_smart_collections returns automated collections that Shopify builds based on rules (e.g., all products tagged "sale", all products over $100). Both tools return collection names only — no internal collection IDs are exposed to the customer. They are typically used together with get_collection_products to let a customer browse a specific category. Example: customer asks "What categories do you have?" — AI lists collection names, customer says "Show me the Winter collection" — AI calls get_collection_products to fetch and display products in that category.

Question 4

How does get_collection_products work?

Accepted Answer

get_collection_products fetches all products within a specific collection or category. The AI uses the collection ID received from a prior list_collections or list_smart_collections call — this ID is handled internally and never shown to the customer. Once products are fetched, the same flow as list_products applies: the AI reads a text summary of up to 50 products, selects the most relevant ones, and calls show_product_cards to display them in the widget. Works for both custom collections and smart collections. Product cards use the same layout: full-width for 1 card, 2-column grid for 2 to 4 cards.

Question 5

How does check_inventory work?

Accepted Answer

check_inventory checks real-time stock levels for a product by name. It is completely standalone — no other tool calls are needed beforehand. Inventory results are returned as plain text only — no product cards are shown for inventory checks. Stock status labels: In stock (more than 5 units available), Low stock (1 to 5 units available), Out of stock (0 units), Backordered (negative inventory quantity, oversold or pre-ordered stock). Products with inventory tracking disabled, or configured to "continue selling when out of stock" in Shopify, will always report as in stock. Example: customer asks "Is the Complete Snowboard in stock?" — AI calls check_inventory and reports stock levels per variant.

Question 6

How does list_locations work?

Accepted Answer

list_locations returns all active store and warehouse locations configured in your Shopify account, including their names and full addresses. The AI uses this when a customer wants to know where your physical locations are. Common customer questions this answers: "Where are you located?", "Do you have a physical store I can visit?", "Do you have a store near [city]?". No identity verification required. Returns location names and full addresses only — internal location IDs are never shown. Only active locations are listed — deactivated locations in Shopify are excluded automatically.

Question 7

How do draft orders work? (create_draft_order and complete_draft_order)

Accepted Answer

Draft orders let your AI create a quote or custom order during conversation, then share a payment link so the customer can pay directly. Two-step flow: (1) create_draft_order — AI collects product name, price, and quantity, optionally collects customer email, discount code, and order note, always asks the customer to confirm all line items before creating, then creates a draft order in Shopify and shares the invoice URL directly in chat. (2) complete_draft_order — converts a draft into a real paid order in Shopify, used when the customer pays through an alternative method like bank transfer or in person. Discount codes are validated first using lookup_discount_code before being included in the draft. The AI never creates orders without explicit customer approval.

Question 8

How does lookup_discount_code work?

Accepted Answer

lookup_discount_code validates a specific discount code against your Shopify store and returns its value. The AI uses this automatically whenever a customer mentions a code during a conversation, particularly during draft order creation. Returns discount type (percentage off or fixed amount off) and discount value (the exact percentage or amount). If the code is invalid, expired, or has exceeded its usage limit, the AI tells the customer clearly without guessing a discount amount or suggesting alternative codes. Technical details: case-insensitive, strips extra whitespace automatically, and is called automatically when a customer mentions a code.

Question 9

How does list_price_rules work?

Accepted Answer

list_price_rules returns all currently active promotions running in your Shopify store. The AI uses this when a customer asks about available deals, sales, or discounts. What gets filtered out automatically: future promotions scheduled to start after the current date, expired promotions whose end date has passed, fully-redeemed code pools where all codes have been used, and internal promotions (staff, influencer, or wholesale price rules not intended for public customers). Returns promotion names and discount details only — no internal price rule IDs are exposed to the customer.

Question 10

What if list_products or get_product finds no results?

Accepted Answer

list_products with no results: if the store has no published products or all products are unpublished/hidden, the AI says "I wasn't able to find any products in the store" and suggests the customer contact support. get_product with no match: if the search term does not match any product title, the AI says "I couldn't find a product matching that name" and may ask the customer to rephrase or try a different name. Partial matches work: searching "snowboard" will match "The Complete Snowboard" so exact names are not required.

Question 11

What if check_inventory matches multiple products with similar names?

Accepted Answer

When the product name matches several products (e.g., "hoodie" matches "Blue Hoodie", "Red Hoodie", "Classic Hoodie"), inventory levels for all matching products are returned. The AI presents each one clearly so the customer can identify the specific item they are asking about. Example response: "I found 3 products matching 'hoodie': Blue Hoodie (in stock: 14 units), Red Hoodie (low stock: 2 units), Classic Hoodie (out of stock)." Up to 5 matching products are returned. If there are more, the AI suggests using a more specific search term.

Question 12

What happens if a draft order expires before the customer pays?

Accepted Answer

Shopify draft orders expire based on the draft order expiry settings in your store — there is no expiry by default unless you have configured one. If a customer tries to use an expired invoice link, they will see an error page on Shopify's side. In that case, the customer can ask the AI to create a new draft order. complete_draft_order will also fail on an expired draft — Shopify returns an error which the AI surfaces: "This draft order is no longer available. Shall I create a new one?".

Question 13

How are prices and currencies displayed in product cards?

Accepted Answer

The store currency is detected automatically when you first connect via OAuth. Shopify returns the store base currency in the shop info response, and prices are displayed using the correct currency symbol. Supported currency symbols: USD ($), EUR (euro symbol), GBP (pound sign), JPY (yen sign), AUD (A$), CAD (C$), DKK/SEK/NOK (kr), CHF (Fr). Price ranges are shown when a product has variants with different prices (e.g., euro 19.99 to euro 39.99). If a variant has no price set, it is excluded from the range calculation.

Products, Inventory & Draft Orders

What each product card shows

Card layout

Example