mcp-shopify-yoffi 1.1.0 → 1.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +711 -649
- package/dist/index.js +1 -1
- package/dist/lib/discountCodes/codeList.js +93 -0
- package/dist/lib/discountCodes/manage.js +194 -0
- package/dist/lib/discountCodes/runFile.js +87 -0
- package/dist/lib/discountCodes/shopify.js +331 -0
- package/dist/lib/discountCodes/snapshot.js +63 -0
- package/dist/lib/requestWithRetry.js +33 -0
- package/dist/tools/addDiscountCodes.js +354 -0
- package/dist/tools/deleteDiscounts.js +107 -0
- package/dist/tools/getDiscountCodes.js +213 -0
- package/dist/tools/manageDiscount.js +58 -0
- package/dist/tools/registry.js +11 -1
- package/dist/tools/removeDiscountCodes.js +355 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,649 +1,711 @@
|
|
|
1
|
-
# Shopify MCP Server (Yoffi Digital fork)
|
|
2
|
-
|
|
3
|
-
MCP Server for the Shopify Admin API, enabling interaction with store data through GraphQL. This server provides tools for managing products, customers, orders, discounts, and more.
|
|
4
|
-
|
|
5
|
-
This is a fork of [shopify-mcp](https://github.com/GeLi2001/shopify-mcp) by GeLi2001, extended by [Yoffi Digital](https://github.com/yoffi-digital) with discount-management tools (`create-discount`, `create-automatic-discount`) and other fixes.
|
|
6
|
-
|
|
7
|
-
## Features
|
|
8
|
-
|
|
9
|
-
- **Product Management**: Full CRUD for products, variants, and options (8 tools)
|
|
10
|
-
- **Customer Management**: Full CRUD, merge, and address management (8 tools)
|
|
11
|
-
- **Order Management**: Smart lookup, cancel, close/open, mark as paid, fulfillment, refunds (10 tools)
|
|
12
|
-
- **Metafield Management**: Get, set, and delete metafields on any resource (3 tools)
|
|
13
|
-
- **Inventory Management**: Set absolute inventory quantities at locations (1 tool)
|
|
14
|
-
- **Tag Management**: Add/remove tags on any taggable resource (1 tool)
|
|
15
|
-
- **Discount Management**: Create percentage or fixed-amount discount codes, store-wide or scoped to collections (
|
|
16
|
-
- **Translation Management**: List shop locales, read translatable content, and register or remove translations (4 tools)
|
|
17
|
-
- **Metaobject & File Management**: Read definitions, list/create/update/delete metaobject entries, search and upload files (6 tools)
|
|
18
|
-
- **Pagination & Sorting**: Cursor-based pagination and sort keys on all list queries
|
|
19
|
-
- **Advanced Filtering**: Pass-through Shopify query syntax for all list endpoints
|
|
20
|
-
- **GraphQL Integration**: Direct integration with Shopify's GraphQL Admin API (2026-
|
|
21
|
-
- **Comprehensive Error Handling**: Clear error messages for API and authentication issues
|
|
22
|
-
|
|
23
|
-
## Prerequisites
|
|
24
|
-
|
|
25
|
-
1. Node.js (version 18 or higher)
|
|
26
|
-
2. A Shopify store with a custom app (see setup instructions below)
|
|
27
|
-
|
|
28
|
-
## Setup
|
|
29
|
-
|
|
30
|
-
### Authentication
|
|
31
|
-
|
|
32
|
-
This server supports two authentication methods:
|
|
33
|
-
|
|
34
|
-
#### Option 1: Client Credentials (Dev Dashboard apps, January 2026+)
|
|
35
|
-
|
|
36
|
-
As of January 1, 2026, new Shopify apps are created in the **Dev Dashboard** and use OAuth client credentials instead of static access tokens.
|
|
37
|
-
|
|
38
|
-
1. From your Shopify admin, go to **Settings** > **Apps and sales channels**
|
|
39
|
-
2. Click **Develop apps** > **Build app in dev dashboard**
|
|
40
|
-
3. Create a new app and configure **Admin API scopes**:
|
|
41
|
-
- `read_products`, `write_products`
|
|
42
|
-
- `read_customers`, `write_customers`
|
|
43
|
-
- `read_orders`, `write_orders`
|
|
44
|
-
- `read_locales`, `read_translations`, `write_translations` (for the translation tools)
|
|
45
|
-
- `read_metaobject_definitions`, `read_metaobjects`, `write_metaobjects`, `read_files`, `write_files` (for the metaobject and file tools)
|
|
46
|
-
4. Install the app on your store
|
|
47
|
-
5. Copy your **Client ID** and **Client Secret** from the app's API credentials
|
|
48
|
-
|
|
49
|
-
The server will automatically exchange these for an access token and refresh it before it expires (tokens are valid for ~24 hours).
|
|
50
|
-
|
|
51
|
-
#### Option 2: Static Access Token (legacy apps)
|
|
52
|
-
|
|
53
|
-
If you have an existing custom app with a static `shpat_` access token, you can still use it directly.
|
|
54
|
-
|
|
55
|
-
This package is not currently published to npm — clone the repo and build it locally:
|
|
56
|
-
|
|
57
|
-
```bash
|
|
58
|
-
git clone https://github.com/yoffi-digital/mcp-shopify-yoffi.git
|
|
59
|
-
cd mcp-shopify-yoffi
|
|
60
|
-
npm install
|
|
61
|
-
npm run build
|
|
62
|
-
```
|
|
63
|
-
|
|
64
|
-
This produces `dist/index.js`, which the commands below reference directly.
|
|
65
|
-
|
|
66
|
-
### Usage with Claude Desktop
|
|
67
|
-
|
|
68
|
-
**Client Credentials (recommended):**
|
|
69
|
-
|
|
70
|
-
```json
|
|
71
|
-
{
|
|
72
|
-
"mcpServers": {
|
|
73
|
-
"shopify": {
|
|
74
|
-
"command": "node",
|
|
75
|
-
"args": [
|
|
76
|
-
"/absolute/path/to/mcp-shopify-yoffi/dist/index.js",
|
|
77
|
-
"--clientId",
|
|
78
|
-
"<YOUR_CLIENT_ID>",
|
|
79
|
-
"--clientSecret",
|
|
80
|
-
"<YOUR_CLIENT_SECRET>",
|
|
81
|
-
"--domain",
|
|
82
|
-
"<YOUR_SHOP>.myshopify.com"
|
|
83
|
-
]
|
|
84
|
-
}
|
|
85
|
-
}
|
|
86
|
-
}
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
**Static Access Token (legacy):**
|
|
90
|
-
|
|
91
|
-
```json
|
|
92
|
-
{
|
|
93
|
-
"mcpServers": {
|
|
94
|
-
"shopify": {
|
|
95
|
-
"command": "node",
|
|
96
|
-
"args": [
|
|
97
|
-
"/absolute/path/to/mcp-shopify-yoffi/dist/index.js",
|
|
98
|
-
"--accessToken",
|
|
99
|
-
"<YOUR_ACCESS_TOKEN>",
|
|
100
|
-
"--domain",
|
|
101
|
-
"<YOUR_SHOP>.myshopify.com"
|
|
102
|
-
]
|
|
103
|
-
}
|
|
104
|
-
}
|
|
105
|
-
}
|
|
106
|
-
```
|
|
107
|
-
|
|
108
|
-
Locations for the Claude Desktop config file:
|
|
109
|
-
|
|
110
|
-
- MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
111
|
-
- Windows: `%APPDATA%/Claude/claude_desktop_config.json`
|
|
112
|
-
|
|
113
|
-
### Usage with Claude Code
|
|
114
|
-
|
|
115
|
-
**Client Credentials:**
|
|
116
|
-
|
|
117
|
-
```bash
|
|
118
|
-
claude mcp add shopify -- node /absolute/path/to/mcp-shopify-yoffi/dist/index.js \
|
|
119
|
-
--clientId YOUR_CLIENT_ID \
|
|
120
|
-
--clientSecret YOUR_CLIENT_SECRET \
|
|
121
|
-
--domain your-store.myshopify.com
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
**Static Access Token (legacy):**
|
|
125
|
-
|
|
126
|
-
```bash
|
|
127
|
-
claude mcp add shopify -- node /absolute/path/to/mcp-shopify-yoffi/dist/index.js \
|
|
128
|
-
--accessToken YOUR_ACCESS_TOKEN \
|
|
129
|
-
--domain your-store.myshopify.com
|
|
130
|
-
```
|
|
131
|
-
|
|
132
|
-
### Alternative: Run Locally with Environment Variables
|
|
133
|
-
|
|
134
|
-
If you prefer to use environment variables instead of command-line arguments:
|
|
135
|
-
|
|
136
|
-
1. Create a `.env` file with your Shopify credentials:
|
|
137
|
-
|
|
138
|
-
**Client Credentials:**
|
|
139
|
-
```
|
|
140
|
-
SHOPIFY_CLIENT_ID=your_client_id
|
|
141
|
-
SHOPIFY_CLIENT_SECRET=your_client_secret
|
|
142
|
-
MYSHOPIFY_DOMAIN=your-store.myshopify.com
|
|
143
|
-
```
|
|
144
|
-
|
|
145
|
-
**Static Access Token (legacy):**
|
|
146
|
-
```
|
|
147
|
-
SHOPIFY_ACCESS_TOKEN=your_access_token
|
|
148
|
-
MYSHOPIFY_DOMAIN=your-store.myshopify.com
|
|
149
|
-
```
|
|
150
|
-
|
|
151
|
-
2. Run the server:
|
|
152
|
-
```
|
|
153
|
-
node dist/index.js
|
|
154
|
-
```
|
|
155
|
-
|
|
156
|
-
### Additional Options
|
|
157
|
-
|
|
158
|
-
- `--apiVersion`: Specify the Shopify API version (default: `2026-
|
|
159
|
-
|
|
160
|
-
## Available Tools (32)
|
|
161
|
-
|
|
162
|
-
### Pagination, Sorting & Filtering
|
|
163
|
-
|
|
164
|
-
All list query tools (`get-products`, `get-customers`, `get-orders`, `get-customer-orders`) support:
|
|
165
|
-
|
|
166
|
-
- **Cursor-based pagination**: `after` / `before` (cursor strings), with `pageInfo` in the response (`hasNextPage`, `hasPreviousPage`, `startCursor`, `endCursor`)
|
|
167
|
-
- **Sorting**: `sortKey` (enum specific to each resource) and `reverse` (boolean)
|
|
168
|
-
- **Advanced filtering**: `query` or `searchQuery` parameter accepting [Shopify query syntax](https://shopify.dev/docs/api/usage/search-syntax)
|
|
169
|
-
|
|
170
|
-
### Product Management (8 tools)
|
|
171
|
-
|
|
172
|
-
1. **`get-products`**
|
|
173
|
-
|
|
174
|
-
- Get all products or search by title with pagination and sorting
|
|
175
|
-
- Inputs:
|
|
176
|
-
- `searchTitle` (string, optional): Filter products by title (wraps in `title:*...*`)
|
|
177
|
-
- `limit` (number, default: 10): Maximum number of products to return
|
|
178
|
-
- `query` (string, optional): Raw Shopify query string (e.g. `"status:active vendor:Nike tag:sale"`)
|
|
179
|
-
- `sortKey` (string, optional): One of `CREATED_AT`, `ID`, `INVENTORY_TOTAL`, `PRODUCT_TYPE`, `PUBLISHED_AT`, `RELEVANCE`, `TITLE`, `UPDATED_AT`, `VENDOR`
|
|
180
|
-
- `reverse` (boolean, optional): Reverse the sort order
|
|
181
|
-
- `after` / `before` (string, optional): Pagination cursors
|
|
182
|
-
|
|
183
|
-
2. **`get-product-by-id`**
|
|
184
|
-
|
|
185
|
-
- Get a specific product by ID with full details including SEO, options, media, variants, and collections
|
|
186
|
-
- Inputs:
|
|
187
|
-
- `productId` (string, required): Shopify product GID
|
|
188
|
-
- Returns: `productType`, `descriptionHtml`, `seo`, `options` (with `optionValues`), `media` (images), `variants`, `collections`, `tags`, `vendor`, price range, inventory
|
|
189
|
-
|
|
190
|
-
3. **`create-product`**
|
|
191
|
-
|
|
192
|
-
- Create a new product. When using `productOptions`, Shopify registers all option values but only creates one default variant (first value of each option, price $0). Use `manage-product-variants` with `strategy: REMOVE_STANDALONE_VARIANT` afterward to create all real variants with prices.
|
|
193
|
-
- Inputs:
|
|
194
|
-
- `title` (string, required): Title of the product
|
|
195
|
-
- `descriptionHtml` (string, optional): Description with HTML
|
|
196
|
-
- `handle` (string, optional): URL slug. Auto-generated from title if omitted
|
|
197
|
-
- `vendor` (string, optional): Vendor of the product
|
|
198
|
-
- `productType` (string, optional): Type of the product
|
|
199
|
-
- `tags` (array of strings, optional): Product tags
|
|
200
|
-
- `status` (string, optional): `"ACTIVE"`, `"DRAFT"`, or `"ARCHIVED"`. Default `"DRAFT"`
|
|
201
|
-
- `seo` (object, optional): `{ title, description }` for search engines
|
|
202
|
-
- `metafields` (array of objects, optional): Custom metafields (`namespace`, `key`, `value`, `type`)
|
|
203
|
-
- `productOptions` (array of objects, optional): Options to create inline, e.g. `[{ name: "Size", values: [{ name: "S" }, { name: "M" }] }]`. Max 3 options.
|
|
204
|
-
- `collectionsToJoin` (array of strings, optional): Collection GIDs to add the product to
|
|
205
|
-
|
|
206
|
-
4. **`update-product`**
|
|
207
|
-
|
|
208
|
-
- Update an existing product's fields
|
|
209
|
-
- Inputs:
|
|
210
|
-
- `id` (string, required): Shopify product GID
|
|
211
|
-
- `title` (string, optional): New title
|
|
212
|
-
- `descriptionHtml` (string, optional): New description
|
|
213
|
-
- `handle` (string, optional): New URL slug
|
|
214
|
-
- `vendor` (string, optional): New vendor
|
|
215
|
-
- `productType` (string, optional): New product type
|
|
216
|
-
- `tags` (array of strings, optional): New tags (overwrites existing)
|
|
217
|
-
- `status` (string, optional): `"ACTIVE"`, `"DRAFT"`, or `"ARCHIVED"`
|
|
218
|
-
- `seo` (object, optional): `{ title, description }` for search engines
|
|
219
|
-
- `metafields` (array of objects, optional): Metafields to set or update
|
|
220
|
-
- `collectionsToJoin` (array of strings, optional): Collection GIDs to add the product to
|
|
221
|
-
- `collectionsToLeave` (array of strings, optional): Collection GIDs to remove the product from
|
|
222
|
-
- `redirectNewHandle` (boolean, optional): If true, old handle redirects to new handle
|
|
223
|
-
|
|
224
|
-
5. **`delete-product`**
|
|
225
|
-
|
|
226
|
-
- Delete a product
|
|
227
|
-
- Inputs:
|
|
228
|
-
- `id` (string, required): Shopify product GID
|
|
229
|
-
|
|
230
|
-
6. **`manage-product-options`**
|
|
231
|
-
|
|
232
|
-
- Create, update, or delete product options (e.g. Size, Color)
|
|
233
|
-
- Inputs:
|
|
234
|
-
- `productId` (string, required): Shopify product GID
|
|
235
|
-
- `action` (string, required): `"create"`, `"update"`, or `"delete"`
|
|
236
|
-
- `variantStrategy` (string, optional): `"LEAVE_AS_IS"` (default) or `"CREATE"` — controls whether new variant combinations are generated when adding options
|
|
237
|
-
- For `action: "create"`:
|
|
238
|
-
- `options` (array, required): Options to create, e.g. `[{ name: "Size", values: ["S", "M", "L"] }]`
|
|
239
|
-
- For `action: "update"`:
|
|
240
|
-
- `optionId` (string, required): Option GID to update
|
|
241
|
-
- `name` (string, optional): New name for the option
|
|
242
|
-
- `position` (number, optional): New position
|
|
243
|
-
- `valuesToAdd` (array of strings, optional): Values to add
|
|
244
|
-
- `valuesToDelete` (array of strings, optional): Value GIDs to remove
|
|
245
|
-
- For `action: "delete"`:
|
|
246
|
-
- `optionIds` (array of strings, required): Option GIDs to delete
|
|
247
|
-
|
|
248
|
-
7. **`manage-product-variants`**
|
|
249
|
-
|
|
250
|
-
- Create or update product variants in bulk
|
|
251
|
-
- Inputs:
|
|
252
|
-
- `productId` (string, required): Shopify product GID
|
|
253
|
-
- `strategy` (string, optional): How to handle the default variant when creating. `"DEFAULT"` (removes "Default Title" automatically), `"REMOVE_STANDALONE_VARIANT"` (recommended for full control), or `"PRESERVE_STANDALONE_VARIANT"`
|
|
254
|
-
- `variants` (array, required): Variants to create or update. Each variant:
|
|
255
|
-
- `id` (string, optional): Variant GID for updates. Omit to create new
|
|
256
|
-
- `price` (string, optional): Price, e.g. `"49.00"`
|
|
257
|
-
- `compareAtPrice` (string, optional): Compare-at price for showing discounts
|
|
258
|
-
- `sku` (string, optional): SKU (mapped to `inventoryItem.sku`)
|
|
259
|
-
- `tracked` (boolean, optional): Whether inventory is tracked. Set `false` for print-on-demand
|
|
260
|
-
- `taxable` (boolean, optional): Whether the variant is taxable
|
|
261
|
-
- `barcode` (string, optional): Barcode
|
|
262
|
-
- `weight` (number, optional): Weight of the variant
|
|
263
|
-
- `weightUnit` (string, optional): `"GRAMS"`, `"KILOGRAMS"`, `"OUNCES"`, or `"POUNDS"`
|
|
264
|
-
- `optionValues` (array, optional): Option values, e.g. `[{ optionName: "Size", name: "A4" }]`
|
|
265
|
-
|
|
266
|
-
8. **`delete-product-variants`**
|
|
267
|
-
|
|
268
|
-
- Delete one or more variants from a product
|
|
269
|
-
- Inputs:
|
|
270
|
-
- `productId` (string, required): Shopify product GID
|
|
271
|
-
- `variantIds` (array of strings, required): Variant GIDs to delete
|
|
272
|
-
|
|
273
|
-
### Customer Management (8 tools)
|
|
274
|
-
|
|
275
|
-
1. **`get-customers`**
|
|
276
|
-
|
|
277
|
-
- List customers with search, pagination, and sorting
|
|
278
|
-
- Inputs:
|
|
279
|
-
- `searchQuery` (string, optional): Freetext or Shopify query syntax (e.g. `"country:US tag:vip orders_count:>5"`)
|
|
280
|
-
- `limit` (number, default: 10): Maximum number of customers to return
|
|
281
|
-
- `sortKey` (string, optional): One of `CREATED_AT`, `ID`, `LAST_UPDATE`, `LOCATION`, `NAME`, `ORDERS_COUNT`, `RELEVANCE`, `TOTAL_SPENT`, `UPDATED_AT`
|
|
282
|
-
- `reverse` (boolean, optional): Reverse the sort order
|
|
283
|
-
- `after` / `before` (string, optional): Pagination cursors
|
|
284
|
-
|
|
285
|
-
2. **`get-customer-by-id`**
|
|
286
|
-
|
|
287
|
-
- Get a single customer by ID with full details
|
|
288
|
-
- Inputs:
|
|
289
|
-
- `id` (string, required): Shopify customer ID (numeric only, e.g. `"6276879810626"`)
|
|
290
|
-
- Returns: name, email, phone, addresses, tags, note, tax status, amount spent, order count, metafields
|
|
291
|
-
|
|
292
|
-
3. **`create-customer`**
|
|
293
|
-
|
|
294
|
-
- Create a new customer
|
|
295
|
-
- Inputs:
|
|
296
|
-
- `firstName` (string, optional): Customer's first name
|
|
297
|
-
- `lastName` (string, optional): Customer's last name
|
|
298
|
-
- `email` (string, optional): Customer's email address
|
|
299
|
-
- `phone` (string, optional): Customer's phone number
|
|
300
|
-
- `tags` (array of strings, optional): Tags to apply
|
|
301
|
-
- `note` (string, optional): Note about the customer
|
|
302
|
-
- `taxExempt` (boolean, optional): Whether the customer is exempt from taxes
|
|
303
|
-
- `metafields` (array of objects, optional): Custom metafields (`namespace`, `key`, `value`, `type`)
|
|
304
|
-
- `addresses` (array of objects, optional): Customer addresses (`address1`, `address2`, `city`, `provinceCode`, `zip`, `country`, `phone`)
|
|
305
|
-
|
|
306
|
-
4. **`update-customer`**
|
|
307
|
-
|
|
308
|
-
- Update a customer's information
|
|
309
|
-
- Inputs:
|
|
310
|
-
- `id` (string, required): Shopify customer ID (numeric only, e.g. `"6276879810626"`)
|
|
311
|
-
- `firstName` (string, optional): Customer's first name
|
|
312
|
-
- `lastName` (string, optional): Customer's last name
|
|
313
|
-
- `email` (string, optional): Customer's email address
|
|
314
|
-
- `phone` (string, optional): Customer's phone number
|
|
315
|
-
- `tags` (array of strings, optional): Tags to apply to the customer
|
|
316
|
-
- `note` (string, optional): Note about the customer
|
|
317
|
-
- `taxExempt` (boolean, optional): Whether the customer is exempt from taxes
|
|
318
|
-
- `emailMarketingConsent` (object, optional): Email marketing consent settings
|
|
319
|
-
- `marketingState` (string, required): `"NOT_SUBSCRIBED"`, `"SUBSCRIBED"`, `"UNSUBSCRIBED"`, or `"PENDING"`
|
|
320
|
-
- `consentUpdatedAt` (string, optional): ISO 8601 timestamp
|
|
321
|
-
- `marketingOptInLevel` (string, optional): `"SINGLE_OPT_IN"`, `"CONFIRMED_OPT_IN"`, or `"UNKNOWN"`
|
|
322
|
-
- `metafields` (array of objects, optional): Customer metafields
|
|
323
|
-
|
|
324
|
-
5. **`delete-customer`**
|
|
325
|
-
|
|
326
|
-
- Delete a customer
|
|
327
|
-
- Inputs:
|
|
328
|
-
- `id` (string, required): Shopify customer ID (numeric only, e.g. `"6276879810626"`)
|
|
329
|
-
|
|
330
|
-
6. **`customer-merge`**
|
|
331
|
-
|
|
332
|
-
- Merge two customer records into one
|
|
333
|
-
- Inputs:
|
|
334
|
-
- `customerOneId` (string, required): GID of the first customer
|
|
335
|
-
- `customerTwoId` (string, required): GID of the second customer
|
|
336
|
-
- `overrideFields` (object, optional): Override which fields to keep from which customer (firstName, lastName, email, phone, defaultAddress, note, tags)
|
|
337
|
-
|
|
338
|
-
7. **`manage-customer-address`**
|
|
339
|
-
|
|
340
|
-
- Create, update, or delete a customer's mailing address
|
|
341
|
-
- Inputs:
|
|
342
|
-
- `customerId` (string, required): Customer GID
|
|
343
|
-
- `action` (string, required): `"create"`, `"update"`, or `"delete"`
|
|
344
|
-
- `addressId` (string, optional): Address GID (required for update/delete)
|
|
345
|
-
- `address` (object, optional): Address fields (required for create/update): `address1`, `address2`, `city`, `company`, `countryCode`, `firstName`, `lastName`, `phone`, `provinceCode`, `zip`
|
|
346
|
-
- `setAsDefault` (boolean, optional): Set as customer's default address
|
|
347
|
-
|
|
348
|
-
### Order Management (10 tools)
|
|
349
|
-
|
|
350
|
-
1. **`get-orders`**
|
|
351
|
-
|
|
352
|
-
- Get orders with filtering, pagination, and sorting
|
|
353
|
-
- Inputs:
|
|
354
|
-
- `status` (string, optional): `"any"`, `"open"`, `"closed"`, or `"cancelled"`. Default `"any"`
|
|
355
|
-
- `limit` (number, default: 10): Maximum number of orders to return
|
|
356
|
-
- `query` (string, optional): Raw Shopify query string (e.g. `"financial_status:paid fulfillment_status:shipped tag:rush"`)
|
|
357
|
-
- `sortKey` (string, optional): One of `CREATED_AT`, `ORDER_NUMBER`, `TOTAL_PRICE`, `FINANCIAL_STATUS`, `FULFILLMENT_STATUS`, `UPDATED_AT`, `CUSTOMER_NAME`, `PROCESSED_AT`, `ID`, `RELEVANCE`
|
|
358
|
-
- `reverse` (boolean, optional): Reverse the sort order
|
|
359
|
-
- `after` / `before` (string, optional): Pagination cursors
|
|
360
|
-
|
|
361
|
-
2. **`get-order-by-id`**
|
|
362
|
-
|
|
363
|
-
- Get a specific order by ID with smart lookup — accepts order name (`#77235` or `77235`), numeric ID (`8054938337547`), or full GID (`gid://shopify/Order/...`)
|
|
364
|
-
- Inputs:
|
|
365
|
-
- `orderId` (string, required): Order name, numeric ID, or full GID
|
|
366
|
-
- Returns: pricing, customer, shipping/billing addresses, line items, tags, notes, metafields, cancel reason, return status, discount codes, PO number, timestamps
|
|
367
|
-
|
|
368
|
-
3. **`update-order`**
|
|
369
|
-
|
|
370
|
-
- Update an existing order
|
|
371
|
-
- Inputs:
|
|
372
|
-
- `id` (string, required): Shopify order GID
|
|
373
|
-
- `tags` (array of strings, optional): New tags for the order
|
|
374
|
-
- `email` (string, optional): Update customer email on the order
|
|
375
|
-
- `note` (string, optional): Order notes
|
|
376
|
-
- `phone` (string, optional): Phone number for the order
|
|
377
|
-
- `poNumber` (string, optional): Purchase order number
|
|
378
|
-
- `customAttributes` (array of objects, optional): Custom key-value attributes
|
|
379
|
-
- `metafields` (array of objects, optional): Order metafields
|
|
380
|
-
- `shippingAddress` (object, optional): Shipping address fields
|
|
381
|
-
|
|
382
|
-
4. **`get-customer-orders`**
|
|
383
|
-
|
|
384
|
-
- Get orders for a specific customer with pagination and sorting
|
|
385
|
-
- Inputs:
|
|
386
|
-
- `customerId` (string, required): Shopify customer ID (numeric only, e.g. `"6276879810626"`)
|
|
387
|
-
- `limit` (number, default: 10): Maximum number of orders to return
|
|
388
|
-
- `sortKey` (string, optional): Same sort keys as `get-orders`
|
|
389
|
-
- `reverse` (boolean, optional): Reverse the sort order
|
|
390
|
-
- `after` / `before` (string, optional): Pagination cursors
|
|
391
|
-
|
|
392
|
-
5. **`order-cancel`**
|
|
393
|
-
|
|
394
|
-
- Cancel an order with options for refunding, restocking, and customer notification. **Irreversible.**
|
|
395
|
-
- Inputs:
|
|
396
|
-
- `orderId` (string, required): Order GID
|
|
397
|
-
- `reason` (string, required): `"CUSTOMER"`, `"DECLINED"`, `"FRAUD"`, `"INVENTORY"`, `"OTHER"`, or `"STAFF"`
|
|
398
|
-
- `restock` (boolean, required): Whether to restock inventory
|
|
399
|
-
- `notifyCustomer` (boolean, default: false): Notify the customer
|
|
400
|
-
- `staffNote` (string, optional): Internal note
|
|
401
|
-
- `refund` (boolean, optional): Refund to original payment method
|
|
402
|
-
|
|
403
|
-
6. **`order-close-open`**
|
|
404
|
-
|
|
405
|
-
- Close or reopen an order
|
|
406
|
-
- Inputs:
|
|
407
|
-
- `orderId` (string, required): Order GID
|
|
408
|
-
- `action` (string, required): `"close"` or `"open"`
|
|
409
|
-
|
|
410
|
-
7. **`order-mark-as-paid`**
|
|
411
|
-
|
|
412
|
-
- Mark an order as paid (for manual/offline payments)
|
|
413
|
-
- Inputs:
|
|
414
|
-
- `orderId` (string, required): Order GID
|
|
415
|
-
|
|
416
|
-
8. **`create-fulfillment`**
|
|
417
|
-
|
|
418
|
-
- Create a fulfillment (mark items as shipped) with optional tracking
|
|
419
|
-
- Inputs:
|
|
420
|
-
- `lineItemsByFulfillmentOrder` (array, required): Fulfillment orders and line items to fulfill
|
|
421
|
-
- `trackingInfo` (object, optional): `{ number, url, company }` tracking details
|
|
422
|
-
- `notifyCustomer` (boolean, default: false): Send shipping notification
|
|
423
|
-
|
|
424
|
-
9. **`refund-create`**
|
|
425
|
-
|
|
426
|
-
- Create a full or partial refund with optional restocking
|
|
427
|
-
- Inputs:
|
|
428
|
-
- `orderId` (string, required): Order GID
|
|
429
|
-
- `refundLineItems` (array, optional): Line items to refund with `lineItemId`, `quantity`, `restockType` (`CANCEL`/`RETURN`/`NO_RESTOCK`), `locationId`
|
|
430
|
-
- `shipping` (object, optional): `{ amount, fullRefund }` shipping refund
|
|
431
|
-
- `note` (string, optional): Refund note
|
|
432
|
-
- `notify` (boolean, optional): Send refund notification
|
|
433
|
-
|
|
434
|
-
10. **`create-draft-order`**
|
|
435
|
-
|
|
436
|
-
- Create a draft order for phone/chat sales, invoicing, or wholesale
|
|
437
|
-
- Inputs:
|
|
438
|
-
- `lineItems` (array, required): Product variants (`variantId`) or custom items (`title` + price). Max 499
|
|
439
|
-
- `customerId` (string, optional): Customer GID
|
|
440
|
-
- `email`, `phone`, `note`, `tags`, `poNumber` (optional)
|
|
441
|
-
- `shippingAddress`, `billingAddress` (objects, optional)
|
|
442
|
-
- `appliedDiscount` (object, optional): `{ title, value, valueType }` order-level discount
|
|
443
|
-
|
|
444
|
-
### Draft Order Management (1 tool)
|
|
445
|
-
|
|
446
|
-
1. **`complete-draft-order`**
|
|
447
|
-
|
|
448
|
-
- Complete a draft order, converting it into a real order
|
|
449
|
-
- Inputs:
|
|
450
|
-
- `draftOrderId` (string, required): Draft order GID
|
|
451
|
-
- `paymentGatewayId` (string, optional): Payment gateway GID
|
|
452
|
-
|
|
453
|
-
### Metafield Management (3 tools)
|
|
454
|
-
|
|
455
|
-
1. **`get-metafields`**
|
|
456
|
-
|
|
457
|
-
- Get metafields for any Shopify resource (products, orders, customers, variants, collections, etc.)
|
|
458
|
-
- Inputs:
|
|
459
|
-
- `ownerId` (string, required): GID of any resource
|
|
460
|
-
- `namespace` (string, optional): Filter by namespace
|
|
461
|
-
- `first` (number, default: 25): Number of metafields to return
|
|
462
|
-
- `after` (string, optional): Pagination cursor
|
|
463
|
-
|
|
464
|
-
2. **`set-metafields`**
|
|
465
|
-
|
|
466
|
-
- Set metafields on any Shopify resource. Creates or updates up to 25 metafields atomically
|
|
467
|
-
- Inputs:
|
|
468
|
-
- `metafields` (array, required): Metafields to set, each with `ownerId`, `key`, `value`, and optional `namespace`, `type`
|
|
469
|
-
|
|
470
|
-
3. **`delete-metafields`**
|
|
471
|
-
|
|
472
|
-
- Delete metafields from any Shopify resource
|
|
473
|
-
- Inputs:
|
|
474
|
-
- `metafields` (array, required): Metafields to delete, each with `ownerId`, `namespace`, `key`
|
|
475
|
-
|
|
476
|
-
### Inventory Management (1 tool)
|
|
477
|
-
|
|
478
|
-
1. **`inventory-set-quantities`**
|
|
479
|
-
|
|
480
|
-
- Set absolute inventory quantities for items at specific locations
|
|
481
|
-
- Inputs:
|
|
482
|
-
- `reason` (string, required): Reason for change (e.g. `"correction"`, `"cycle_count_available"`)
|
|
483
|
-
- `name` (string, required): `"available"` or `"on_hand"`
|
|
484
|
-
- `quantities` (array, required): Items with `inventoryItemId`, `locationId`, `quantity`
|
|
485
|
-
|
|
486
|
-
### Tag Management (1 tool)
|
|
487
|
-
|
|
488
|
-
1. **`manage-tags`**
|
|
489
|
-
|
|
490
|
-
- Add or remove tags on any taggable resource (orders, products, customers, draft orders, articles)
|
|
491
|
-
- Inputs:
|
|
492
|
-
- `id` (string, required): GID of the resource
|
|
493
|
-
- `tags` (array of strings, required): Tags to add or remove
|
|
494
|
-
- `action` (string, required): `"add"` or `"remove"`
|
|
495
|
-
|
|
496
|
-
### Discount Management (
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
- `
|
|
507
|
-
- `
|
|
508
|
-
- `
|
|
509
|
-
- `
|
|
510
|
-
- `
|
|
511
|
-
- `
|
|
512
|
-
- `
|
|
513
|
-
- `
|
|
514
|
-
- `
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
- `
|
|
525
|
-
- `
|
|
526
|
-
- `
|
|
527
|
-
- `
|
|
528
|
-
- `
|
|
529
|
-
- `
|
|
530
|
-
- `
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
-
|
|
539
|
-
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
- `
|
|
547
|
-
- `
|
|
548
|
-
- `
|
|
549
|
-
- `
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
-
|
|
558
|
-
|
|
559
|
-
- `
|
|
560
|
-
- `
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
-
|
|
566
|
-
|
|
567
|
-
- `
|
|
568
|
-
- `
|
|
569
|
-
- `
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
- `
|
|
580
|
-
- `
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
-
|
|
585
|
-
- Inputs:
|
|
586
|
-
- `
|
|
587
|
-
- `
|
|
588
|
-
- `
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
-
|
|
608
|
-
|
|
609
|
-
- `
|
|
610
|
-
- `
|
|
611
|
-
- `
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
|
|
618
|
-
|
|
619
|
-
|
|
620
|
-
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
636
|
-
|
|
637
|
-
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
|
|
642
|
-
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
1
|
+
# Shopify MCP Server (Yoffi Digital fork)
|
|
2
|
+
|
|
3
|
+
MCP Server for the Shopify Admin API, enabling interaction with store data through GraphQL. This server provides tools for managing products, customers, orders, discounts, and more.
|
|
4
|
+
|
|
5
|
+
This is a fork of [shopify-mcp](https://github.com/GeLi2001/shopify-mcp) by GeLi2001, extended by [Yoffi Digital](https://github.com/yoffi-digital) with discount-management tools (`create-discount`, `create-automatic-discount`) and other fixes.
|
|
6
|
+
|
|
7
|
+
## Features
|
|
8
|
+
|
|
9
|
+
- **Product Management**: Full CRUD for products, variants, and options (8 tools)
|
|
10
|
+
- **Customer Management**: Full CRUD, merge, and address management (8 tools)
|
|
11
|
+
- **Order Management**: Smart lookup, cancel, close/open, mark as paid, fulfillment, refunds (10 tools)
|
|
12
|
+
- **Metafield Management**: Get, set, and delete metafields on any resource (3 tools)
|
|
13
|
+
- **Inventory Management**: Set absolute inventory quantities at locations (1 tool)
|
|
14
|
+
- **Tag Management**: Add/remove tags on any taggable resource (1 tool)
|
|
15
|
+
- **Discount Management**: Create percentage or fixed-amount discount codes, store-wide or scoped to collections, bulk-attach thousands of codes to an existing discount, pause/reschedule/delete discounts, export or remove codes (7 tools)
|
|
16
|
+
- **Translation Management**: List shop locales, read translatable content, and register or remove translations (4 tools)
|
|
17
|
+
- **Metaobject & File Management**: Read definitions, list/create/update/delete metaobject entries, search and upload files (6 tools)
|
|
18
|
+
- **Pagination & Sorting**: Cursor-based pagination and sort keys on all list queries
|
|
19
|
+
- **Advanced Filtering**: Pass-through Shopify query syntax for all list endpoints
|
|
20
|
+
- **GraphQL Integration**: Direct integration with Shopify's GraphQL Admin API (2026-07)
|
|
21
|
+
- **Comprehensive Error Handling**: Clear error messages for API and authentication issues
|
|
22
|
+
|
|
23
|
+
## Prerequisites
|
|
24
|
+
|
|
25
|
+
1. Node.js (version 18 or higher)
|
|
26
|
+
2. A Shopify store with a custom app (see setup instructions below)
|
|
27
|
+
|
|
28
|
+
## Setup
|
|
29
|
+
|
|
30
|
+
### Authentication
|
|
31
|
+
|
|
32
|
+
This server supports two authentication methods:
|
|
33
|
+
|
|
34
|
+
#### Option 1: Client Credentials (Dev Dashboard apps, January 2026+)
|
|
35
|
+
|
|
36
|
+
As of January 1, 2026, new Shopify apps are created in the **Dev Dashboard** and use OAuth client credentials instead of static access tokens.
|
|
37
|
+
|
|
38
|
+
1. From your Shopify admin, go to **Settings** > **Apps and sales channels**
|
|
39
|
+
2. Click **Develop apps** > **Build app in dev dashboard**
|
|
40
|
+
3. Create a new app and configure **Admin API scopes**:
|
|
41
|
+
- `read_products`, `write_products`
|
|
42
|
+
- `read_customers`, `write_customers`
|
|
43
|
+
- `read_orders`, `write_orders`
|
|
44
|
+
- `read_locales`, `read_translations`, `write_translations` (for the translation tools)
|
|
45
|
+
- `read_metaobject_definitions`, `read_metaobjects`, `write_metaobjects`, `read_files`, `write_files` (for the metaobject and file tools)
|
|
46
|
+
4. Install the app on your store
|
|
47
|
+
5. Copy your **Client ID** and **Client Secret** from the app's API credentials
|
|
48
|
+
|
|
49
|
+
The server will automatically exchange these for an access token and refresh it before it expires (tokens are valid for ~24 hours).
|
|
50
|
+
|
|
51
|
+
#### Option 2: Static Access Token (legacy apps)
|
|
52
|
+
|
|
53
|
+
If you have an existing custom app with a static `shpat_` access token, you can still use it directly.
|
|
54
|
+
|
|
55
|
+
This package is not currently published to npm — clone the repo and build it locally:
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
git clone https://github.com/yoffi-digital/mcp-shopify-yoffi.git
|
|
59
|
+
cd mcp-shopify-yoffi
|
|
60
|
+
npm install
|
|
61
|
+
npm run build
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
This produces `dist/index.js`, which the commands below reference directly.
|
|
65
|
+
|
|
66
|
+
### Usage with Claude Desktop
|
|
67
|
+
|
|
68
|
+
**Client Credentials (recommended):**
|
|
69
|
+
|
|
70
|
+
```json
|
|
71
|
+
{
|
|
72
|
+
"mcpServers": {
|
|
73
|
+
"shopify": {
|
|
74
|
+
"command": "node",
|
|
75
|
+
"args": [
|
|
76
|
+
"/absolute/path/to/mcp-shopify-yoffi/dist/index.js",
|
|
77
|
+
"--clientId",
|
|
78
|
+
"<YOUR_CLIENT_ID>",
|
|
79
|
+
"--clientSecret",
|
|
80
|
+
"<YOUR_CLIENT_SECRET>",
|
|
81
|
+
"--domain",
|
|
82
|
+
"<YOUR_SHOP>.myshopify.com"
|
|
83
|
+
]
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
**Static Access Token (legacy):**
|
|
90
|
+
|
|
91
|
+
```json
|
|
92
|
+
{
|
|
93
|
+
"mcpServers": {
|
|
94
|
+
"shopify": {
|
|
95
|
+
"command": "node",
|
|
96
|
+
"args": [
|
|
97
|
+
"/absolute/path/to/mcp-shopify-yoffi/dist/index.js",
|
|
98
|
+
"--accessToken",
|
|
99
|
+
"<YOUR_ACCESS_TOKEN>",
|
|
100
|
+
"--domain",
|
|
101
|
+
"<YOUR_SHOP>.myshopify.com"
|
|
102
|
+
]
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
Locations for the Claude Desktop config file:
|
|
109
|
+
|
|
110
|
+
- MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
111
|
+
- Windows: `%APPDATA%/Claude/claude_desktop_config.json`
|
|
112
|
+
|
|
113
|
+
### Usage with Claude Code
|
|
114
|
+
|
|
115
|
+
**Client Credentials:**
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
claude mcp add shopify -- node /absolute/path/to/mcp-shopify-yoffi/dist/index.js \
|
|
119
|
+
--clientId YOUR_CLIENT_ID \
|
|
120
|
+
--clientSecret YOUR_CLIENT_SECRET \
|
|
121
|
+
--domain your-store.myshopify.com
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
**Static Access Token (legacy):**
|
|
125
|
+
|
|
126
|
+
```bash
|
|
127
|
+
claude mcp add shopify -- node /absolute/path/to/mcp-shopify-yoffi/dist/index.js \
|
|
128
|
+
--accessToken YOUR_ACCESS_TOKEN \
|
|
129
|
+
--domain your-store.myshopify.com
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### Alternative: Run Locally with Environment Variables
|
|
133
|
+
|
|
134
|
+
If you prefer to use environment variables instead of command-line arguments:
|
|
135
|
+
|
|
136
|
+
1. Create a `.env` file with your Shopify credentials:
|
|
137
|
+
|
|
138
|
+
**Client Credentials:**
|
|
139
|
+
```
|
|
140
|
+
SHOPIFY_CLIENT_ID=your_client_id
|
|
141
|
+
SHOPIFY_CLIENT_SECRET=your_client_secret
|
|
142
|
+
MYSHOPIFY_DOMAIN=your-store.myshopify.com
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
**Static Access Token (legacy):**
|
|
146
|
+
```
|
|
147
|
+
SHOPIFY_ACCESS_TOKEN=your_access_token
|
|
148
|
+
MYSHOPIFY_DOMAIN=your-store.myshopify.com
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
2. Run the server:
|
|
152
|
+
```
|
|
153
|
+
node dist/index.js
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
### Additional Options
|
|
157
|
+
|
|
158
|
+
- `--apiVersion`: Specify the Shopify API version (default: `2026-07`). Can also be set via `SHOPIFY_API_VERSION` environment variable.
|
|
159
|
+
|
|
160
|
+
## Available Tools (32)
|
|
161
|
+
|
|
162
|
+
### Pagination, Sorting & Filtering
|
|
163
|
+
|
|
164
|
+
All list query tools (`get-products`, `get-customers`, `get-orders`, `get-customer-orders`) support:
|
|
165
|
+
|
|
166
|
+
- **Cursor-based pagination**: `after` / `before` (cursor strings), with `pageInfo` in the response (`hasNextPage`, `hasPreviousPage`, `startCursor`, `endCursor`)
|
|
167
|
+
- **Sorting**: `sortKey` (enum specific to each resource) and `reverse` (boolean)
|
|
168
|
+
- **Advanced filtering**: `query` or `searchQuery` parameter accepting [Shopify query syntax](https://shopify.dev/docs/api/usage/search-syntax)
|
|
169
|
+
|
|
170
|
+
### Product Management (8 tools)
|
|
171
|
+
|
|
172
|
+
1. **`get-products`**
|
|
173
|
+
|
|
174
|
+
- Get all products or search by title with pagination and sorting
|
|
175
|
+
- Inputs:
|
|
176
|
+
- `searchTitle` (string, optional): Filter products by title (wraps in `title:*...*`)
|
|
177
|
+
- `limit` (number, default: 10): Maximum number of products to return
|
|
178
|
+
- `query` (string, optional): Raw Shopify query string (e.g. `"status:active vendor:Nike tag:sale"`)
|
|
179
|
+
- `sortKey` (string, optional): One of `CREATED_AT`, `ID`, `INVENTORY_TOTAL`, `PRODUCT_TYPE`, `PUBLISHED_AT`, `RELEVANCE`, `TITLE`, `UPDATED_AT`, `VENDOR`
|
|
180
|
+
- `reverse` (boolean, optional): Reverse the sort order
|
|
181
|
+
- `after` / `before` (string, optional): Pagination cursors
|
|
182
|
+
|
|
183
|
+
2. **`get-product-by-id`**
|
|
184
|
+
|
|
185
|
+
- Get a specific product by ID with full details including SEO, options, media, variants, and collections
|
|
186
|
+
- Inputs:
|
|
187
|
+
- `productId` (string, required): Shopify product GID
|
|
188
|
+
- Returns: `productType`, `descriptionHtml`, `seo`, `options` (with `optionValues`), `media` (images), `variants`, `collections`, `tags`, `vendor`, price range, inventory
|
|
189
|
+
|
|
190
|
+
3. **`create-product`**
|
|
191
|
+
|
|
192
|
+
- Create a new product. When using `productOptions`, Shopify registers all option values but only creates one default variant (first value of each option, price $0). Use `manage-product-variants` with `strategy: REMOVE_STANDALONE_VARIANT` afterward to create all real variants with prices.
|
|
193
|
+
- Inputs:
|
|
194
|
+
- `title` (string, required): Title of the product
|
|
195
|
+
- `descriptionHtml` (string, optional): Description with HTML
|
|
196
|
+
- `handle` (string, optional): URL slug. Auto-generated from title if omitted
|
|
197
|
+
- `vendor` (string, optional): Vendor of the product
|
|
198
|
+
- `productType` (string, optional): Type of the product
|
|
199
|
+
- `tags` (array of strings, optional): Product tags
|
|
200
|
+
- `status` (string, optional): `"ACTIVE"`, `"DRAFT"`, or `"ARCHIVED"`. Default `"DRAFT"`
|
|
201
|
+
- `seo` (object, optional): `{ title, description }` for search engines
|
|
202
|
+
- `metafields` (array of objects, optional): Custom metafields (`namespace`, `key`, `value`, `type`)
|
|
203
|
+
- `productOptions` (array of objects, optional): Options to create inline, e.g. `[{ name: "Size", values: [{ name: "S" }, { name: "M" }] }]`. Max 3 options.
|
|
204
|
+
- `collectionsToJoin` (array of strings, optional): Collection GIDs to add the product to
|
|
205
|
+
|
|
206
|
+
4. **`update-product`**
|
|
207
|
+
|
|
208
|
+
- Update an existing product's fields
|
|
209
|
+
- Inputs:
|
|
210
|
+
- `id` (string, required): Shopify product GID
|
|
211
|
+
- `title` (string, optional): New title
|
|
212
|
+
- `descriptionHtml` (string, optional): New description
|
|
213
|
+
- `handle` (string, optional): New URL slug
|
|
214
|
+
- `vendor` (string, optional): New vendor
|
|
215
|
+
- `productType` (string, optional): New product type
|
|
216
|
+
- `tags` (array of strings, optional): New tags (overwrites existing)
|
|
217
|
+
- `status` (string, optional): `"ACTIVE"`, `"DRAFT"`, or `"ARCHIVED"`
|
|
218
|
+
- `seo` (object, optional): `{ title, description }` for search engines
|
|
219
|
+
- `metafields` (array of objects, optional): Metafields to set or update
|
|
220
|
+
- `collectionsToJoin` (array of strings, optional): Collection GIDs to add the product to
|
|
221
|
+
- `collectionsToLeave` (array of strings, optional): Collection GIDs to remove the product from
|
|
222
|
+
- `redirectNewHandle` (boolean, optional): If true, old handle redirects to new handle
|
|
223
|
+
|
|
224
|
+
5. **`delete-product`**
|
|
225
|
+
|
|
226
|
+
- Delete a product
|
|
227
|
+
- Inputs:
|
|
228
|
+
- `id` (string, required): Shopify product GID
|
|
229
|
+
|
|
230
|
+
6. **`manage-product-options`**
|
|
231
|
+
|
|
232
|
+
- Create, update, or delete product options (e.g. Size, Color)
|
|
233
|
+
- Inputs:
|
|
234
|
+
- `productId` (string, required): Shopify product GID
|
|
235
|
+
- `action` (string, required): `"create"`, `"update"`, or `"delete"`
|
|
236
|
+
- `variantStrategy` (string, optional): `"LEAVE_AS_IS"` (default) or `"CREATE"` — controls whether new variant combinations are generated when adding options
|
|
237
|
+
- For `action: "create"`:
|
|
238
|
+
- `options` (array, required): Options to create, e.g. `[{ name: "Size", values: ["S", "M", "L"] }]`
|
|
239
|
+
- For `action: "update"`:
|
|
240
|
+
- `optionId` (string, required): Option GID to update
|
|
241
|
+
- `name` (string, optional): New name for the option
|
|
242
|
+
- `position` (number, optional): New position
|
|
243
|
+
- `valuesToAdd` (array of strings, optional): Values to add
|
|
244
|
+
- `valuesToDelete` (array of strings, optional): Value GIDs to remove
|
|
245
|
+
- For `action: "delete"`:
|
|
246
|
+
- `optionIds` (array of strings, required): Option GIDs to delete
|
|
247
|
+
|
|
248
|
+
7. **`manage-product-variants`**
|
|
249
|
+
|
|
250
|
+
- Create or update product variants in bulk
|
|
251
|
+
- Inputs:
|
|
252
|
+
- `productId` (string, required): Shopify product GID
|
|
253
|
+
- `strategy` (string, optional): How to handle the default variant when creating. `"DEFAULT"` (removes "Default Title" automatically), `"REMOVE_STANDALONE_VARIANT"` (recommended for full control), or `"PRESERVE_STANDALONE_VARIANT"`
|
|
254
|
+
- `variants` (array, required): Variants to create or update. Each variant:
|
|
255
|
+
- `id` (string, optional): Variant GID for updates. Omit to create new
|
|
256
|
+
- `price` (string, optional): Price, e.g. `"49.00"`
|
|
257
|
+
- `compareAtPrice` (string, optional): Compare-at price for showing discounts
|
|
258
|
+
- `sku` (string, optional): SKU (mapped to `inventoryItem.sku`)
|
|
259
|
+
- `tracked` (boolean, optional): Whether inventory is tracked. Set `false` for print-on-demand
|
|
260
|
+
- `taxable` (boolean, optional): Whether the variant is taxable
|
|
261
|
+
- `barcode` (string, optional): Barcode
|
|
262
|
+
- `weight` (number, optional): Weight of the variant
|
|
263
|
+
- `weightUnit` (string, optional): `"GRAMS"`, `"KILOGRAMS"`, `"OUNCES"`, or `"POUNDS"`
|
|
264
|
+
- `optionValues` (array, optional): Option values, e.g. `[{ optionName: "Size", name: "A4" }]`
|
|
265
|
+
|
|
266
|
+
8. **`delete-product-variants`**
|
|
267
|
+
|
|
268
|
+
- Delete one or more variants from a product
|
|
269
|
+
- Inputs:
|
|
270
|
+
- `productId` (string, required): Shopify product GID
|
|
271
|
+
- `variantIds` (array of strings, required): Variant GIDs to delete
|
|
272
|
+
|
|
273
|
+
### Customer Management (8 tools)
|
|
274
|
+
|
|
275
|
+
1. **`get-customers`**
|
|
276
|
+
|
|
277
|
+
- List customers with search, pagination, and sorting
|
|
278
|
+
- Inputs:
|
|
279
|
+
- `searchQuery` (string, optional): Freetext or Shopify query syntax (e.g. `"country:US tag:vip orders_count:>5"`)
|
|
280
|
+
- `limit` (number, default: 10): Maximum number of customers to return
|
|
281
|
+
- `sortKey` (string, optional): One of `CREATED_AT`, `ID`, `LAST_UPDATE`, `LOCATION`, `NAME`, `ORDERS_COUNT`, `RELEVANCE`, `TOTAL_SPENT`, `UPDATED_AT`
|
|
282
|
+
- `reverse` (boolean, optional): Reverse the sort order
|
|
283
|
+
- `after` / `before` (string, optional): Pagination cursors
|
|
284
|
+
|
|
285
|
+
2. **`get-customer-by-id`**
|
|
286
|
+
|
|
287
|
+
- Get a single customer by ID with full details
|
|
288
|
+
- Inputs:
|
|
289
|
+
- `id` (string, required): Shopify customer ID (numeric only, e.g. `"6276879810626"`)
|
|
290
|
+
- Returns: name, email, phone, addresses, tags, note, tax status, amount spent, order count, metafields
|
|
291
|
+
|
|
292
|
+
3. **`create-customer`**
|
|
293
|
+
|
|
294
|
+
- Create a new customer
|
|
295
|
+
- Inputs:
|
|
296
|
+
- `firstName` (string, optional): Customer's first name
|
|
297
|
+
- `lastName` (string, optional): Customer's last name
|
|
298
|
+
- `email` (string, optional): Customer's email address
|
|
299
|
+
- `phone` (string, optional): Customer's phone number
|
|
300
|
+
- `tags` (array of strings, optional): Tags to apply
|
|
301
|
+
- `note` (string, optional): Note about the customer
|
|
302
|
+
- `taxExempt` (boolean, optional): Whether the customer is exempt from taxes
|
|
303
|
+
- `metafields` (array of objects, optional): Custom metafields (`namespace`, `key`, `value`, `type`)
|
|
304
|
+
- `addresses` (array of objects, optional): Customer addresses (`address1`, `address2`, `city`, `provinceCode`, `zip`, `country`, `phone`)
|
|
305
|
+
|
|
306
|
+
4. **`update-customer`**
|
|
307
|
+
|
|
308
|
+
- Update a customer's information
|
|
309
|
+
- Inputs:
|
|
310
|
+
- `id` (string, required): Shopify customer ID (numeric only, e.g. `"6276879810626"`)
|
|
311
|
+
- `firstName` (string, optional): Customer's first name
|
|
312
|
+
- `lastName` (string, optional): Customer's last name
|
|
313
|
+
- `email` (string, optional): Customer's email address
|
|
314
|
+
- `phone` (string, optional): Customer's phone number
|
|
315
|
+
- `tags` (array of strings, optional): Tags to apply to the customer
|
|
316
|
+
- `note` (string, optional): Note about the customer
|
|
317
|
+
- `taxExempt` (boolean, optional): Whether the customer is exempt from taxes
|
|
318
|
+
- `emailMarketingConsent` (object, optional): Email marketing consent settings
|
|
319
|
+
- `marketingState` (string, required): `"NOT_SUBSCRIBED"`, `"SUBSCRIBED"`, `"UNSUBSCRIBED"`, or `"PENDING"`
|
|
320
|
+
- `consentUpdatedAt` (string, optional): ISO 8601 timestamp
|
|
321
|
+
- `marketingOptInLevel` (string, optional): `"SINGLE_OPT_IN"`, `"CONFIRMED_OPT_IN"`, or `"UNKNOWN"`
|
|
322
|
+
- `metafields` (array of objects, optional): Customer metafields
|
|
323
|
+
|
|
324
|
+
5. **`delete-customer`**
|
|
325
|
+
|
|
326
|
+
- Delete a customer
|
|
327
|
+
- Inputs:
|
|
328
|
+
- `id` (string, required): Shopify customer ID (numeric only, e.g. `"6276879810626"`)
|
|
329
|
+
|
|
330
|
+
6. **`customer-merge`**
|
|
331
|
+
|
|
332
|
+
- Merge two customer records into one
|
|
333
|
+
- Inputs:
|
|
334
|
+
- `customerOneId` (string, required): GID of the first customer
|
|
335
|
+
- `customerTwoId` (string, required): GID of the second customer
|
|
336
|
+
- `overrideFields` (object, optional): Override which fields to keep from which customer (firstName, lastName, email, phone, defaultAddress, note, tags)
|
|
337
|
+
|
|
338
|
+
7. **`manage-customer-address`**
|
|
339
|
+
|
|
340
|
+
- Create, update, or delete a customer's mailing address
|
|
341
|
+
- Inputs:
|
|
342
|
+
- `customerId` (string, required): Customer GID
|
|
343
|
+
- `action` (string, required): `"create"`, `"update"`, or `"delete"`
|
|
344
|
+
- `addressId` (string, optional): Address GID (required for update/delete)
|
|
345
|
+
- `address` (object, optional): Address fields (required for create/update): `address1`, `address2`, `city`, `company`, `countryCode`, `firstName`, `lastName`, `phone`, `provinceCode`, `zip`
|
|
346
|
+
- `setAsDefault` (boolean, optional): Set as customer's default address
|
|
347
|
+
|
|
348
|
+
### Order Management (10 tools)
|
|
349
|
+
|
|
350
|
+
1. **`get-orders`**
|
|
351
|
+
|
|
352
|
+
- Get orders with filtering, pagination, and sorting
|
|
353
|
+
- Inputs:
|
|
354
|
+
- `status` (string, optional): `"any"`, `"open"`, `"closed"`, or `"cancelled"`. Default `"any"`
|
|
355
|
+
- `limit` (number, default: 10): Maximum number of orders to return
|
|
356
|
+
- `query` (string, optional): Raw Shopify query string (e.g. `"financial_status:paid fulfillment_status:shipped tag:rush"`)
|
|
357
|
+
- `sortKey` (string, optional): One of `CREATED_AT`, `ORDER_NUMBER`, `TOTAL_PRICE`, `FINANCIAL_STATUS`, `FULFILLMENT_STATUS`, `UPDATED_AT`, `CUSTOMER_NAME`, `PROCESSED_AT`, `ID`, `RELEVANCE`
|
|
358
|
+
- `reverse` (boolean, optional): Reverse the sort order
|
|
359
|
+
- `after` / `before` (string, optional): Pagination cursors
|
|
360
|
+
|
|
361
|
+
2. **`get-order-by-id`**
|
|
362
|
+
|
|
363
|
+
- Get a specific order by ID with smart lookup — accepts order name (`#77235` or `77235`), numeric ID (`8054938337547`), or full GID (`gid://shopify/Order/...`)
|
|
364
|
+
- Inputs:
|
|
365
|
+
- `orderId` (string, required): Order name, numeric ID, or full GID
|
|
366
|
+
- Returns: pricing, customer, shipping/billing addresses, line items, tags, notes, metafields, cancel reason, return status, discount codes, PO number, timestamps
|
|
367
|
+
|
|
368
|
+
3. **`update-order`**
|
|
369
|
+
|
|
370
|
+
- Update an existing order
|
|
371
|
+
- Inputs:
|
|
372
|
+
- `id` (string, required): Shopify order GID
|
|
373
|
+
- `tags` (array of strings, optional): New tags for the order
|
|
374
|
+
- `email` (string, optional): Update customer email on the order
|
|
375
|
+
- `note` (string, optional): Order notes
|
|
376
|
+
- `phone` (string, optional): Phone number for the order
|
|
377
|
+
- `poNumber` (string, optional): Purchase order number
|
|
378
|
+
- `customAttributes` (array of objects, optional): Custom key-value attributes
|
|
379
|
+
- `metafields` (array of objects, optional): Order metafields
|
|
380
|
+
- `shippingAddress` (object, optional): Shipping address fields
|
|
381
|
+
|
|
382
|
+
4. **`get-customer-orders`**
|
|
383
|
+
|
|
384
|
+
- Get orders for a specific customer with pagination and sorting
|
|
385
|
+
- Inputs:
|
|
386
|
+
- `customerId` (string, required): Shopify customer ID (numeric only, e.g. `"6276879810626"`)
|
|
387
|
+
- `limit` (number, default: 10): Maximum number of orders to return
|
|
388
|
+
- `sortKey` (string, optional): Same sort keys as `get-orders`
|
|
389
|
+
- `reverse` (boolean, optional): Reverse the sort order
|
|
390
|
+
- `after` / `before` (string, optional): Pagination cursors
|
|
391
|
+
|
|
392
|
+
5. **`order-cancel`**
|
|
393
|
+
|
|
394
|
+
- Cancel an order with options for refunding, restocking, and customer notification. **Irreversible.**
|
|
395
|
+
- Inputs:
|
|
396
|
+
- `orderId` (string, required): Order GID
|
|
397
|
+
- `reason` (string, required): `"CUSTOMER"`, `"DECLINED"`, `"FRAUD"`, `"INVENTORY"`, `"OTHER"`, or `"STAFF"`
|
|
398
|
+
- `restock` (boolean, required): Whether to restock inventory
|
|
399
|
+
- `notifyCustomer` (boolean, default: false): Notify the customer
|
|
400
|
+
- `staffNote` (string, optional): Internal note
|
|
401
|
+
- `refund` (boolean, optional): Refund to original payment method
|
|
402
|
+
|
|
403
|
+
6. **`order-close-open`**
|
|
404
|
+
|
|
405
|
+
- Close or reopen an order
|
|
406
|
+
- Inputs:
|
|
407
|
+
- `orderId` (string, required): Order GID
|
|
408
|
+
- `action` (string, required): `"close"` or `"open"`
|
|
409
|
+
|
|
410
|
+
7. **`order-mark-as-paid`**
|
|
411
|
+
|
|
412
|
+
- Mark an order as paid (for manual/offline payments)
|
|
413
|
+
- Inputs:
|
|
414
|
+
- `orderId` (string, required): Order GID
|
|
415
|
+
|
|
416
|
+
8. **`create-fulfillment`**
|
|
417
|
+
|
|
418
|
+
- Create a fulfillment (mark items as shipped) with optional tracking
|
|
419
|
+
- Inputs:
|
|
420
|
+
- `lineItemsByFulfillmentOrder` (array, required): Fulfillment orders and line items to fulfill
|
|
421
|
+
- `trackingInfo` (object, optional): `{ number, url, company }` tracking details
|
|
422
|
+
- `notifyCustomer` (boolean, default: false): Send shipping notification
|
|
423
|
+
|
|
424
|
+
9. **`refund-create`**
|
|
425
|
+
|
|
426
|
+
- Create a full or partial refund with optional restocking
|
|
427
|
+
- Inputs:
|
|
428
|
+
- `orderId` (string, required): Order GID
|
|
429
|
+
- `refundLineItems` (array, optional): Line items to refund with `lineItemId`, `quantity`, `restockType` (`CANCEL`/`RETURN`/`NO_RESTOCK`), `locationId`
|
|
430
|
+
- `shipping` (object, optional): `{ amount, fullRefund }` shipping refund
|
|
431
|
+
- `note` (string, optional): Refund note
|
|
432
|
+
- `notify` (boolean, optional): Send refund notification
|
|
433
|
+
|
|
434
|
+
10. **`create-draft-order`**
|
|
435
|
+
|
|
436
|
+
- Create a draft order for phone/chat sales, invoicing, or wholesale
|
|
437
|
+
- Inputs:
|
|
438
|
+
- `lineItems` (array, required): Product variants (`variantId`) or custom items (`title` + price). Max 499
|
|
439
|
+
- `customerId` (string, optional): Customer GID
|
|
440
|
+
- `email`, `phone`, `note`, `tags`, `poNumber` (optional)
|
|
441
|
+
- `shippingAddress`, `billingAddress` (objects, optional)
|
|
442
|
+
- `appliedDiscount` (object, optional): `{ title, value, valueType }` order-level discount
|
|
443
|
+
|
|
444
|
+
### Draft Order Management (1 tool)
|
|
445
|
+
|
|
446
|
+
1. **`complete-draft-order`**
|
|
447
|
+
|
|
448
|
+
- Complete a draft order, converting it into a real order
|
|
449
|
+
- Inputs:
|
|
450
|
+
- `draftOrderId` (string, required): Draft order GID
|
|
451
|
+
- `paymentGatewayId` (string, optional): Payment gateway GID
|
|
452
|
+
|
|
453
|
+
### Metafield Management (3 tools)
|
|
454
|
+
|
|
455
|
+
1. **`get-metafields`**
|
|
456
|
+
|
|
457
|
+
- Get metafields for any Shopify resource (products, orders, customers, variants, collections, etc.)
|
|
458
|
+
- Inputs:
|
|
459
|
+
- `ownerId` (string, required): GID of any resource
|
|
460
|
+
- `namespace` (string, optional): Filter by namespace
|
|
461
|
+
- `first` (number, default: 25): Number of metafields to return
|
|
462
|
+
- `after` (string, optional): Pagination cursor
|
|
463
|
+
|
|
464
|
+
2. **`set-metafields`**
|
|
465
|
+
|
|
466
|
+
- Set metafields on any Shopify resource. Creates or updates up to 25 metafields atomically
|
|
467
|
+
- Inputs:
|
|
468
|
+
- `metafields` (array, required): Metafields to set, each with `ownerId`, `key`, `value`, and optional `namespace`, `type`
|
|
469
|
+
|
|
470
|
+
3. **`delete-metafields`**
|
|
471
|
+
|
|
472
|
+
- Delete metafields from any Shopify resource
|
|
473
|
+
- Inputs:
|
|
474
|
+
- `metafields` (array, required): Metafields to delete, each with `ownerId`, `namespace`, `key`
|
|
475
|
+
|
|
476
|
+
### Inventory Management (1 tool)
|
|
477
|
+
|
|
478
|
+
1. **`inventory-set-quantities`**
|
|
479
|
+
|
|
480
|
+
- Set absolute inventory quantities for items at specific locations
|
|
481
|
+
- Inputs:
|
|
482
|
+
- `reason` (string, required): Reason for change (e.g. `"correction"`, `"cycle_count_available"`)
|
|
483
|
+
- `name` (string, required): `"available"` or `"on_hand"`
|
|
484
|
+
- `quantities` (array, required): Items with `inventoryItemId`, `locationId`, `quantity`
|
|
485
|
+
|
|
486
|
+
### Tag Management (1 tool)
|
|
487
|
+
|
|
488
|
+
1. **`manage-tags`**
|
|
489
|
+
|
|
490
|
+
- Add or remove tags on any taggable resource (orders, products, customers, draft orders, articles)
|
|
491
|
+
- Inputs:
|
|
492
|
+
- `id` (string, required): GID of the resource
|
|
493
|
+
- `tags` (array of strings, required): Tags to add or remove
|
|
494
|
+
- `action` (string, required): `"add"` or `"remove"`
|
|
495
|
+
|
|
496
|
+
### Discount Management (7 tools)
|
|
497
|
+
|
|
498
|
+
Bulk and maintenance tools (3–7) need the `read_discounts` and `write_discounts` scopes.
|
|
499
|
+
|
|
500
|
+
**Finding a discount:** every tool accepts the discount GID, the number from the admin URL (`/discounts/2269857186117`) or any code that is on it. Searching by code only works while that code is still on the discount. If a code was removed (for example the discount's own main code, which `remove-discount-codes` with `keepCsvPath` removes together with every other code not in the list), use the ID from the admin URL or one of the codes that are still on it.
|
|
501
|
+
|
|
502
|
+
1. **`create-discount`**
|
|
503
|
+
|
|
504
|
+
- Create a basic discount code (percentage or fixed amount), applied store-wide or scoped to specific collections and/or products
|
|
505
|
+
- Inputs:
|
|
506
|
+
- `title` (string, required): Internal title for the discount
|
|
507
|
+
- `code` (string, required): The discount code customers enter at checkout
|
|
508
|
+
- `valueType` (string, required): `"PERCENTAGE"` or `"FIXED_AMOUNT"`
|
|
509
|
+
- `value` (number, required): Decimal between 0 and 1 for `PERCENTAGE` (e.g. `0.15` for 15%), or the currency amount for `FIXED_AMOUNT`
|
|
510
|
+
- `startsAt` (string, required): ISO 8601 datetime the discount becomes active
|
|
511
|
+
- `endsAt` (string, optional): ISO 8601 datetime the discount expires
|
|
512
|
+
- `appliesOncePerCustomer` (boolean, optional): Limit each customer to a single use
|
|
513
|
+
- `usageLimit` (number, optional): Total number of redemptions allowed
|
|
514
|
+
- `includeCollectionIds` (array of strings, optional): Collection GIDs to scope the discount to (mutually exclusive with the product ID fields)
|
|
515
|
+
- `excludeCollectionIds` (array of strings, optional): Collection GIDs to exclude from an otherwise store-wide discount
|
|
516
|
+
- `includeProductIds` (array of strings, optional): Product GIDs to scope the discount to (mutually exclusive with the collection ID fields)
|
|
517
|
+
- `excludeProductIds` (array of strings, optional): Product GIDs to exclude from an otherwise store-wide discount
|
|
518
|
+
- `combinesWith` (object, optional): `{ productDiscounts, orderDiscounts, shippingDiscounts }` combination rules
|
|
519
|
+
|
|
520
|
+
2. **`create-automatic-discount`**
|
|
521
|
+
|
|
522
|
+
- Create an automatic discount (percentage or fixed amount) that applies at checkout with no code required, store-wide or scoped to specific collections and/or products
|
|
523
|
+
- Inputs:
|
|
524
|
+
- `title` (string, required): Title for the discount, shown to customers at checkout
|
|
525
|
+
- `valueType` (string, required): `"PERCENTAGE"` or `"FIXED_AMOUNT"`
|
|
526
|
+
- `value` (number, required): Decimal between 0 and 1 for `PERCENTAGE` (e.g. `0.15` for 15%), or the currency amount for `FIXED_AMOUNT`
|
|
527
|
+
- `startsAt` (string, required): ISO 8601 datetime the discount becomes active
|
|
528
|
+
- `endsAt` (string, optional): ISO 8601 datetime the discount expires
|
|
529
|
+
- `minimumSubtotal` (number, optional): Minimum order subtotal required for the discount to apply
|
|
530
|
+
- `includeCollectionIds` (array of strings, optional): Collection GIDs to scope the discount to (mutually exclusive with the product ID fields)
|
|
531
|
+
- `excludeCollectionIds` (array of strings, optional): Collection GIDs to exclude from an otherwise store-wide discount
|
|
532
|
+
- `includeProductIds` (array of strings, optional): Product GIDs to scope the discount to (mutually exclusive with the collection ID fields)
|
|
533
|
+
- `excludeProductIds` (array of strings, optional): Product GIDs to exclude from an otherwise store-wide discount
|
|
534
|
+
- `combinesWith` (object, optional): `{ productDiscounts, orderDiscounts, shippingDiscounts }` combination rules
|
|
535
|
+
|
|
536
|
+
3. **`add-discount-codes`**
|
|
537
|
+
|
|
538
|
+
- Attach many single-use codes (up to 100,000) to an existing code discount, including app discounts (e.g. SMART). Uploads in batches of 250 and writes two files: `<run>-result.csv` (every code with its status) and `<run>-partner.csv` (only usable codes). Only counts and samples are returned to the chat, never the full code list. Local (stdio) mode only.
|
|
539
|
+
- Statuses: `attached`, `skipped` (already on this discount), `conflict` (on another discount), `failed` (with Shopify's reason)
|
|
540
|
+
- Safe to repeat: each call stops after `maxSeconds`; calling again with the same input resumes from the result file and never uploads a code twice
|
|
541
|
+
- Inputs:
|
|
542
|
+
- `discount` (string, required): Discount GID, the number from the admin URL (`/discounts/123`), or a code already on the discount
|
|
543
|
+
- `generate` (object, optional): `{ count, prefix, length }`, e.g. `{ count: 25000, prefix: "DB-" }`. Uses readable characters only (no 0/O, 1/I/L)
|
|
544
|
+
- `csvPath` (string, optional): Partner CSV with its own codes (`code` column or first column, comma or semicolon). Use this or `generate`
|
|
545
|
+
- `outputDir` (string, optional): Folder for the result files. Required with `generate`; defaults to the CSV's folder
|
|
546
|
+
- `runName` (string, optional): Name of the result files. A new name starts a new run
|
|
547
|
+
- `dryRun` (boolean, default `true`): Show the discount details, plan and warnings without uploading. Reads the discount's current codes, so codes already on it are reported as `alreadyOnDiscount`, not as "would upload"
|
|
548
|
+
- `verify` (boolean, default `false`): Code-by-code reconciliation. Pages through all codes on the discount and compares them with the CSV / result file: `ok`, `missing` (in list, not on discount) and `extra` (on discount, not in list). Writes `<run>-verify.csv` and sets missing codes back to pending, so the next run uploads exactly those. Uploads nothing
|
|
549
|
+
- `maxSeconds` (number, default 50): Time budget per call
|
|
550
|
+
- Resilience: throttled requests are retried (about 47 s), network problems and requests without an answer after 25 s are retried 5 times. If it still fails, the call returns the counts plus `interrupted` instead of an error; calling again continues. `<run>-partner.csv` is written once, when the run is finished. If Windows locks a file (virus scanner, preview), the write is retried and otherwise reported in `fileWarnings` without aborting the call
|
|
551
|
+
|
|
552
|
+
4. **`manage-discount`**
|
|
553
|
+
|
|
554
|
+
- Pause (`deactivate`), reactivate (`activate`) or reschedule (change start/end date) an existing code discount. Codes are kept. Returns the discount before and after
|
|
555
|
+
- **Native Shopify discounts:** all three actions work.
|
|
556
|
+
- **App discounts (e.g. SMART):** Shopify only lets the app that owns a discount change it, so this tool can do just two things with them: **add codes** (`add-discount-codes`) and **pause** (`deactivate`). `activate` and `reschedule` are refused with a clear message. Activate the discount manually in the Shopify admin, and change its dates in the owning app (SMART)
|
|
557
|
+
- Inputs:
|
|
558
|
+
- `discount` (string, required): Discount GID, the number from the admin URL, or one of its codes
|
|
559
|
+
- `action` (string, required): `"activate"`, `"deactivate"` or `"reschedule"`
|
|
560
|
+
- `startsAt` (string, optional): `reschedule` only, new start (ISO 8601)
|
|
561
|
+
- `endsAt` (string or null, optional): `reschedule` only, new end (ISO 8601); `null` removes the end date
|
|
562
|
+
|
|
563
|
+
5. **`delete-discounts`**
|
|
564
|
+
|
|
565
|
+
- Permanently delete code discounts including all their codes (e.g. test discounts). Explicit discounts only, never by search. Default `dryRun=true` lists what would be deleted. Discounts already used in orders are skipped unless `allowUsed=true`. Discounts that are not found are reported, so repeating a call is safe
|
|
566
|
+
- Inputs:
|
|
567
|
+
- `discounts` (array of strings, required, max 50): GID, admin URL number or a code of each discount
|
|
568
|
+
- `dryRun` (boolean, default `true`): Only show what would be deleted
|
|
569
|
+
- `confirmCount` (number): Required when `dryRun=false`: the number of discounts that would be deleted (`wouldDelete` from the dry run). A wrong or missing number refuses the deletion
|
|
570
|
+
- `allowUsed` (boolean, default `false`): Also delete discounts that were used in orders
|
|
571
|
+
- `maxSeconds` (number, default 50): How long to wait for Shopify's delete job
|
|
572
|
+
|
|
573
|
+
6. **`get-discount-codes`**
|
|
574
|
+
|
|
575
|
+
- Look up a discount by ID, admin URL number or any of its codes (which discount does this code belong to?) and show its details. With `outputDir` it exports all codes to `<run>-codes.csv`; large discounts (25,000+) take several calls, repeat the same input to continue. The chat only gets details, counts and sample codes
|
|
576
|
+
- Inputs:
|
|
577
|
+
- `discount` (string, required): GID, admin URL number or a code
|
|
578
|
+
- `outputDir` (string, optional): Folder for the CSV export (local mode only)
|
|
579
|
+
- `runName` (string, optional): Name of the export files
|
|
580
|
+
- `maxSeconds` (number, default 50): Time budget per call
|
|
581
|
+
|
|
582
|
+
7. **`remove-discount-codes`**
|
|
583
|
+
|
|
584
|
+
- Remove codes from a discount without deleting it, e.g. extra codes after an upload. Three modes: `codes` (explicit list), `removeCsvPath` (codes to remove) or `keepCsvPath` (codes that must stay, everything else is removed). Default `dryRun=true` reads the discount once, builds the plan and writes `<run>-remove-plan.csv` (code + status) and a state file `<run>-remove-state.json`. The first real run needs `confirmCount` equal to the planned count; after that the run is confirmed. Large removals (25,000 codes) continue over several calls: repeat the same input (same `runName`, no `confirmCount`); each call works through the saved plan without re-reading the discount, so it is not affected by the count changing while Shopify's jobs run. When everything is removed, the discount is read once more to check; codes still there are retried. Batches start at 250 codes and drop to 100 if Shopify rejects them. Never removes all codes of a discount, and `keepCsvPath` is refused if none of its codes is on the discount. Note: `keepCsvPath` also removes the discount's own main code unless it is in the list; afterwards the discount can no longer be found by that code, only by its ID or a remaining code
|
|
585
|
+
- Inputs:
|
|
586
|
+
- `discount` (string, required): GID, admin URL number or a code
|
|
587
|
+
- `codes` / `removeCsvPath` / `keepCsvPath`: exactly one of them
|
|
588
|
+
- `outputDir` (string, required): Folder for the run files (local mode only)
|
|
589
|
+
- `runName` (string, optional): Name of the run files. The same name continues the run, a new name starts a new one
|
|
590
|
+
- `dryRun` (boolean, default `true`): Build and show the plan, remove nothing
|
|
591
|
+
- `confirmCount` (number): Required on the first `dryRun=false` call of a run: the count from the dry run. Not needed when continuing
|
|
592
|
+
- `maxSeconds` (number, default 50): Time budget per call
|
|
593
|
+
|
|
594
|
+
### Translation Management (4 tools)
|
|
595
|
+
|
|
596
|
+
Requires the `read_locales`, `read_translations` and `write_translations` scopes. Translations are written directly to the live store; there is no review step and no exclusion rules or glossary are applied.
|
|
597
|
+
|
|
598
|
+
1. **`get-shop-locales`**
|
|
599
|
+
|
|
600
|
+
- Get the shop's enabled locales, including the primary locale and which are published
|
|
601
|
+
- Inputs:
|
|
602
|
+
- `published` (boolean, optional): Only return published locales
|
|
603
|
+
|
|
604
|
+
2. **`get-translatable-resources`**
|
|
605
|
+
|
|
606
|
+
- Read translatable fields and existing translations for one locale. Each field returns its source value, digest, current translation and `outdated` flag
|
|
607
|
+
- Inputs:
|
|
608
|
+
- `locale` (string, required): Target locale, e.g. `"en"`
|
|
609
|
+
- `resourceIds` (array of strings, optional): GIDs of specific resources (max 50). Takes precedence over `resourceType`
|
|
610
|
+
- `resourceType` (string, optional): `TranslatableResourceType` to list, e.g. `"PRODUCT"`, `"PAGE"`, `"ONLINE_STORE_THEME"`
|
|
611
|
+
- `marketId` (string, optional): Market GID for market-specific translations
|
|
612
|
+
- `keys` (array of strings, optional): Only return these field keys
|
|
613
|
+
- `onlyMissingOrOutdated` (boolean, optional): Only return untranslated or outdated fields
|
|
614
|
+
- `first` (number, default: 10): Number of resources when listing by type (max 50)
|
|
615
|
+
- `after` (string, optional): Pagination cursor
|
|
616
|
+
|
|
617
|
+
3. **`register-translations`**
|
|
618
|
+
|
|
619
|
+
- Create or update translations on a single resource. Missing digests are fetched automatically
|
|
620
|
+
- Inputs:
|
|
621
|
+
- `resourceId` (string, required): GID of the resource
|
|
622
|
+
- `translations` (array, required): Up to 100 items, each with `key`, `locale`, `value`, and optional `translatableContentDigest`, `marketId`
|
|
623
|
+
|
|
624
|
+
4. **`remove-translations`**
|
|
625
|
+
|
|
626
|
+
- Delete translations for the given keys and locales on a single resource
|
|
627
|
+
- Inputs:
|
|
628
|
+
- `resourceId` (string, required): GID of the resource
|
|
629
|
+
- `translationKeys` (array of strings, required): Field keys to remove
|
|
630
|
+
- `locales` (array of strings, required): Locales to remove from
|
|
631
|
+
- `marketIds` (array of strings, optional): Market GIDs for market-specific translations
|
|
632
|
+
|
|
633
|
+
### Metaobject & File Management (6 tools)
|
|
634
|
+
|
|
635
|
+
Requires the `read_metaobject_definitions`, `read_metaobjects`, `write_metaobjects`, `read_files` and `write_files` scopes.
|
|
636
|
+
|
|
637
|
+
1. **`get-metaobject-definitions`**
|
|
638
|
+
|
|
639
|
+
- Get all metaobject definitions (types) with field keys, field types, required flags, validations and whether Active/Draft status is enabled
|
|
640
|
+
- Inputs:
|
|
641
|
+
- `first` (number, default: 25): Number of definitions to return (max 50)
|
|
642
|
+
- `after` (string, optional): Pagination cursor
|
|
643
|
+
|
|
644
|
+
2. **`get-metaobjects`**
|
|
645
|
+
|
|
646
|
+
- Get metaobject entries of one type with handle, display name, field values and Active/Draft status
|
|
647
|
+
- Inputs:
|
|
648
|
+
- `type` (string, required): Metaobject definition type, e.g. `"shipping_bar_settings"`
|
|
649
|
+
- `first` (number, default: 25): Number of entries to return (max 50)
|
|
650
|
+
- `after` (string, optional): Pagination cursor
|
|
651
|
+
|
|
652
|
+
3. **`upsert-metaobject`**
|
|
653
|
+
|
|
654
|
+
- Create or update a metaobject entry by type and handle
|
|
655
|
+
- Inputs:
|
|
656
|
+
- `type` (string, required): Metaobject definition type
|
|
657
|
+
- `handle` (string, required): Entry handle. Updates the entry if it exists, otherwise creates it
|
|
658
|
+
- `fields` (array, required): Items with `key` and `value`. Values are strings: lists as JSON arrays, references as GIDs, rich text as Shopify rich text JSON, dates as ISO 8601
|
|
659
|
+
- `status` (string, optional): `"ACTIVE"` or `"DRAFT"`, for types with Active/Draft status enabled
|
|
660
|
+
|
|
661
|
+
4. **`delete-metaobject`**
|
|
662
|
+
|
|
663
|
+
- Permanently delete a metaobject entry
|
|
664
|
+
- Inputs:
|
|
665
|
+
- `id` (string, required): Metaobject GID
|
|
666
|
+
|
|
667
|
+
5. **`get-files`**
|
|
668
|
+
|
|
669
|
+
- Search files in Content > Files, newest first. Returns GIDs for use in file reference fields
|
|
670
|
+
- Inputs:
|
|
671
|
+
- `query` (string, optional): Search query, e.g. `"filename:hero*"`, `"media_type:IMAGE"`
|
|
672
|
+
- `first` (number, default: 25): Number of files to return (max 50)
|
|
673
|
+
- `after` (string, optional): Pagination cursor
|
|
674
|
+
|
|
675
|
+
6. **`create-files`**
|
|
676
|
+
|
|
677
|
+
- Upload files to Content > Files from a public URL or a local file path. Files are processed asynchronously; check `fileStatus` with `get-files`
|
|
678
|
+
- Inputs:
|
|
679
|
+
- `files` (array, required): Up to 25 items, each with exactly one of `originalSource` (public URL) or `filePath` (local path, stdio mode only; jpg, jpeg, png, gif, webp, svg, mp4, mov, webm, pdf), plus optional `alt`, `filename`, `contentType` (`"IMAGE"`, `"VIDEO"`, `"FILE"`)
|
|
680
|
+
|
|
681
|
+
### Order Query Filter Reference
|
|
682
|
+
|
|
683
|
+
The `get-orders` tool's `query` parameter supports [Shopify search syntax](https://shopify.dev/docs/api/usage/search-syntax):
|
|
684
|
+
|
|
685
|
+
| Filter | Example |
|
|
686
|
+
|--------|---------|
|
|
687
|
+
| `name` | `name:#77235` |
|
|
688
|
+
| `created_at` | `created_at:>2024-01-01` or `created_at:2024-01-01..2024-03-31` |
|
|
689
|
+
| `updated_at` | `updated_at:>2024-06-01` |
|
|
690
|
+
| `financial_status` | `financial_status:paid` |
|
|
691
|
+
| `fulfillment_status` | `fulfillment_status:shipped` |
|
|
692
|
+
| `status` | `status:open` |
|
|
693
|
+
| `email` | `email:customer@example.com` |
|
|
694
|
+
| `tag` / `tag_not` | `tag:vip tag_not:wholesale` |
|
|
695
|
+
| `discount_code` | `discount_code:SUMMER20` |
|
|
696
|
+
| `sku` | `sku:PROD-001` |
|
|
697
|
+
| `risk_level` | `risk_level:high` |
|
|
698
|
+
| `gateway` | `gateway:shopify_payments` |
|
|
699
|
+
| `test` | `test:true` |
|
|
700
|
+
|
|
701
|
+
## Debugging
|
|
702
|
+
|
|
703
|
+
If you encounter issues, check Claude Desktop's MCP logs:
|
|
704
|
+
|
|
705
|
+
```
|
|
706
|
+
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
|
|
707
|
+
```
|
|
708
|
+
|
|
709
|
+
## License
|
|
710
|
+
|
|
711
|
+
MIT
|