# Invoice CSV Preflight & Whole-Invoice Batch Pack (`atesen-software/invoice-csv-preflight-batch-pack`) Actor

Check supplied exact-profile US/USD invoice CSVs and preserve whole invoices in review batches. Source-record validation receipts and optional CSV/ZIP for acknowledged invoices. No QuickBooks connection or import.

- **URL**: https://apify.com/atesen-software/invoice-csv-preflight-batch-pack.md
- **Developed by:** [Atesen Software](https://apify.com/atesen-software) (community)
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 20.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$2.00 / 1,000 whole-invoice validation receipts

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

## Invoice CSV Preflight & Whole-Invoice Batch Pack

Review a supplied invoice CSV before manually mapping it into an eligible US QuickBooks Online invoice-import workflow. Keep each invoice together, retain source cell values, and get a traceable receipt with original record ordinals, line counts, item-amount totals and input hashes.

This Actor processes your supplied CSV **in Apify cloud**. It does not connect to QuickBooks, import data, verify account/customer/item existence, or certify tax/accounting correctness. Before uploading any financial CSV, set your Apify account/resource access to **Restricted**. The platform stores input before Actor code starts, so the Actor cannot retrospectively guarantee the privacy of the upload window. Use only data you are authorized to upload. Run inputs, receipts and CSV files are stored in your Apify run storage; do not share run links or credentials with unauthorized people.

The source schema marks `csvText` as `isSecret: true`. [Apify documents](https://docs.apify.com/actors/development/actor-definition/input-schema/secret-input) encrypted Console input and field encryption before default INPUT storage for API runs. `Actor.get_input()` decrypts the field for processing. The existing anonymous-denial check and Restricted run, dataset and output requirements continue to apply. Other input fields and generated CSV files retain their storage access controls.

### Exact supported profile

- UTF-8 CSV text with exact headings: `InvoiceNo,Customer,InvoiceDate,DueDate,ItemAmount`. Optional columns are preserved.
- Explicit declarations: `region: "US"`, `salesTaxEnabled: false`, `currency: "USD"`, and `dateFormat: "ISO"`, `"DMY"` or `"MDY"`. Unknown context is blocked. USD-only and these exact headers are this tool's restrictions.
- At most 1,000,000 CSV UTF-8 bytes, 5,000 source records and 500 whole invoices per run; total input JSON at most 2,000,000 UTF-8 bytes. Output batches retain at most 100 invoices and 1,000 rows. One invoice larger than a batch is blocked.
- Conflicting customer/dates/currency within an invoice, negative amounts, unsupported number/date formats, formula-like text and unreviewed identical rows block the entire input. This is a conservative local-profile review, not a prediction of every native importer outcome.

### Try the fictional sample

The prefilled input contains **3 fictional invoices / 5 CSV line records**. No QuickBooks login/token, external vendor fetch or customer data is needed. Platform storage/privacy API checks run under your existing Apify permissions. `package` saves at most three invoice receipts for that sample; `preview` produces a free diagnostic summary without CSV/ZIP.

```json
{
  "csvText": "InvoiceNo,Customer,InvoiceDate,DueDate,ItemAmount\nDEMO-001,Fictional Company,2026-01-01,2026-01-31,12.50\n",
  "region": "US",
  "salesTaxEnabled": false,
  "currency": "USD",
  "dateFormat": "ISO",
  "mode": "package"
}
```

### Outputs and charges

**$0.002 per saved whole-invoice validation receipt ($2 per 1,000 invoices)**, a single `invoice-receipt` event. A receipt includes invoice ordinal/key hash, source record and physical-line ordinals, line count, item-amount sum and input SHA256. It contains no CSV row cells or customer names. The item-amount sum is not a verified invoice grand total.

Preview and blocked/invalid input produce diagnostics without invoice receipt charges. There is no startup fee or positive dataset-item charge. Apify documents standard PPE platform-usage accounting and an optional PPE + usage setting. Check the live Apify pricing panel for any platform-usage component; the receipt-event rate alone does not establish that setting. Set `maxTotalChargeUsd` explicitly in API/CLI **run options** (for example `0.01`); it limits invoice receipt events. The default fictional 3-invoice sample has $0.006 of receipt events in receipt-event charges; an owner smoke test is not customer revenue.

`STATE` identifies completion, acknowledged receipt count, budget-limited delivery and available export keys. A budget-limited run can complete with a smaller whole-invoice subset. CSV batches and `native-review-pack.zip` contain **only the invoices whose receipt push/charge acknowledgement was confirmed**. Zero receipt budget creates no CSV/ZIP. Preview does not expose a hidden CSV download.

Apify dataset writes and billing are not one atomic transaction. If a receipt push/charge acknowledgement is uncertain, the Actor stops without its wrapper retrying that uncertain operation or exporting its invoice. A receipt row may already exist or be charged. A later CSV/storage failure can leave useful paid receipts while exports are unavailable: `STATE` is incomplete/failed, and no successful package is claimed. Inspect existing run state before any manual rerun; a new run can incur new charges.

`REVIEW` contains free error codes and source ordinals for preview/blocked inputs. `ERROR` omits supplied values. Each hosted run checks anonymous INPUT access before reading CSV, rejects public/unknown input access, and requests Restricted access for only that run and its default dataset/key-value store. It requires restricted API readback plus unsigned anonymous access denial before processing/charging. If protection cannot be confirmed, it stops. These checks do not change account-wide settings, revoke existing explicit collaborators or prove upload-history privacy. Keep storage/run links, signed share URLs and access permissions under your control. Export download links can be absent until saved; check `STATE` first.

### Native and integrated alternatives

[QuickBooks' native importer](https://quickbooks.intuit.com/learn-support/en-us/help-article/import-export-data-files/import-multiple-invoices/L7E9Xrd8l_US_en_US) already imports and validates invoice CSVs, with up to 100 invoices / 1,000 rows per file; its documented route is unavailable when sales tax is set up. Manual spreadsheet grouping plus the native importer may be enough.

[SaasAnt Quick Import](https://support.saasant.com/support/solutions/articles/14000150088-how-to-use-quick-import-feature-in-saasant-transactions-/) and [Transaction Pro](https://importer.transactionpro.com/Importer/Docs/Import/ImportSteps.aspx) provide broader connected import, mapping and validation workflows. This Actor offers hosted exact-profile preparation and record receipts, rather than those integrations. It is not a unique invoice validator or a replacement for native account checks.

### Limits

No QBO API/import, credentials, tax validation, live tenant validation, automatic repair, XLSX/PDF/OCR, multicurrency or general header mapping. Original cells are preserved, including optional fields; that does not prove native acceptance of every Unicode/control value. Inspect the files and map columns/dates manually before importing. This independent tool is not affiliated with Intuit.

# Actor input Schema

## `csvText` (type: `string`):

Paste your UTF-8 invoice CSV with exact InvoiceNo,Customer,InvoiceDate,DueDate,ItemAmount headings; optional columns retained. Up to 1 MB / 5000 records / 500 invoices. Stored encrypted in Apify cloud. Leave empty to run a free sample review of 3 fictional invoices (not charged).

## `region` (type: `string`):

US-only review profile. This declaration does not verify your QuickBooks account eligibility.

## `salesTaxEnabled` (type: `boolean`):

Must explicitly be false. This native invoice CSV route is out of scope when sales tax is set up; the Actor cannot inspect your account.

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

USD-only candidate restriction, not a universal QuickBooks restriction. Optional Currency cells must also be USD.

## `dateFormat` (type: `string`):

Explicit ISO YYYY-MM-DD, DMY DD/MM/YYYY or MDY MM/DD/YYYY. Dates are never converted or guessed.

## `mode` (type: `string`):

Preview: free diagnostic summary only. Package: one paid receipt per valid whole invoice; CSV/ZIP only for acknowledged receipts.

## `allowDuplicateLines` (type: `boolean`):

False blocks identical repeated lines. True preserves them all after your own review; never deduplicates.

## `fromDate` (type: `string`):

Optional inclusive ISO date YYYY-MM-DD. Values outside period block the entire input.

## `toDate` (type: `string`):

Optional inclusive ISO date YYYY-MM-DD.

## Actor input object example

```json
{
  "region": "US",
  "salesTaxEnabled": false,
  "currency": "USD",
  "dateFormat": "ISO",
  "mode": "package",
  "allowDuplicateLines": false
}
```

# Actor output Schema

## `receipts` (type: `string`):

No description

## `state` (type: `string`):

No description

## `exportReceipt` (type: `string`):

No description

## `pack` (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 = {
    "region": "US",
    "salesTaxEnabled": false,
    "currency": "USD",
    "dateFormat": "ISO",
    "mode": "package"
};

// Run the Actor and wait for it to finish
const run = await client.actor("atesen-software/invoice-csv-preflight-batch-pack").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 = {
    "region": "US",
    "salesTaxEnabled": False,
    "currency": "USD",
    "dateFormat": "ISO",
    "mode": "package",
}

# Run the Actor and wait for it to finish
run = client.actor("atesen-software/invoice-csv-preflight-batch-pack").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 '{
  "region": "US",
  "salesTaxEnabled": false,
  "currency": "USD",
  "dateFormat": "ISO",
  "mode": "package"
}' |
apify call atesen-software/invoice-csv-preflight-batch-pack --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,atesen-software/invoice-csv-preflight-batch-pack"
        }
    }
}
```

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/OpJBFgCEUNB6xkMWW/builds/ECAMEG2tlkwyultAZ/openapi.json