Shopify Payments Payout Reconciliation Skill

What it catches

Proven on a labeled example

examples/northwind-october/ is a fictional coffee roaster's October in Shopify Payments's own export format: 6 payouts, 18 lines, a bank statement and an orders export, with 12 planted situations (a missing deposit, a short deposit, a chargeback, a reserve hold, a double charge, an under-charged order, a paid order never charged, an unexplained deposit, a payout still in transit and a refund from September). expected.json labels the outcome a careful bookkeeper would reach; the tests assert the tool reaches exactly that in any row order, that every proposed entry balances, and that a fixed month exits 0.

What you get

Outputs in out/: payouts.csv (each payout, its status and bank line), exceptions.csv (review queue, highest priority first), journal.csv (proposed entries, balanced), report.md, summary.json. Exit 0 = every payout is accounted for; 1 = something blocks the reconciliation; 2 = an input problem (the message says which flag fixes it).

Quick start

./run_tests.sh
python3 -m shopifypayrec --payouts examples/northwind-october/payout_transactions_export.csv --bank examples/northwind-october/bank.csv \
  --orders examples/northwind-october/orders.csv --name "Northwind Coffee" --out out/

Inputs

• Shopify admin > Finance > Payouts > View transactions > Export (CSV). Uses Payout ID (added to exports in January 2026) or groups by Payout Date on older files; checks each payout's own payout row against its lines.
• Any bank CSV with a date and either an amount column or debit/credit columns. Map unusual headers with --map-bank date="Posted" amount="Amt". Slash dates that could be US or EU are refused until you pass --date-format.
• Optional orders/invoices CSV with an order number and total (Shopify orders export, WooCommerce, an invoice list).

Use it from your agent

• Claude Code plugin: this folder is a plugin (.claude-plugin/plugin.json). Try it with claude --plugin-dir ./shopify-payout-reconciliation-skill, or add the folder to your own plugin marketplace.
• Skill only: copy skills/shopify-payout-rec/ into ~/.claude/skills/ (or your agent's skills folder) and keep this folder where the agent can run python3 -m shopifypayrec.
• No agent: the CLI works on its own; --help lists every flag.

Honest limits

• CSV exports only: no API connection, no login, no PDF statements.
• One currency per run (--currency); no FX conversion.
• Matching is exact on amount within a date window (default 5 days). A deposit that combines two payouts comes out as exceptions for a person to pair, not a forced match.
• possible_ codes are leads: check the order and the processor dashboard before refunding anyone.
• It proposes entries; it never posts them. It is not accounting or tax advice.

Requirements

Python 3.9+ (tested on 3.10 and 3.13), no dependencies. Not affiliated with Shopify.

Format and license

Zip, 22 KB, v1.0, 17 files. Use and modify it for yourself and for clients you serve; no resale or redistribution of the kit itself. Full terms in LICENSE.txt.

FAQ

Shopify Payments only?

Yes; PayPal and other gateways come through their own exports (see the PayPal kit).

Does it install an app?

No; CSV only, nothing touches your store.

Does it post entries?

Never.

How do I get the files?

Right after payment, Stripe’s confirmation page shows your download link.

Refunds?

Email hello@youraitools.co within 14 days if it doesn’t work and we can’t fix it.

Can I pay with crypto?

Yes. Pay the same price in USDC or USDT on Base, Ethereum, Arbitrum, Optimism, Polygon or Solana from the "Pay with crypto" button, with no account or KYC. We check the payment on-chain and show your download links as soon as it confirms.

Pairs well with

Related

• Stripe Payout Reconciliation Skill
• PayPal Payout Reconciliation Skill
• Bank Reconciliation Exceptions Skill
• All agent skills