Shopify Payout CSV Preflight

Check the arithmetic in a Shopify Payments transaction export before reconciling a payout. This Actor totals amounts, fees and refunds, checks every Amount - Fee = Net calculation, and compares a declared single payout with an optional bank amount when the records support that comparison.

Built for e-commerce bookkeepers, merchant finance teams and accounting automation developers who already export Shopify data. It requires no store credentials and does not replace your accounting system, connect to a bank or post journals.

Why use a payout preflight?

A spreadsheet can look balanced even when a filtered export omits transactions or repeated rows inflate its totals. This check makes those uncertainties visible instead of presenting an unreliable match. Its useful result is a structured review report, including the reasons a comparison could not be performed.

Use it to check a payout before month-end review, screen files entering a bookkeeping workflow, or produce a consistent review trail across merchant clients. A report with no arithmetic differences is not proof that Shopify paid the bank or that every relevant transaction was supplied.

Key features

• Checks signed transaction arithmetic using integer minor units, without floating-point rounding drift.
• Handles negative refunds and negative fee credits without changing their signs.
• Totals amounts, fees and net values by transaction type and payout status.
• Retains repeated CSV records and flags them for review. The supported export has no universal stable transaction ID, so identical records cannot safely be deleted.
• Recognizes quoted commas, escaped quotes, quoted line breaks, UTF-8 BOM and CRLF CSV records.
• Reports row numbers for arithmetic findings and reasons for withholding a bank comparison.
• Rejects malformed files, unsupported headers and oversized requests without silently truncating rows.

No OCR, AI inference, web scraping, exchange-rate lookup or third-party account access is involved.

Who should use it?

Bookkeeping practices handling multiple Shopify merchants can add this check before their existing reconciliation process. Merchant finance teams can use it as a second arithmetic review. Developers can consume the structured holds and totals without a store integration. It is not intended for customers seeking automatic accounting entries or access to transaction history without an export.

Quick start

1. In Shopify, select one specific payout and export its complete transactions. Do not apply a filter if you intend to compare the complete payout.
2. Paste the supported legacy Shopify Payments CSV into Shopify Payments transactions CSV.
3. Declare the currency and enter a short payout alias. Do not enter a bank account number.
4. Set the full single-payout declaration truthfully. Leave it false for partial or uncertain coverage.
5. Optionally supply the matching bank amount in the same currency, then run the Actor.
6. Open the report dataset or OUTPUT JSON. Review findings and comparison holds before relying on totals.

The prefilled demonstration is invented data, not merchant activity. Running a completed demonstration is billable.

Tested example input

{
  "transactionsCsv": "Type,Payout Status,Payout Date,Amount,Fee,Net\ncharge,paid,2026-10-09,100.00,3.00,97.00\nrefund,paid,2026-10-09,-2.00,0.00,-2.00",
  "currency": "USD",
  "payoutReference": "PAYOUT-DEMO",
  "exportComplete": true,
  "bankAmount": "95.00"
}

Inputs and supported format

Field	Required	Meaning and limit
transactionsCsv	Yes	UTF-8 CSV string, at most 2,000,000 bytes and 5,000 nonempty transaction records.
currency	Yes	USD, CAD, AUD, EUR or GBP. Explicit declaration; never inferred from this CSV.
payoutReference	Yes	Letter-led alias up to 60 characters; no bank account details.
exportComplete	Yes	Boolean declaration that this is one full, unfiltered payout export. Not independently verified.
bankAmount	No	Signed decimal string, up to two decimal places, in the same currency. Omit when unknown.

Required CSV headers are exactly Type, Payout Status, Payout Date, Amount, Fee, Net. Optional documented headers are Transaction Date, Order, Card Brand, Card Source, Available On. Column order may vary. Other headers, duplicate headers and inconsistent record widths are rejected. This intentionally supports a particular documented export, not arbitrary Shopify reports or third-party formats.

Money fields must use plain decimal text, such as 123.45 or -2.00; no currency symbols, thousands separators or scientific notation. Dates are real YYYY-MM-DD dates or blank. Supported statuses are paid, deposited, withdrawn, scheduled, pending and failed, case-insensitive. Unknown statuses are rejected rather than assigned a guessed meaning.

The fixed limits are 128 MB memory and 30 seconds. Requests exceeding the input limits fail; results are not silently shortened.

Output: verified example result

The tested input above produces the following selected fields from the complete report:

{
  "schemaVersion": 1,
  "payoutReference": "PAYOUT-DEMO",
  "currency": "USD",
  "summary": {
    "transactionCount": 2,
    "repeatedRecordsKept": 0,
    "totalAmount": "98.00",
    "totalFee": "3.00",
    "reportedNetTotal": "95.00",
    "calculatedNetTotal": "95.00",
    "findingCount": 0
  },
  "bankComparison": {
    "provided": true,
    "performed": true,
    "declaredBankAmount": "95.00",
    "difference": "0.00",
    "holds": []
  },
  "reviewRequired": false,
  "findings": []
}

The complete JSON also includes the check timestamp, input hash, reviewed rows, totals by type and status, scope and coverage declarations. Money remains a decimal string in all outputs.

Output	How to use it
summary	Whole-file counts and signed totals; repeated records remain included.
rows	Parsed transaction amounts, fees, reported net and calculated net with CSV record numbers. Order/card labels are omitted.
findings	Arithmetic mismatches, repeated-record review requests and permitted bank comparison differences.
bankComparison.holds	Reasons a bank comparison is unsafe, even when a bank amount was supplied.
coverage	User declarations and the explicit fact that completeness was not independently verified.
byType, byStatus	Categorized totals for a reviewer or downstream workflow.
inputSha256	Fingerprint of the submitted input, not a stable Shopify transaction identifier.

How comparisons work

Each transaction is parsed and its reported net is compared with amount minus fee. The Actor then sums the supplied rows. A bank comparison requires all of the following: a supplied bank amount, a full single-payout declaration, exactly one nonblank payout date, final settlement statuses, no repeated-record ambiguity and no transaction net mismatches.

Several payouts can share a date. A common date does not establish that the file contains one payout; the full single-payout declaration remains the user's responsibility. Pending values may change. A paid or deposited label in an uploaded CSV does not independently prove bank receipt.

When permitted, the bank difference is declared bank amount - reported net total. A difference asks the reviewer to investigate timing, currency, fees and source selection. It is not evidence that money was withheld or revenue lost.

Pricing

The proposed Actor price is $0.18 per completed payout preflight report, including up to 5,000 transaction rows. One report is stored as one dataset item and triggers one payout-csv-preflight event. Findings and explicit comparison holds are useful completed review results and are billable. Invalid input rejected before report creation does not trigger the report event.

Examples of Actor event charges: one report $0.18; ten reports $1.80; 100 reports $18.00. Four weekly reports cost $0.72. These are usage examples, not a subscription. Applicable Apify platform charges and plan rules are separate; the Store pricing panel is authoritative. Downstream storage access and customer-selected retention can also affect platform usage. The product does not collect a percentage of a difference or charge per finding.

API, scheduling and integrations

Schedule a saved Actor task after your export process makes a new file available. This Actor does not automatically retrieve files from Shopify or banks. Your automation must pass a complete CSV string and accurate declarations for each run. Do not resubmit the same payout merely because a previous report found a difference: inspect its completed run first.

For an API integration, supply an Apify API token through your application's secure environment and use the official client:

import { ApifyClient } from 'apify-client';
import fs from 'node:fs';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const input = JSON.parse(fs.readFileSync('sample_input.json', 'utf8'));
const run = await client.actor('wheresprada/shopify-payout-csv-preflight').call(input);
const report = await client.keyValueStore(run.defaultKeyValueStoreId).getRecord('OUTPUT');
console.log(report.value.summary, report.value.bankComparison);

Use the tested example JSON as sample_input.json. Never commit a token or put it in customer-visible logs. Apify run-completion webhooks can notify a downstream workflow; check the actual run status and report before consuming results. Integration code requires the official apify-client package in your application.

Limits and accuracy

This is a bounded arithmetic and coverage preflight, not an accounting audit or financial advice. It cannot detect an omitted transaction absent from the uploaded file, establish complete merchant history, reconcile multiple currencies, validate processor fee contracts, determine tax treatment or create accounting journals. It cannot distinguish two genuinely identical transactions from an accidentally repeated CSV record. Both remain in totals with a hold.

Only the documented legacy Shopify Payments layout is accepted. If Shopify changes its export, the Actor should reject an unsupported layout instead of producing guessed mappings. Confirm current format compatibility with the first small file before automating a large batch.

Privacy and security

No external network calls, proxies or credentials are required by the processing code. Do not upload customer names, addresses, card numbers, bank account numbers or API tokens. Optional order/card label columns are not copied into the result, but anything submitted remains present in the run's stored input according to Apify storage and retention settings. The original CSV is therefore still sensitive. Use appropriate access controls and retention; this Actor is not a promise of automatic deletion or a security certification.

Reports contain financial totals and the alias you supplied. Treat dataset links as sensitive and do not share them publicly by accident. No checkout, bank or Shopify account is accessed.

Troubleshooting and FAQ

Why was my file rejected? Check the required headers, comma delimiter, quoting and decimal format. Other Shopify reports and localized layouts are not supported. Error messages identify the problem or record number without echoing transaction values.

Why is the bank comparison held? Read bankComparison.holds. A partial export, pending status, blank/mixed dates, repeated record or net mismatch prevents a reliable comparison. Correct the source selection rather than forcing the declaration.

Why were duplicate-looking rows kept? This export lacks a universal stable transaction ID. Automatically dropping equal rows could remove legitimate transactions.

Does a zero difference prove my books are correct? No. It verifies arithmetic against your supplied amount under your completeness declaration, not external account history or bank receipt.

Can I check several payouts at once? Supply one complete payout per run for a bank comparison. Multi-payout files may be reviewed for transaction arithmetic, but declare coverage false and expect comparison holds.

Can I use another currency? Only the five supported two-decimal currencies are accepted. No FX conversion is performed.

Am I charged when findings exist? Yes, if a complete report was produced. Findings and documented holds are the review's output. Invalid input does not trigger the completed-report event.

Where are the results? One complete report is available in the default dataset and under OUTPUT in the default key-value store.

Support and source format

Open an issue on this Actor's Apify Store page with the run ID, expected behavior and a redacted minimal example. Never include API tokens or merchant/customer secrets. Export documentation: Shopify Payments payout details and transactions. Scheduling and API behavior follow the official Apify documentation.

Independent product; not affiliated with or endorsed by Shopify or any bank.