# Shopify Payout CSV Preflight (`wheresprada/shopify-payout-csv-preflight`) Actor

Check Shopify Payments CSV net arithmetic, refunds and fees before comparing one declared payout with a bank amount. Flag incomplete exports and repeated records. No store login, accounting connection or automatic posting.

- **URL**: https://apify.com/wheresprada/shopify-payout-csv-preflight.md
- **Developed by:** [Mahruf Hossain](https://apify.com/wheresprada) (community)
- **Categories:** E-commerce
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.18 / completed payout csv preflight

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## 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

```json
{
  "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:

```json
{
  "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:

```javascript
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](https://help.shopify.com/en/manual/payments/shopify-payments/payouts/view-details). Scheduling and API behavior follow the [official Apify documentation](https://docs.apify.com/platform).

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

# Actor input Schema

## `transactionsCsv` (type: `string`):

Required headers: Type, Payout Status, Payout Date, Amount, Fee, Net. Optional official fields: Transaction Date, Order, Card Brand, Card Source, Available On. Maximum 5000 records / 2 MB. Money is a signed plain decimal, at most two places. Other layouts are rejected.

## `currency` (type: `string`):

Required explicit declaration: the supported legacy CSV does not identify currency. No foreign-exchange conversion.

## `payoutReference` (type: `string`):

A letter-led label up to 60 characters, such as PAYOUT-OCT-09. Do not use a bank account number.

## `exportComplete` (type: `boolean`):

An explicit user declaration, not independently verified. Set false for filtered or multi-payout data. Multiple payouts can share a date.

## `bankAmount` (type: `string`):

Signed plain decimal string in the same declared currency. Omit if unknown. Compared only when all coverage and arithmetic checks permit it.

## Actor input object example

```json
{
  "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"
}
```

# Actor output Schema

## `report` (type: `string`):

No description

## `reports` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "transactionsCsv": `Type,Payout Status,Payout Date,Amount,Fee,Net
charge,paid,2026-10-09,100.00,3.00,97.00
refund,paid,2026-10-09,-2.00,0.00,-2.00`,
    "currency": "USD",
    "payoutReference": "PAYOUT-DEMO",
    "exportComplete": true,
    "bankAmount": "95.00"
};

// Run the Actor and wait for it to finish
const run = await client.actor("wheresprada/shopify-payout-csv-preflight").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "transactionsCsv": """Type,Payout Status,Payout Date,Amount,Fee,Net
charge,paid,2026-10-09,100.00,3.00,97.00
refund,paid,2026-10-09,-2.00,0.00,-2.00""",
    "currency": "USD",
    "payoutReference": "PAYOUT-DEMO",
    "exportComplete": True,
    "bankAmount": "95.00",
}

# Run the Actor and wait for it to finish
run = client.actor("wheresprada/shopify-payout-csv-preflight").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "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"
}' |
apify call wheresprada/shopify-payout-csv-preflight --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,wheresprada/shopify-payout-csv-preflight"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/lexd6HsbxLVYpWYZA/builds/dULPByB2PpR8fFz6T/openapi.json