# Shopify → QuickBooks Online Reconciliation — CSV Report (`goldenrod_serrano/shopify-qbo-reconciliation`) Actor

Upload Shopify orders (and optional payouts) CSV plus a QuickBooks Online export CSV. Get a pay-per-report discrepancy list: missing in QBO, duplicates, amount/tax/shipping/refund mismatches, fee timing — plus a Markdown/HTML summary. No Shopify or QBO login.

- **URL**: https://apify.com/goldenrod_serrano/shopify-qbo-reconciliation.md
- **Developed by:** [Paopao Studio](https://apify.com/goldenrod_serrano) (community)
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $70.00 / 1,000 reconciliation reports

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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 → QuickBooks Online Reconciliation — CSV Discrepancy Report

After the **Intuit Shopify → QuickBooks Online connector** upgrade, many stores see missing orders, duplicate sales receipts, wrong tax codes, and shipping that never lands in QBO. This Actor does **not** replace the connector and does **not** ask for your Shopify or QBO login.

You upload (or paste) a **Shopify orders export CSV** and a **QuickBooks Online export CSV**. Optionally add a **Shopify payouts / transactions CSV**. The Actor matches them and returns a **discrepancy dataset** plus a **Markdown/HTML summary**: missing in QBO, missing in Shopify, duplicates, amount / tax / shipping / refund mismatches, and fee-vs-payout timing when payouts are provided.

### Who uses it

- **Shopify merchants and bookkeepers** cleaning up after a connector upgrade or switching from A2X / Synder / Webgility / Bold Sync summaries to a one-shot file audit.
- **Agencies** that need a cheap, repeatable CSV check before quoting a full cleanup engagement.
- **Operators** who refuse to hand API keys to a new SaaS just to see which orders never posted.

### Quick start

1. Click **Start** with an empty input (or `sampleMode: true`) → free **synthetic** demo report (not charged, invented fixtures).
2. In Shopify Admin: **Orders → Export** the date range you care about (CSV).
3. In QuickBooks Online: **Reports → Transaction List by Date** (customize columns to include **Num** and **Memo/Description**) → **Export → CSV**. Put the Shopify order name (e.g. `#1001`) in **Num**, or keep it in the memo.
4. Optional: Shopify **Finance → Payouts → View transactions → Export**.
5. Upload the files (or paste / pass HTTPS URLs) and run. One paid **`report`** event covers the whole reconciliation.

Example paid input (URLs):

```json
{
  "shopifyOrdersUrl": "https://example.com/shopify-orders.csv",
  "qboUrl": "https://example.com/qbo-transaction-list.csv",
  "shopifyPayoutsUrl": "https://example.com/shopify-payouts.csv",
  "periodLabel": "2026-09",
  "amountToleranceUsd": 0.01
}
```

### Input

| Field | What it does |
|---|---|
| `sampleMode` | Free synthetic demo. Empty input does the same. **Not real customer data.** |
| `shopifyOrdersCsv` / `shopifyOrdersUrl` | Shopify orders export (file upload editor or URL / paste). |
| `shopifyPayoutsCsv` / `shopifyPayoutsUrl` | Optional Shopify Payments transactions export. |
| `qboCsv` / `qboUrl` | QBO Transaction List (or similar) CSV. Preamble rows are skipped automatically. |
| `amountToleranceUsd` | Match tolerance (default `$0.01`). |
| `includeMatched` | Also emit `matched` rows for a full audit trail. |
| `periodLabel` | Label stored on the summary (does not filter). |
| `shopifyOrdersColumnMap` / `shopifyPayoutsColumnMap` / `qboColumnMap` | Optional header overrides when your export uses non-standard names. |

#### Field formats verified

- **Shopify orders CSV** — official headers `Name`, `Financial Status`, `Paid at`, `Currency`, `Subtotal`, `Shipping`, `Taxes`, `Total`, `Created at`, `Lineitem *`, … ([Shopify Help: Exporting orders](https://help.shopify.com/en/manual/fulfillment/managing-orders/exporting-orders)). Multi-line-item orders are aggregated by `Name`.
- **Shopify payouts / transactions CSV** — `Transaction Date`, `Type`, `Order`, `Payout Status`, `Payout Date`, `Amount`, `Fee`, `Net`, … ([Shopify Help: Viewing and exporting payout details](https://help.shopify.com/en/manual/payments/shopify-payments/payouts/view-details)).
- **QBO Transaction List by Date CSV** — typical columns `Date`, `Transaction Type`, `Num`, `Name`, `Memo/Description`, `Account`, `Amount`, `Balance`; company/title/date-range preamble and total rows are skipped (QBO report export behaviour as documented by Intuit-oriented export guides).

Complaint themes that shaped the checks (Shopify App Store reviews of the Intuit connector and peers such as Bold Sync / A2X): missing orders after forced upgrades, duplicate invoice/receipt numbers, tax-code chaos, shipping omitted, refunds that do not match, and payout-date vs capture-date timing when using summary posting tools.

### Output

**Dataset**

1. One `record_type=summary` row (counts, totals, notes).
2. One `record_type=discrepancy` row per finding.

| `type` | Meaning |
|---|---|
| `missing_in_qbo` | Shopify order id not found in QBO Num/memo |
| `missing_in_shopify` | QBO row with `#order` id not in the Shopify export |
| `duplicate_in_qbo` | Two or more QBO rows share the same order id |
| `amount_mismatch` | Totals differ beyond tolerance (not explained by tax/shipping alone) |
| `tax_mismatch` | Delta matches tax (or QBO equals subtotal, omitting tax/shipping) |
| `shipping_mismatch` | Delta matches shipping |
| `refund_mismatch` | Refund / credit amounts differ |
| `fee_timing` | QBO date vs pending/in-transit Shopify payout date (needs payouts CSV) |
| `matched` | Only when `includeMatched` is on |

**Key-value store:** `REPORT.md`, `REPORT.html`, `SUMMARY.json`.

### Pricing (pay per event)

One event: **`report`** — one full reconciliation (summary + every discrepancy row for that run).

| Your Apify plan tier | Price per report |
|---|---|
| Free (list price) | **$0.10** |
| Bronze (−10%) | $0.09 |
| Silver (−20%) | $0.08 |
| Gold / Platinum / Diamond (−30%) | $0.07 |

Rationale: same shape as [Lead Leak Check](https://apify.com/goldenrod_serrano/lead-leak-check-apify)’s `report` event ($0.05), priced higher because each run parses multiple CSVs, classifies several discrepancy classes, and returns an audit artifact bookkeepers actually hand to a client. Freelancer cleanup / reconciliation jobs in this niche commonly clear **$200–$500+**; this Actor is the cheap first pass. The free synthetic sample is never charged. Platform compute is small (CSV only, no browser, no proxy).

### Related Actors by PaoPao Studio

- [Lead Leak Check](https://apify.com/goldenrod_serrano/lead-leak-check-apify) — offline Zapier/Make/n8n lead-pipeline audit (ops checklist companion to this finance reconciliation).
- [SEC Form D Scraper](https://apify.com/goldenrod_serrano/sec-form-d-funding-signals) — new US private placements from SEC EDGAR Form D filings.
- [NCUA Credit Union Call Report Scraper](https://apify.com/goldenrod_serrano/ncua-call-report) — every US credit union's 5300 call report (net worth, growth, risk flags).

### Limitations & compliance

- **Files only.** No Shopify Admin API, no QuickBooks Online API, no OAuth. You control what leaves your books.
- Matching keys off Shopify `Name` / payouts `Order` and QBO `Num` (or `#id` inside Memo). If your connector posts **summary journals by payout** with no per-order Num, per-order matching will under-match — use this Actor on a per-order export or ask your bookkeeper for a transaction list that still carries order ids.
- Currency: amounts are compared as decimal values in the file; multi-currency stores should export one currency at a time.
- Not tax, accounting, or legal advice. Discrepancy labels are heuristics for bookkeepers to review.
- Do not upload files that contain secrets you are not allowed to process. The Actor stores run I/O in your Apify account like any other Actor.

### Changelog

- **0.1.0** — Initial release: orders + QBO matching, optional payouts, PPE `report`, synthetic sample.

# Actor input Schema

## `sampleMode` (type: `boolean`):

Run the built-in synthetic Shopify + QBO fixtures and return a demo discrepancy report without charging. An empty input does the same. Fixtures are invented test data, not a real store.

## `shopifyOrdersCsv` (type: `string`):

Shopify Admin → Orders → Export CSV (or paste the file contents). Official columns include Name, Financial Status, Currency, Subtotal, Shipping, Taxes, Total, Created at, Lineitem \*. Multi-line-item orders are aggregated by Name. See https://help.shopify.com/en/manual/fulfillment/managing-orders/exporting-orders

## `shopifyOrdersUrl` (type: `string`):

Public HTTPS URL to a Shopify orders export CSV if you prefer not to upload. Ignored when shopifyOrdersCsv is set.

## `shopifyPayoutsCsv` (type: `string`):

Optional. Finance → Payouts → Export transactions CSV (Transaction Date, Type, Order, Amount, Fee, Net, Payout Date/Status). Enables fee_timing findings. See https://help.shopify.com/en/manual/payments/shopify-payments/payouts/view-details

## `shopifyPayoutsUrl` (type: `string`):

Public HTTPS URL to a Shopify payouts/transactions CSV. Ignored when shopifyPayoutsCsv is set.

## `qboCsv` (type: `string`):

QBO Reports → Transaction List by Date (or Transaction Detail) → Export CSV. Preamble rows (company name, report title, date range) are auto-skipped. Prefer columns Date, Transaction Type, Num, Name, Memo/Description, Account, Amount. Put the Shopify order id in Num (e.g. #1001) or in the memo.

## `qboUrl` (type: `string`):

Public HTTPS URL to a QBO export CSV. Ignored when qboCsv is set.

## `amountToleranceUsd` (type: `number`):

Differences at or below this absolute amount are treated as matched. Default 0.01 (one cent).

## `includeMatched` (type: `boolean`):

When on, dataset includes type=matched rows for orders whose amounts agree within tolerance (useful for a full audit trail). Still one charged report event.

## `periodLabel` (type: `string`):

Free-text label stored on the summary (e.g. 2026-09). Does not filter rows — filter in Shopify/QBO before export.

## `shopifyOrdersColumnMap` (type: `object`):

Optional map of canonical field → your CSV header when aliases fail. Canonical keys: name, total, taxes, shipping, subtotal, financial_status, created_at, paid_at, currency, email, discount_amount, lineitem_sku, lineitem_name, lineitem_quantity. Example: {"total": "Order Total"}.

## `shopifyPayoutsColumnMap` (type: `object`):

Optional map for payouts CSV. Canonical keys: transaction_date, type, order, amount, fee, net, payout_date, payout_status, currency, payout_id.

## `qboColumnMap` (type: `object`):

Optional map for QBO CSV. Canonical keys: date, transaction_type, num, name, memo, account, amount, balance, class, split. Example: {"num": "Doc Number", "memo": "Description"}.

## Actor input object example

```json
{
  "sampleMode": false,
  "amountToleranceUsd": 0.01,
  "includeMatched": false
}
```

# Actor output Schema

## `results` (type: `string`):

Summary + discrepancy rows (type, severity, order_id, amounts, detail, suggestion).

## `reportMarkdown` (type: `string`):

REPORT.md in the default key-value store.

## `reportHtml` (type: `string`):

REPORT.html in the default key-value store.

## `summaryJson` (type: `string`):

SUMMARY.json in the default key-value store.

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("goldenrod_serrano/shopify-qbo-reconciliation").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("goldenrod_serrano/shopify-qbo-reconciliation").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 '{}' |
apify call goldenrod_serrano/shopify-qbo-reconciliation --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,goldenrod_serrano/shopify-qbo-reconciliation"
        }
    }
}
```

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/mxz1JCUf3nYMQUheT/builds/fnvvqPENOR99Rn9sl/openapi.json