payout-explain-cli

Shopify-style payout reconciliation from a normalized CSV.

This tool helps ecommerce sellers, bookkeepers, and small accounting firms explain why an ecommerce payout total does not match the amount that landed in the bank. It totals sales, refunds, fees, chargebacks, and adjustments, calculates the expected net payout, and compares that amount to an optional bank deposit.

It is designed for normalized payout data, not direct platform exports. Use it when you already have a simple transaction CSV and want a plain reconciliation summary or a Markdown report you can share with a client.

What It Does

• Totals gross sales from Shopify-style orders and other ecommerce payments.
• Subtracts refunds, payment processing fees, and chargebacks.
• Includes positive or negative payout adjustments such as reserve holds, reserve releases, and manual corrections.
• Calculates the net payout from the CSV rows.
• Optionally compares the calculated net payout to a bank deposit and explains the difference.

What It Does Not Do

• No Shopify, PayPal, or Stripe API integration yet.
• Not direct export compatibility yet; the CSV must use the normalized schema below.
• Not accounting, tax, or bookkeeping advice.
• Does not replace bookkeeping software.

CSV Format

Input files must be CSV files with this header:

date,type,amount,description

Supported transaction types:

• sale
• refund
• fee
• chargeback
• adjustment

Signs are taken exactly from the CSV: sales usually positive, refunds/fees/chargebacks usually negative, adjustments may be positive or negative.

Currency symbols, multiple currencies, and comma-formatted amounts are not supported yet. Enter amounts as plain numbers such as 184.50 or -14.87.

Sample Input

The included sample shows a normalized Shopify/PayPal-style payout with order sales, a refund, processing fees, a chargeback, reserve activity, and a manual payout adjustment.

date,type,amount,description
2026-06-01,sale,184.50,Shopify order #1001
2026-06-01,sale,76.25,Shopify order #1002
2026-06-02,sale,129.99,PayPal payment #PP-2041
2026-06-02,refund,-32.10,Refund for Shopify order #1002
2026-06-03,fee,-14.87,Payment processing fees
2026-06-03,chargeback,-58.40,Chargeback for Shopify order #1003
2026-06-04,adjustment,-25.00,Reserve hold
2026-06-05,adjustment,10.00,Reserve release
2026-06-05,adjustment,3.50,Manual payout adjustment

Run

.venv/bin/python -m payout_explain sample_data/basic_payout.csv

Optionally reconcile the calculated net payout against a bank deposit:

.venv/bin/python -m payout_explain sample_data/basic_payout.csv --bank-deposit 272.42

The difference is calculated as bank_deposit - net_payout.

Write a client-ready Markdown report to a file:

.venv/bin/python -m payout_explain sample_data/basic_payout.csv --bank-deposit 272.42 --output report.md

When --output is provided, the normal text report is not printed to stdout. The Markdown report includes a title, summary table, reconciliation fields, and explanation. See sample_output/example_report.md for an example client-ready Markdown report.

Example output:

gross_sales: 390.74
refunds: -32.10
fees: -14.87
chargebacks: -58.40
adjustments: -11.50
net_payout: 273.87
bank_deposit: 272.42
difference: -1.45

The bank deposit is 1.45 lower than the calculated net payout.

Test

.venv/bin/python -m unittest