shopify-admin-return-initiation

Name: shopify-admin-return-initiation
Author: 40RTY-ai

168stars17forks

How to install shopify-admin-return-initiation?

40rty-ai/shopify-admin-skills/shopify-admin-return-initiation

$npx -y skills add 40RTY-ai/shopify-admin-skills --skill shopify-admin-return-initiation

Installs into the current project.

Summary

Create a formal Shopify Return record for an order, specifying line items, quantities, and return reason — the first step in the native returns workflow.

Files · 1

View on GitHub

SKILL.md

1	## Purpose
2	Initiates a formal Shopify Return on a delivered order — specifying which line items to return, quantities, and reason. This creates the return record in Shopify's native returns system (distinct from simply issuing a refund). Used by support agents when a customer contacts them to return delivered items. The return record enables tracking, warehouse inspection, and exchange/refund resolution downstream. Note: `returnCreate` requires the order to be in `FULFILLED` status. For orders that haven't shipped yet, use `cancel-and-restock` instead. For already-returned items needing a refund, use `refund-and-reorder`.
3
4	## Prerequisites
5	- `shopify auth login --store <domain>`
6	- API scopes: `read_orders`, `write_returns`
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 \| false \| Preview operations without executing mutations \|
15	\| order_id \| string \| yes \| — \| GID of the order (e.g., `gid://shopify/Order/12345`) \|
16	\| return_line_items \| array \| no \| all fulfilled \| Array of `{fulfillment_line_item_id, quantity, reason, reason_note}` to return \|
17	\| return_reason \| string \| no \| `OTHER` \| Default return reason for all items if not specified per-item: `SIZE_TOO_SMALL`, `SIZE_TOO_LARGE`, `WRONG_ITEM`, `NOT_AS_DESCRIBED`, `DEFECTIVE`, `STYLE`, `COLOR`, `UNWANTED`, `OTHER` \|
18	\| notify_customer \| bool \| no \| true \| Send return initiation notification email to customer \|
19
20	## Safety
21
22	> ⚠️ Step 2 executes `returnCreate` which creates a formal return record and — if `notify_customer: true` — sends an email to the customer. This is appropriate only after verifying with the customer that a return is expected. Run with `dry_run: true` to preview the return line items and quantities before committing.
23
24	## Workflow Steps
25
26	1. OPERATION: `order` — query
27	Inputs: `id: <order_id>`
28	Expected output: Order `name`, `displayFulfillmentStatus` (must be `FULFILLED` — abort if not), `fulfillments` with `fulfillmentLineItems` including `id`, `quantity`, `discountedTotalSet`
29
30	2. OPERATION: `returnCreate` — mutation
31	Inputs: `returnInput.orderId`, `returnInput.returnLineItems` array (each with `fulfillmentLineItemId`, `quantity`, `reason`, `customerNote`)
32	Expected output: `return.id`, `return.status: OPEN`, `userErrors`
33
34	## GraphQL Operations
35
36	```graphql
37	# order:query — validated against api_version 2025-01
38	query OrderForReturn($id: ID!) {
39	order(id: $id) {
40	id
41	name
42	displayFulfillmentStatus
43	displayFinancialStatus
44	customer {
45	id
46	defaultEmailAddress {
47	emailAddress
48	}
49	firstName
50	lastName
51	}
52	fulfillments {
53	id
54	status
55	fulfillmentLineItems(first: 50) {
56	edges {
57	node {
58	id
59	quantity
60	lineItem {
61	title
62	variant {
63	id
64	sku
65	}
66	}
67	discountedTotalSet {
68	shopMoney { amount currencyCode }
69	}
70	}
71	}
72	}
73	}
74	}
75	}
76	```
77
78	```graphql
79	# returnCreate:mutation — validated against api_version 2025-01
80	mutation ReturnCreate($returnInput: ReturnInput!) {
81	returnCreate(returnInput: $returnInput) {
82	return {
83	id
84	status
85	order {
86	id
87	name
88	}
89	}
90	userErrors {
91	field
92	message
93	}
94	}
95	}
96	```
97
98	## Session Tracking
99
100	Claude MUST emit the following output at each stage. This is mandatory.
101
102	On start, emit:
103	```
104	╔══════════════════════════════════════════════╗
105	║ SKILL: return-initiation ║
106	║ Store: <store domain> ║
107	║ Started: <YYYY-MM-DD HH:MM UTC> ║
108	╚══════════════════════════════════════════════╝
109	```
110
111	After each step, emit:
112	```
113	[N/TOTAL] <QUERY\|MUTATION> <OperationName>
114	→ Params: <brief summary of key inputs>
115	→ Result: <count or outcome>
116	```
117
118	If `dry_run: true`, prefix every mutation step with `[DRY RUN]` and do not execute it.
119
120	On completion, emit:
121
122	For `format: human` (default):
123	```
124	══════════════════════════════════════════════
125	OUTCOME SUMMARY
126	Order: <name>
127	Return ID: <id>
128	Line items included: <count>
129	Return status: <status>
130	Customer notified: <yes/no>
131	Errors: 0
132	Output: none
133	════════════════════

People who liked this also viewed

6 picks

Type

shopify-admin-return-initiation

168stars17forks

View on GitHub

How to install shopify-admin-return-initiation?

40rty-ai/shopify-admin-skills/shopify-admin-return-initiation

$npx -y skills add 40RTY-ai/shopify-admin-skills --skill shopify-admin-return-initiation

Installs into the current project.

Summary

Create a formal Shopify Return record for an order, specifying line items, quantities, and return reason — the first step in the native returns workflow.

Files · 1

View on GitHub

SKILL.md

1	## Purpose
2	Initiates a formal Shopify Return on a delivered order — specifying which line items to return, quantities, and reason. This creates the return record in Shopify's native returns system (distinct from simply issuing a refund). Used by support agents when a customer contacts them to return delivered items. The return record enables tracking, warehouse inspection, and exchange/refund resolution downstream. Note: `returnCreate` requires the order to be in `FULFILLED` status. For orders that haven't shipped yet, use `cancel-and-restock` instead. For already-returned items needing a refund, use `refund-and-reorder`.
3
4	## Prerequisites
5	- `shopify auth login --store <domain>`
6	- API scopes: `read_orders`, `write_returns`
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 \| false \| Preview operations without executing mutations \|
15	\| order_id \| string \| yes \| — \| GID of the order (e.g., `gid://shopify/Order/12345`) \|
16	\| return_line_items \| array \| no \| all fulfilled \| Array of `{fulfillment_line_item_id, quantity, reason, reason_note}` to return \|
17	\| return_reason \| string \| no \| `OTHER` \| Default return reason for all items if not specified per-item: `SIZE_TOO_SMALL`, `SIZE_TOO_LARGE`, `WRONG_ITEM`, `NOT_AS_DESCRIBED`, `DEFECTIVE`, `STYLE`, `COLOR`, `UNWANTED`, `OTHER` \|
18	\| notify_customer \| bool \| no \| true \| Send return initiation notification email to customer \|
19
20	## Safety
21
22	> ⚠️ Step 2 executes `returnCreate` which creates a formal return record and — if `notify_customer: true` — sends an email to the customer. This is appropriate only after verifying with the customer that a return is expected. Run with `dry_run: true` to preview the return line items and quantities before committing.
23
24	## Workflow Steps
25
26	1. OPERATION: `order` — query
27	Inputs: `id: <order_id>`
28	Expected output: Order `name`, `displayFulfillmentStatus` (must be `FULFILLED` — abort if not), `fulfillments` with `fulfillmentLineItems` including `id`, `quantity`, `discountedTotalSet`
29
30	2. OPERATION: `returnCreate` — mutation
31	Inputs: `returnInput.orderId`, `returnInput.returnLineItems` array (each with `fulfillmentLineItemId`, `quantity`, `reason`, `customerNote`)
32	Expected output: `return.id`, `return.status: OPEN`, `userErrors`
33
34	## GraphQL Operations
35
36	```graphql
37	# order:query — validated against api_version 2025-01
38	query OrderForReturn($id: ID!) {
39	order(id: $id) {
40	id
41	name
42	displayFulfillmentStatus
43	displayFinancialStatus
44	customer {
45	id
46	defaultEmailAddress {
47	emailAddress
48	}
49	firstName
50	lastName
51	}
52	fulfillments {
53	id
54	status
55	fulfillmentLineItems(first: 50) {
56	edges {
57	node {
58	id
59	quantity
60	lineItem {
61	title
62	variant {
63	id
64	sku
65	}
66	}
67	discountedTotalSet {
68	shopMoney { amount currencyCode }
69	}
70	}
71	}
72	}
73	}
74	}
75	}
76	```
77
78	```graphql
79	# returnCreate:mutation — validated against api_version 2025-01
80	mutation ReturnCreate($returnInput: ReturnInput!) {
81	returnCreate(returnInput: $returnInput) {
82	return {
83	id
84	status
85	order {
86	id
87	name
88	}
89	}
90	userErrors {
91	field
92	message
93	}
94	}
95	}
96	```
97
98	## Session Tracking
99
100	Claude MUST emit the following output at each stage. This is mandatory.
101
102	On start, emit:
103	```
104	╔══════════════════════════════════════════════╗
105	║ SKILL: return-initiation ║
106	║ Store: <store domain> ║
107	║ Started: <YYYY-MM-DD HH:MM UTC> ║
108	╚══════════════════════════════════════════════╝
109	```
110
111	After each step, emit:
112	```
113	[N/TOTAL] <QUERY\|MUTATION> <OperationName>
114	→ Params: <brief summary of key inputs>
115	→ Result: <count or outcome>
116	```
117
118	If `dry_run: true`, prefix every mutation step with `[DRY RUN]` and do not execute it.
119
120	On completion, emit:
121
122	For `format: human` (default):
123	```
124	══════════════════════════════════════════════
125	OUTCOME SUMMARY
126	Order: <name>
127	Return ID: <id>
128	Line items included: <count>
129	Return status: <status>
130	Customer notified: <yes/no>
131	Errors: 0
132	Output: none
133	════════════════════

People who liked this also viewed

6 picks

Type