shopify-admin-bulk-customer-tag-update

Name: shopify-admin-bulk-customer-tag-update
Author: 40RTY-ai

168stars17forks

How to install shopify-admin-bulk-customer-tag-update?

40rty-ai/shopify-admin-skills/shopify-admin-bulk-customer-tag-update

$npx -y skills add 40RTY-ai/shopify-admin-skills --skill shopify-admin-bulk-customer-tag-update

Installs into the current project.

Summary

Adds and/or removes tags across a filtered set of customers — supports query-based selection, explicit ID lists, and union/replace tag modes.

Files · 1

View on GitHub

SKILL.md

1	## Purpose
2	Applies bulk tag changes (add, remove, or both) to customers selected by a query filter (e.g., `total_spent:>=500`, `tag:newsletter`) or by an explicit list of customer GIDs. Tags are how Shopify segments customers for discounts, marketing, and support workflows; this skill makes batch changes safe, dry-runnable, and auditable. Use when migrating from one tag taxonomy to another, when retiring a campaign-specific tag, or when applying a new segment tag identified by an analytics report.
3
4	## Prerequisites
5	- Authenticated Shopify CLI session: `shopify store auth --store <domain> --scopes read_customers,write_customers`
6	- API scopes: `read_customers`, `write_customers`
7
8	## Parameters
9
10	\| Parameter \| Type \| Required \| Default \| Description \|
11	\|-----------\|------\|----------\|---------\|-------------\|
12	\| store \| string \| yes \| — \| Store domain (e.g., mystore.myshopify.com) \|
13	\| format \| string \| no \| human \| Output format: `human` or `json` \|
14	\| dry_run \| bool \| no \| true \| Preview matching customers and the planned tag changes without executing mutations \|
15	\| filter \| string \| conditional \| — \| Customer query filter (e.g., `tag:newsletter`, `total_spent:>=500`); required if `customer_ids` is omitted \|
16	\| customer_ids \| array \| conditional \| — \| Explicit list of customer GIDs; required if `filter` is omitted \|
17	\| add_tags \| array \| no \| [] \| Tags to add (union with existing tags) \|
18	\| remove_tags \| array \| no \| [] \| Tags to remove (set difference) \|
19	\| mode \| string \| no \| merge \| Tag write mode: `merge` (apply add/remove to existing) or `replace` (overwrite tags entirely with `add_tags` only) \|
20	\| max_customers \| integer \| no \| 1000 \| Run-size cap; abort if filter matches more than this \|
21
22	## Safety
23
24	> ⚠️ Step 2 executes one `customerUpdate` mutation per customer in the matched set. Tag changes are immediate and visible to staff and to any apps reading customer tags (loyalty, marketing automation, segmentation). `mode: replace` overwrites existing tags entirely — manually-applied operational tags will be lost. The default is `dry_run: true` and `mode: merge`. Always run dry-run first, review the matched count, and confirm `add_tags`/`remove_tags` are spelled correctly — Shopify tags are case-sensitive.
25
26	## Workflow Steps
27
28	1. OPERATION: `customers` — query
29	Inputs: When `filter` is set: `query: <filter>`, `first: 250`, pagination cursor. When `customer_ids` is set: batch query with `query: "id:<id1> OR id:<id2> ..."` (chunk into batches of 25 IDs). Select `id`, `displayName`, `defaultEmailAddress { emailAddress }`, `tags`.
30	Expected output: Customer list with current tags. Abort if `match_count > max_customers`.
31
32	2. For each matched customer, compute the target tag set:
33	- If `mode: merge`: `target = (existing ∪ add_tags) \ remove_tags`
34	- If `mode: replace`: `target = add_tags` (remove_tags ignored)
35	Skip the customer if `target == existing` (no-op).
36
37	3. OPERATION: `customerUpdate` — mutation
38	Inputs: For each customer with a non-empty diff: `input: { id: <customer_id>, tags: <target_tag_array> }`
39	Expected output: `customer.id`, `customer.tags`, `userErrors`; collect failures
40
41	## GraphQL Operations
42
43	```graphql
44	# customers:query — validated against api_version 2025-01
45	query CustomersForBulkTagging($query: String!, $after: String) {
46	customers(first: 250, after: $after, query: $query) {
47	edges {
48	node {
49	id
50	displayName
51	firstName
52	lastName
53	defaultEmailAddress {
54	emailAddress
55	}
56	tags
57	numberOfOrders
58	amountSpent {
59	amount
60	currencyCode
61	}
62	}
63	}
64	pageInfo {
65	hasNextPage
66	endCursor
67	}
68	}
69	}
70	```
71
72	```graphql
73	# customerUpdate:mutation — validated against api_version 2025-01
74	mutation CustomerTagsUpdate($input: CustomerInput!) {
75	customerUpdate(input: $input) {
76	customer {
77	id
78	displayName
79	tags
80	}
81	userErrors {
82	field
83	message
84	}
85	}
86	}
87	```
88
89	## Session Tracking
90
91	Claude MUST emit the following output at each stage. This is mandatory.
92
93	On start, emit:
94	```
95	╔══════════════════════════════════════════════╗
96	║ SKILL: Bulk Customer Tag Update ║
97	║ Store: <store domain> ║
98	║ Started: <YYYY-MM-DD HH:MM UTC> ║
99	╚══════════════════════════════════════════════╝
100	```
101
102	After each step, emit:
103	```
104	[N/TOTAL] <QUERY\|MUTATION> <OperationName>
105	→ Params: <brief summary of key inputs>
106	→ Result: <count or outcome>
107	```
108
109	If `dry_run:

People who liked this also viewed

6 picks

Type

shopify-admin-bulk-customer-tag-update

168stars17forks

View on GitHub

How to install shopify-admin-bulk-customer-tag-update?

40rty-ai/shopify-admin-skills/shopify-admin-bulk-customer-tag-update

$npx -y skills add 40RTY-ai/shopify-admin-skills --skill shopify-admin-bulk-customer-tag-update

Installs into the current project.

Summary

Adds and/or removes tags across a filtered set of customers — supports query-based selection, explicit ID lists, and union/replace tag modes.

Files · 1

View on GitHub

SKILL.md

1	## Purpose
2	Applies bulk tag changes (add, remove, or both) to customers selected by a query filter (e.g., `total_spent:>=500`, `tag:newsletter`) or by an explicit list of customer GIDs. Tags are how Shopify segments customers for discounts, marketing, and support workflows; this skill makes batch changes safe, dry-runnable, and auditable. Use when migrating from one tag taxonomy to another, when retiring a campaign-specific tag, or when applying a new segment tag identified by an analytics report.
3
4	## Prerequisites
5	- Authenticated Shopify CLI session: `shopify store auth --store <domain> --scopes read_customers,write_customers`
6	- API scopes: `read_customers`, `write_customers`
7
8	## Parameters
9
10	\| Parameter \| Type \| Required \| Default \| Description \|
11	\|-----------\|------\|----------\|---------\|-------------\|
12	\| store \| string \| yes \| — \| Store domain (e.g., mystore.myshopify.com) \|
13	\| format \| string \| no \| human \| Output format: `human` or `json` \|
14	\| dry_run \| bool \| no \| true \| Preview matching customers and the planned tag changes without executing mutations \|
15	\| filter \| string \| conditional \| — \| Customer query filter (e.g., `tag:newsletter`, `total_spent:>=500`); required if `customer_ids` is omitted \|
16	\| customer_ids \| array \| conditional \| — \| Explicit list of customer GIDs; required if `filter` is omitted \|
17	\| add_tags \| array \| no \| [] \| Tags to add (union with existing tags) \|
18	\| remove_tags \| array \| no \| [] \| Tags to remove (set difference) \|
19	\| mode \| string \| no \| merge \| Tag write mode: `merge` (apply add/remove to existing) or `replace` (overwrite tags entirely with `add_tags` only) \|
20	\| max_customers \| integer \| no \| 1000 \| Run-size cap; abort if filter matches more than this \|
21
22	## Safety
23
24	> ⚠️ Step 2 executes one `customerUpdate` mutation per customer in the matched set. Tag changes are immediate and visible to staff and to any apps reading customer tags (loyalty, marketing automation, segmentation). `mode: replace` overwrites existing tags entirely — manually-applied operational tags will be lost. The default is `dry_run: true` and `mode: merge`. Always run dry-run first, review the matched count, and confirm `add_tags`/`remove_tags` are spelled correctly — Shopify tags are case-sensitive.
25
26	## Workflow Steps
27
28	1. OPERATION: `customers` — query
29	Inputs: When `filter` is set: `query: <filter>`, `first: 250`, pagination cursor. When `customer_ids` is set: batch query with `query: "id:<id1> OR id:<id2> ..."` (chunk into batches of 25 IDs). Select `id`, `displayName`, `defaultEmailAddress { emailAddress }`, `tags`.
30	Expected output: Customer list with current tags. Abort if `match_count > max_customers`.
31
32	2. For each matched customer, compute the target tag set:
33	- If `mode: merge`: `target = (existing ∪ add_tags) \ remove_tags`
34	- If `mode: replace`: `target = add_tags` (remove_tags ignored)
35	Skip the customer if `target == existing` (no-op).
36
37	3. OPERATION: `customerUpdate` — mutation
38	Inputs: For each customer with a non-empty diff: `input: { id: <customer_id>, tags: <target_tag_array> }`
39	Expected output: `customer.id`, `customer.tags`, `userErrors`; collect failures
40
41	## GraphQL Operations
42
43	```graphql
44	# customers:query — validated against api_version 2025-01
45	query CustomersForBulkTagging($query: String!, $after: String) {
46	customers(first: 250, after: $after, query: $query) {
47	edges {
48	node {
49	id
50	displayName
51	firstName
52	lastName
53	defaultEmailAddress {
54	emailAddress
55	}
56	tags
57	numberOfOrders
58	amountSpent {
59	amount
60	currencyCode
61	}
62	}
63	}
64	pageInfo {
65	hasNextPage
66	endCursor
67	}
68	}
69	}
70	```
71
72	```graphql
73	# customerUpdate:mutation — validated against api_version 2025-01
74	mutation CustomerTagsUpdate($input: CustomerInput!) {
75	customerUpdate(input: $input) {
76	customer {
77	id
78	displayName
79	tags
80	}
81	userErrors {
82	field
83	message
84	}
85	}
86	}
87	```
88
89	## Session Tracking
90
91	Claude MUST emit the following output at each stage. This is mandatory.
92
93	On start, emit:
94	```
95	╔══════════════════════════════════════════════╗
96	║ SKILL: Bulk Customer Tag Update ║
97	║ Store: <store domain> ║
98	║ Started: <YYYY-MM-DD HH:MM UTC> ║
99	╚══════════════════════════════════════════════╝
100	```
101
102	After each step, emit:
103	```
104	[N/TOTAL] <QUERY\|MUTATION> <OperationName>
105	→ Params: <brief summary of key inputs>
106	→ Result: <count or outcome>
107	```
108
109	If `dry_run:

People who liked this also viewed

6 picks

Type