shopify-admin-payout-reconciliation

Name: shopify-admin-payout-reconciliation
Author: 40RTY-ai

168stars17forks

How to install shopify-admin-payout-reconciliation?

40rty-ai/shopify-admin-skills/shopify-admin-payout-reconciliation

$npx -y skills add 40RTY-ai/shopify-admin-skills --skill shopify-admin-payout-reconciliation

Installs into the current project.

Summary

Read-only: reconciles Shopify Payments payouts against the order transactions that funded them and flags amount discrepancies.

Files · 1

View on GitHub

SKILL.md

1	## Purpose
2	Reconciles Shopify Payments payouts to the order transactions that contributed to them. For each payout, sums gross sales, refunds, adjustments, and fees, and compares the computed net to the payout's reported `net` amount. Discrepancies are flagged with a delta and the suspected cause. Read-only — no mutations.
3
4	## Prerequisites
5	- Authenticated Shopify CLI session: `shopify store auth --store <domain> --scopes read_shopify_payments_payouts,read_orders`
6	- API scopes: `read_shopify_payments_payouts`, `read_orders`
7	- Store must use Shopify Payments. If the store uses only third-party gateways, this skill exits cleanly with a message.
8
9	## Parameters
10
11	\| Parameter \| Type \| Required \| Default \| Description \|
12	\|-----------\|------\|----------\|---------\|-------------\|
13	\| store \| string \| yes \| — \| Store domain (e.g., mystore.myshopify.com) \|
14	\| days_back \| integer \| no \| 30 \| Lookback window covering payouts issued in this period \|
15	\| tolerance \| number \| no \| 0.01 \| Acceptable delta in store currency before flagging a discrepancy \|
16	\| format \| string \| no \| human \| Output format: `human` or `json` \|
17
18	## Safety
19
20	> ℹ️ Read-only skill — no mutations are executed. Reconciliation output is informational; do not treat flagged discrepancies as confirmed errors before reviewing the underlying transactions in the Shopify admin.
21
22	## Workflow Steps
23
24	1. OPERATION: `shopifyPaymentsAccount` — query
25	Inputs: select `payouts(first: 100, query: "issued_at:>='<NOW - days_back days>'")` with `id`, `issuedAt`, `status`, `net`, `gross`, `summary { chargesGross, chargesFee, refundsGross, refundsFee, adjustmentsGross, adjustmentsFee, retriedPayoutsGross, retriedPayoutsFee }`
26	Expected output: All payouts in the window. If account is null, exit — store does not use Shopify Payments.
27
28	2. For each payout, compute reconciliation expectation:
29	```
30	expected_net = chargesGross - chargesFee
31	- refundsGross + refundsFee (refundsFee is normally negative / reversed)
32	+ adjustmentsGross - adjustmentsFee
33	+ retriedPayoutsGross - retriedPayoutsFee
34	```
35	`delta = reported_net - expected_net`
36
37	3. OPERATION: `orders` — query (only for flagged payouts to drill down)
38	Inputs: `query: "transactions:'gateway:shopify_payments processed_at:>=<payout.issuedAt - 7d> processed_at:<=<payout.issuedAt + 1d>'"`, `first: 250`
39	Expected output: Candidate orders that may have contributed to the payout, used for an order-level cross-check on top discrepancies
40
41	4. Classify each payout:
42	- `ok` if `\|delta\| <= tolerance`
43	- `discrepancy` otherwise — record sign (positive: payout overpaid us; negative: payout underpaid)
44
45	5. Aggregate totals across the window: total payouts, total reconciled, total discrepancies, sum of absolute deltas
46
47	## GraphQL Operations
48
49	```graphql
50	# shopifyPaymentsAccount:query — validated against api_version 2025-01
51	query PayoutReconciliation($payoutQuery: String!, $payoutAfter: String) {
52	shopifyPaymentsAccount {
53	id
54	payoutSchedule { interval }
55	payouts(first: 100, after: $payoutAfter, query: $payoutQuery) {
56	edges {
57	node {
58	id
59	issuedAt
60	status
61	net { amount currencyCode }
62	gross { amount currencyCode }
63	summary {
64	chargesGross { amount currencyCode }
65	chargesFee { amount currencyCode }
66	refundsFeeGross { amount currencyCode }
67	refundsFee { amount currencyCode }
68	adjustmentsGross { amount currencyCode }
69	adjustmentsFee { amount currencyCode }
70	retriedPayoutsGross { amount currencyCode }
71	retriedPayoutsFee { amount currencyCode }
72	}
73	}
74	}
75	pageInfo { hasNextPage endCursor }
76	}
77	}
78	}
79	```
80
81	```graphql
82	# orders:query — validated against api_version 2025-01
83	query OrdersFundingPayout($query: String!, $after: String) {
84	orders(first: 250, after: $after, query: $query) {
85	edges {
86	node {
87	id
88	name
89	processedAt
90	totalPriceSet { shopMoney { amount currencyCode } }
91	totalReceivedSet { shopMoney { amount currencyCode } }
92	transactions {
93	id
94	gateway
95	kind
96	status
97	processedAt
98	amountSet { shopMoney { amount currencyCode } }
99	}
100	}
101	}
102	pageInfo { hasNextPage endCursor }
103	}
104	}
105	```
106
107	## Session Tracking
108
109	Claude MUST emit the following output at each stage. This is mandatory.
110
111	On start, emit:
112	```
113	╔══════════════════════════════════════════════╗

People who liked this also viewed

6 picks

Type

shopify-admin-payout-reconciliation

168stars17forks

View on GitHub

How to install shopify-admin-payout-reconciliation?

40rty-ai/shopify-admin-skills/shopify-admin-payout-reconciliation

$npx -y skills add 40RTY-ai/shopify-admin-skills --skill shopify-admin-payout-reconciliation

Installs into the current project.

Summary

Read-only: reconciles Shopify Payments payouts against the order transactions that funded them and flags amount discrepancies.

Files · 1

View on GitHub

SKILL.md

1	## Purpose
2	Reconciles Shopify Payments payouts to the order transactions that contributed to them. For each payout, sums gross sales, refunds, adjustments, and fees, and compares the computed net to the payout's reported `net` amount. Discrepancies are flagged with a delta and the suspected cause. Read-only — no mutations.
3
4	## Prerequisites
5	- Authenticated Shopify CLI session: `shopify store auth --store <domain> --scopes read_shopify_payments_payouts,read_orders`
6	- API scopes: `read_shopify_payments_payouts`, `read_orders`
7	- Store must use Shopify Payments. If the store uses only third-party gateways, this skill exits cleanly with a message.
8
9	## Parameters
10
11	\| Parameter \| Type \| Required \| Default \| Description \|
12	\|-----------\|------\|----------\|---------\|-------------\|
13	\| store \| string \| yes \| — \| Store domain (e.g., mystore.myshopify.com) \|
14	\| days_back \| integer \| no \| 30 \| Lookback window covering payouts issued in this period \|
15	\| tolerance \| number \| no \| 0.01 \| Acceptable delta in store currency before flagging a discrepancy \|
16	\| format \| string \| no \| human \| Output format: `human` or `json` \|
17
18	## Safety
19
20	> ℹ️ Read-only skill — no mutations are executed. Reconciliation output is informational; do not treat flagged discrepancies as confirmed errors before reviewing the underlying transactions in the Shopify admin.
21
22	## Workflow Steps
23
24	1. OPERATION: `shopifyPaymentsAccount` — query
25	Inputs: select `payouts(first: 100, query: "issued_at:>='<NOW - days_back days>'")` with `id`, `issuedAt`, `status`, `net`, `gross`, `summary { chargesGross, chargesFee, refundsGross, refundsFee, adjustmentsGross, adjustmentsFee, retriedPayoutsGross, retriedPayoutsFee }`
26	Expected output: All payouts in the window. If account is null, exit — store does not use Shopify Payments.
27
28	2. For each payout, compute reconciliation expectation:
29	```
30	expected_net = chargesGross - chargesFee
31	- refundsGross + refundsFee (refundsFee is normally negative / reversed)
32	+ adjustmentsGross - adjustmentsFee
33	+ retriedPayoutsGross - retriedPayoutsFee
34	```
35	`delta = reported_net - expected_net`
36
37	3. OPERATION: `orders` — query (only for flagged payouts to drill down)
38	Inputs: `query: "transactions:'gateway:shopify_payments processed_at:>=<payout.issuedAt - 7d> processed_at:<=<payout.issuedAt + 1d>'"`, `first: 250`
39	Expected output: Candidate orders that may have contributed to the payout, used for an order-level cross-check on top discrepancies
40
41	4. Classify each payout:
42	- `ok` if `\|delta\| <= tolerance`
43	- `discrepancy` otherwise — record sign (positive: payout overpaid us; negative: payout underpaid)
44
45	5. Aggregate totals across the window: total payouts, total reconciled, total discrepancies, sum of absolute deltas
46
47	## GraphQL Operations
48
49	```graphql
50	# shopifyPaymentsAccount:query — validated against api_version 2025-01
51	query PayoutReconciliation($payoutQuery: String!, $payoutAfter: String) {
52	shopifyPaymentsAccount {
53	id
54	payoutSchedule { interval }
55	payouts(first: 100, after: $payoutAfter, query: $payoutQuery) {
56	edges {
57	node {
58	id
59	issuedAt
60	status
61	net { amount currencyCode }
62	gross { amount currencyCode }
63	summary {
64	chargesGross { amount currencyCode }
65	chargesFee { amount currencyCode }
66	refundsFeeGross { amount currencyCode }
67	refundsFee { amount currencyCode }
68	adjustmentsGross { amount currencyCode }
69	adjustmentsFee { amount currencyCode }
70	retriedPayoutsGross { amount currencyCode }
71	retriedPayoutsFee { amount currencyCode }
72	}
73	}
74	}
75	pageInfo { hasNextPage endCursor }
76	}
77	}
78	}
79	```
80
81	```graphql
82	# orders:query — validated against api_version 2025-01
83	query OrdersFundingPayout($query: String!, $after: String) {
84	orders(first: 250, after: $after, query: $query) {
85	edges {
86	node {
87	id
88	name
89	processedAt
90	totalPriceSet { shopMoney { amount currencyCode } }
91	totalReceivedSet { shopMoney { amount currencyCode } }
92	transactions {
93	id
94	gateway
95	kind
96	status
97	processedAt
98	amountSet { shopMoney { amount currencyCode } }
99	}
100	}
101	}
102	pageInfo { hasNextPage endCursor }
103	}
104	}
105	```
106
107	## Session Tracking
108
109	Claude MUST emit the following output at each stage. This is mandatory.
110
111	On start, emit:
112	```
113	╔══════════════════════════════════════════════╗

People who liked this also viewed

6 picks

Type