Shopify

shopify_get_order_by_id

• Purpose: Fetch details for a specific Shopify order.

• Key Params: order_id: str

• When/How to Use: Use when a user asks about the status or details of a specific order and provides an order number or ID. Instruct the AI to ask for the order ID if the user's query requires it but isn't provided initially.

• Important Note: Customers may confuse the order ID with the order name, or some orders may have prefixes. If a lookup fails, ask the customer to double-check that they're providing a valid order ID (not order name) and verify the reference format in their Shopify admin.

• Example Prompt Instruction:

  If the user is asking about the status or location of their order, you must ask them for their order number. Once the user provides an order number, you must call shopify_get_order_by_id with the provided order_id as the parameter. Use the information returned by the tool to answer the user's question about their order.

shopify_get_order_history

• Purpose: Retrieve the full order history (most recent 5 orders) for a customer by email address.

• Key Params: email: str

• When/How to Use: Use when a customer wants to see their recent order history or when you need to look up multiple orders for a customer. This is particularly useful for customers who can't remember specific order numbers.

• Example Prompt Instruction:

  If the user wants to see their recent orders or order history, ask for their email address. Once provided, call shopify_get_order_history with the email parameter to retrieve their most recent 5 orders with full details.

shopify_get_customer_by_email

• Purpose: Look up a Shopify customer by their email address.

• Key Params: email: str

• When/How to Use: Use when a user asks about their account, order history, or general customer information and provides their email address. Instruct the AI to request the email if needed.

• Example Prompt Instruction:

  If the user is asking about their customer account or looking for information related to orders associated with their account but has not provided an order number, you must ask for the email address associated with their account for verification. Once the user provides their email address, you must call shopify_get_customer_by_email with the provided email. Use the information returned to help the user with their account-related query.

shopify_get_product_variants

• Purpose: Retrieve all variants for specified product IDs, including size, color, and other variant options.

• Key Params: product_ids: List[str] - A list of product IDs to get variants for

• When/How to Use: Use when customers ask about available options for specific products, or when you need variant information for inventory or pricing queries.

• Example Prompt Instruction:

  When a user asks about available sizes, colors, or other options for a specific product, use shopify_get_product_variants with the product ID(s) to show all available variants and their details.

shopify_get_products

• Purpose: Retrieve product catalog information including titles, IDs, and tags. Returns up to 3 pages of products sorted by creation date.

• Key Params: None (retrieves all products)

• When/How to Use: Use when customers want to browse the product catalog, or when you need to find products by name or category before getting specific details.

• Example Prompt Instruction:

  If a user wants to browse available products or asks "what do you sell?", call shopify_get_products to retrieve the product catalog and present the available items.

shopify_get_fulfillment_for_order_id

• Purpose: Retrieve fulfillment and shipping information for a specific order ID.

• Key Params: order_id: str - The numeric order ID (e.g., "11607431610736")

• When/How to Use: Use when customers ask about shipping status, tracking information, or fulfillment details for their order.

• Example Prompt Instruction:

  When a user asks about shipping status or tracking information, first get their order using shopify_get_order_by_id, then use shopify_get_fulfillment_for_order_id with the order ID to get detailed fulfillment information.

shopify_get_variant_metafields

• Purpose: Fetch custom metafields for product variants, useful for accessing additional product data like specifications, custom attributes, or extended information.

• Key Params:

  • variant_ids: List[str] - List of variant IDs

  • namespace: str (optional) - Filter by metafield namespace

  • key: str (optional) - Filter by specific metafield key

  • type_: str (optional) - Filter by metafield type

  • limit: int (optional, default 50) - Results per page

  • max_pages: int (optional, default 1) - Maximum pages to fetch

• When/How to Use: Use when you need access to custom product variant data that's stored in metafields, such as technical specifications, care instructions, or custom attributes.

• Example Prompt Instruction:

  When users ask about detailed product specifications or custom attributes that aren't in the standard product data, use shopify_get_variant_metafields to access additional information stored in metafields.

shopify_get_product_metafields

• Purpose: Fetch custom metafields for products, providing access to additional product information beyond standard fields.

• Key Params:

  • product_ids: List[str] - List of product IDs

  • namespace: str (optional) - Filter by metafield namespace

  • key: str (optional) - Filter by specific metafield key

  • type_: str (optional) - Filter by metafield type

  • limit: int (optional, default 50) - Results per page

  • max_pages: int (optional, default 1) - Maximum pages to fetch

• When/How to Use: Use when you need to access custom product data stored in metafields, such as detailed descriptions, specifications, or custom business data.

• Example Prompt Instruction:

  For detailed product information beyond the standard fields, use shopify_get_product_metafields to retrieve custom data stored in metafields for the requested products.

shopify_search_products

• Purpose: Search the product catalog using GraphQL search API to find products matching specific search terms.

• Key Params:

  • search_query: str - Search terms (e.g., "brake pads", "red shirt", "iPhone case")

  • limit: int (optional, default 10, max 250) - Maximum results to return

• When/How to Use: Use when customers search for products by name, category, or description. More powerful than browsing all products as it uses Shopify's search capabilities.

• Example Prompt Instruction:

  When users search for specific products or ask about items by name/category, use shopify_search_products with their search terms to find matching products with details including pricing, availability, and images.

shopify_generate_carousel

• Purpose: Generate a product carousel using Shopify's public Storefront API. Can search for products or display specific products by ID. No authentication required.

• Key Params:

  • shop_name: str - Shopify shop name (e.g., "mystore" for mystore.myshopify.com)

  • search_query: str (optional) - Search term for products

  • product_ids: List[str] (optional) - Specific product IDs to display

  • limit: int (optional, default 6, max 20) - Maximum products for search results

• When/How to Use: Use to create visual product displays for customers, either based on search results or specific product recommendations.

• Example Prompt Instruction:

  To show customers a visual carousel of products, use shopify_generate_carousel with either a search query for discovery or specific product IDs for recommendations. This creates a rich UI display with images and purchase links.

shopify_create_return

• Purpose: Create a return merchandise authorization (RMA) for a specific order with selected line items.

• Key Params:

  • order_id: str - Shopify order ID

  • line_items: List[ReturnLineItem] - Items to return with fulfillmentLineItemId and quantity

  • reason: str (optional, default "UNKNOWN") - Return reason (COLOR, DEFECTIVE, NOT_AS_DESCRIBED, OTHER, SIZE_TOO_LARGE, SIZE_TOO_SMALL, STYLE, UNKNOWN, UNWANTED, WRONG_ITEM)

  • notify_customer: bool (optional, default False) - Whether to email customer

• When/How to Use: Use when customers want to return specific items from an order. Requires fulfillment line item IDs from the order details.

• Example Prompt Instruction:

  When a customer wants to return items, first get their order details, then use shopify_create_return with the specific line items they want to return and the reason for the return.

shopify_create_return_order

• Purpose: Create a 100% discounted replacement order for returned items, typically used in exchange scenarios.

• Key Params:

  • original_order_id: str - Original order being replaced

  • replacement_line_items: List[ReplacementOrderLineItem] - New items with variantId and quantity

  • customer_email: str - Customer's email address (required)

• When/How to Use: Use when processing exchanges or sending replacement items at no charge to the customer.

• Example Prompt Instruction:

  For product exchanges or free replacements, use shopify_create_return_order to create a fully discounted order with the replacement items for the customer.

shopify_refund_order

• Purpose: Process a full refund for a Shopify order with customer email validation for security.

• Key Params:

  • order_id: str - Order identifier (name like "#1001" or numeric ID)

  • customer_email: str - Customer email for validation

  • reason: str (optional, default "other") - Refund reason ("duplicate", "fraud", "other")

  • note: str (optional) - Note explaining the refund

  • notify_customer: bool (optional, default True) - Send email notification

• When/How to Use: Use when customers request refunds. Always validates that the order belongs to the provided email address for security.

• Example Prompt Instruction:

  For refund requests, use shopify_refund_order with both the order ID and customer email to securely process the full refund. The system will validate ownership before processing.

shopify_cancel_order

• Purpose: Cancel a Shopify order with customer email validation, optionally processing automatic refunds.

• Key Params:

  • order_id: str - Order identifier (name like "#1001" or numeric ID)

  • customer_email: str - Customer email for validation

  • reason: str (optional, default "customer") - Cancellation reason ("customer", "fraud", "inventory", "declined", "other")

  • send_notification: bool (optional, default True) - Send email notification

  • process_refund: bool (optional, default True) - Automatically refund paid orders

  • cancellation_note: str (optional) - Note explaining cancellation

• When/How to Use: Use when customers want to cancel unfulfilled orders. Cannot cancel already fulfilled orders - use refund instead.

• Example Prompt Instruction:

  For order cancellations, use shopify_cancel_order with the order ID and customer email. The system validates ownership and can automatically process refunds for paid orders. Use refund tool for already fulfilled orders.

We recommend using the “product search” action (see Customize > create new action > Shopify > product search).

This will allow the bot to use your Shopify to search for the product information instead, which enables real time information rather than indexing your pages via the web crawler.