Shopify Payout Auditor

A Python script that audits Shopify payouts by matching each order transaction against payout records to ensure every eligible order has been paid out.

Features

• Matches orders one-by-one between transaction and payout data
• Identifies any orders that should have been paid out but weren't
• Automatically excludes non-payout transactions (gift cards, cash, manual payments)
• Reports amount discrepancies between transactions and payouts
• Exports results to CSV for further analysis

Requirements

• Python 3.10+
• No external dependencies (uses only standard library)

Setup

1. Create the Data Directory

mkdir -p data

2. Export Files from Shopify

You need to download two CSV files from your Shopify admin:

A. Order Transactions Export

1. Go to Orders
2. Click Export (top right)
3. Select Orders by date
4. Choose your date range
5. Select CSV for Excel, Numbers, or other spreadsheet programs
6. Click Export transaction histories
7. Save the file to the data directory as transactions_export_1.csv

This file contains all order transactions with columns like:

• Order, Name, Kind, Gateway, Created At, Status, Amount, Currency, Card Type, Payment Method

B. Payout Transactions Export

1. Go to Finance > Payouts > View order transactions
2. Click Export (top right)
3. Select Items by date (not Summary)
4. Choose the same date range as above plus 5-10 days to account for delays in processing payouts
5. Select CSV for Excel, Numbers, or other spreadsheet programs
6. Click Export
7. Save the file to the data directory as payment_transactions_export_1.csv

This file contains individual payout transaction records with columns like:

• Transaction Date, Type, Order, Card Brand, Payout Status, Payout Date, Amount, Fee, Net

3. Verify Your Data Directory

Your data directory should look like this:

PayoutAuditor/
├── audit_payouts.py
├── README.md
└── data/
    ├── transactions_export_1.csv
    └── payment_transactions_export_1.csv

Usage

Basic Audit

Run the script with no arguments to audit using files in the data directory:

python3 audit_payouts.py

Export Unpaid Orders

If there are unpaid orders, export them to a CSV file:

python3 audit_payouts.py --export-unpaid

Export Full Audit

Export all orders with their payout status:

python3 audit_payouts.py --export-full

Custom File Paths

Specify custom file locations:

python3 audit_payouts.py \
  --transactions /path/to/transactions.csv \
  --payout-transactions /path/to/payout_transactions.csv

All Options

usage: audit_payouts.py [-h] [--transactions TRANSACTIONS]
                        [--payout-transactions PAYOUT_TRANSACTIONS]
                        [--export-unpaid] [--export-full]
                        [--output-dir OUTPUT_DIR]

Options:
  -h, --help            Show help message
  -t, --transactions    Path to order transactions CSV
  -p, --payout-transactions
                        Path to payout transactions CSV
  -u, --export-unpaid   Export unpaid orders to CSV
  -f, --export-full     Export full audit results to CSV
  -o, --output-dir      Output directory for exports (default: current directory)

Understanding the Output

Summary Section

Total Orders in Transaction Export:    2,599
Payout-Eligible Orders:                2,543
Orders Paid Out:                       2,543
Orders NOT Paid Out:                   0

• Total Orders: All unique orders in the transaction export
• Payout-Eligible: Orders that should appear in payouts (excludes gift cards, cash, etc.)
• Paid Out: Orders matched to a payout record
• NOT Paid Out: Orders missing from payouts (requires investigation)

Excluded Transactions

These transaction types are automatically excluded from the audit as they don't go through Shopify Payments:

• Gift card payments - Paid with store gift cards
• Cash payments - Marked as paid with cash
• Manual payments - Manually marked as paid
• Shop cash payments - Paid with Shop Cash rewards
• Failed transactions - Transactions that didn't complete

Amount Discrepancies

Small discrepancies between transaction and payout amounts are normal and usually caused by:

• Refund timing: A refund appears in transactions but hasn't been processed in payouts yet
• Partial refunds: Refund processed in a different payout cycle
• Split payments: Part of an order paid with gift card (excluded) and part with credit card

Exit Codes

• 0 - All eligible orders have been paid out
• 1 - There are unpaid orders requiring investigation

Troubleshooting

"No transactions export file found"

Make sure your transaction file is in the data directory and named transactions_export*.csv.

"No payout transactions file found"

Make sure your payout transactions file is in the data directory and named payment_transactions_export*.csv.

Large number of unpaid orders

If many orders show as unpaid, check that:

1. Your payout transactions export covers the same date range as your transactions export
2. You exported Transactions (not Summary) from the payouts section
3. Recent orders may not have been paid out yet (typically 2-3 business days delay)

Date range mismatch

For accurate results, ensure both exports cover the same time period. Orders near the end of your date range may show as unpaid if the payout hasn't occurred yet.