Shopify Integration

The Shopify integration lets agents look up orders, manage customers, handle refunds, and manage products — directly from a conversation. Use it to build order support agents, product recommendation bots, or store management tools.

Authentication

Shopify uses a Custom App access token.

To create one:

1. Go to your Shopify Admin → Apps → Develop apps
2. Create a new app, then go to API credentials
3. Under Admin API access scopes, enable:
   • read_orders, write_orders — for order management
   • read_customers, write_customers — for customer management
   • read_products, write_products — for product management
   • read_inventory, write_inventory — for inventory updates
4. Click Install app, then copy the Admin API access token (shpat_...)

Field	Description
Store Domain	Your store URL without https:// (e.g. mystore.myshopify.com)
Access Token	Your Admin API access token starting with shpat_

Installing

1. Go to your project → Integrations → Browse
2. Find Shopify and click Install
3. Enter your Store Domain and Access Token
4. Select the actions you want to enable
5. Click Install

Actions

get_order — Get Order

Retrieves a single order by ID.

Tool reference: {{tool:shopify_get_order}}

Parameter	Required	Description
order_id	Yes	Shopify order ID (numeric)

Returns: Order details including line items, status, customer, totals, shipping address, and fulfillment status

---

list_orders — List Orders

Lists orders, optionally filtered by status.

Tool reference: {{tool:shopify_list_orders}}

Parameter	Required	Description
status	No	open, closed, cancelled, or any (default: any)
limit	No	Number to return (default 10, max 250)

Returns: Array of orders with order_id, order_number, status, total_price, created_at

---

update_order — Update Order

Updates editable order fields.

Tool reference: {{tool:shopify_update_order}}

Parameter	Required	Description
order_id	Yes	Order to update
note	No	Add or update the order note
tags	No	Comma-separated tags
email	No	Update the customer email

---

cancel_order — Cancel Order

Cancels an open order.

Tool reference: {{tool:shopify_cancel_order}}

Parameter	Required	Description
order_id	Yes	Order to cancel
reason	No	Cancellation reason: customer, fraud, inventory, declined, other
send_receipt	No	true to email the customer a cancellation receipt (default: true)

---

create_refund — Create Refund

Issues a refund for an order.

Tool reference: {{tool:shopify_create_refund}}

Parameter	Required	Description
order_id	Yes	Order to refund
amount	Yes	Refund amount (as a decimal, e.g. 29.99)
gateway	No	Payment gateway to refund through (defaults to the original)
note	No	Internal note for the refund
notify_customer	No	true to email the customer about the refund (default: true)

Returns: refund_id, amount, created_at

---

get_customer — Get Customer

Retrieves a customer by ID.

Tool reference: {{tool:shopify_get_customer}}

Parameter	Required	Description
customer_id	Yes	Shopify customer ID

Returns: Customer name, email, phone, order count, total spent, tags, and default address

---

create_customer — Create Customer

Creates a new customer record.

Tool reference: {{tool:shopify_create_customer}}

Parameter	Required	Description
email	Yes	Customer email address
first_name	No	First name
last_name	No	Last name
phone	No	Phone number
tags	No	Comma-separated customer tags

Returns: customer_id, created_at

---

update_customer — Update Customer

Updates a customer's profile.

Tool reference: {{tool:shopify_update_customer}}

Parameter	Required	Description
customer_id	Yes	Customer to update
first_name	No	New first name
last_name	No	New last name
email	No	New email
phone	No	New phone
note	No	Internal note
tags	No	New tags (replaces existing)

---

get_product — Get Product

Retrieves a product by ID.

Tool reference: {{tool:shopify_get_product}}

Parameter	Required	Description
product_id	Yes	Shopify product ID

---

list_products — List Products

Lists products with optional filters.

Tool reference: {{tool:shopify_list_products}}

Parameter	Required	Description
status	No	active, draft, or archived
title	No	Filter by product title (partial match)
limit	No	Number of results (default 10, max 250)

---

create_product — Create Product

Creates a new product.

Tool reference: {{tool:shopify_create_product}}

Parameter	Required	Description
title	Yes	Product name
description	No	Product description (HTML allowed)
vendor	No	Brand or vendor name
product_type	No	Product category
status	No	active, draft, or archived (default: draft)
price	No	Variant price as decimal
sku	No	Stock Keeping Unit
inventory_quantity	No	Initial stock quantity

---

update_product — Update Product

Updates a product's details.

Tool reference: {{tool:shopify_update_product}}

Parameter	Required	Description
product_id	Yes	Product to update
title	No	New title
description	No	New description
status	No	New status
tags	No	Comma-separated tags

---

update_inventory — Update Inventory

Sets the inventory level for a product variant at a location.

Tool reference: {{tool:shopify_update_inventory}}

Parameter	Required	Description
location_id	Yes	Shopify location ID
inventory_item_id	Yes	Inventory item ID (from product variant)
quantity	Yes	New stock quantity

---

Using Shopify in an agent

Order support agent

You are a customer support agent for an e-commerce store powered by Shopify.

When a customer asks about an order:
1. Ask for their order number (e.g. #1042) or their email.
2. Use {{tool:shopify_list_orders}} if searching by status, or
   {{tool:shopify_get_order}} if they have the order ID.
3. Share the order status, items ordered, and estimated delivery in friendly language.

When a customer wants to cancel an order:
- Confirm it's still in "open" status (not yet fulfilled)
- Use {{tool:shopify_cancel_order}} with reason "customer"
- Confirm: "Your order #[N] has been cancelled. You'll receive a confirmation email."

When a customer wants a refund:
- Verify the order and reason
- Use {{tool:shopify_create_refund}} with the appropriate amount
- Confirm: "A refund of $[amount] has been issued. It should appear within 3-5 business days."

Troubleshooting

401 Unauthorized

The access token is invalid or has been revoked. Regenerate in Shopify Admin → Apps → Develop apps.

404 Not Found

The order or product ID doesn't exist in this store. Check that store_domain is correct and the ID belongs to this store.

Missing API scopes

If an action fails with a permission error, the app is missing the required Admin API access scope. Edit the app in Shopify Admin, add the missing scope, and reinstall the app.

Refund fails

Refunds are only possible for paid orders. Check that the order has been paid and that the refund amount doesn't exceed the order total.