reconcilly 0.1.0

Marketplace settlement reconciliation for QuickBooks Online

Reconcilly

Marketplace settlement reconciliation for QuickBooks Online.

Reconcilly turns marketplace export files into balanced journal entries ready for QBO import, plus a reconciliation report and close memo. It runs entirely on your computer; nothing is uploaded to a third party.

What it does

Channel	Inputs	Outputs
Amazon	Monthly Unified Transaction CSV (+ optional Monthly Summary PDF for reconciliation)	One JE CSV per settlement id, plus a close memo and (if PDF supplied) a reconciliation report
Shopify	Orders CSV, Payouts CSV, Taxes CSV	One monthly JE CSV plus a markdown reconciliation report with 9 validation gates
TikTok Shop	Income workbook XLSX	One monthly JE CSV plus a markdown reconciliation report with 11 validation gates

Every JE balances debits = credits to the cent. Validation gates run automatically; FAIL gates block emission unless you explicitly override with a written reason that's recorded in the report.

What it isn't

• Not a QBO connector. Reconcilly produces a CSV; you import it.
• Not multi-tenant. One config.yaml per deployment.
• Not a bookkeeping replacement. It assumes you already know what account names and policies you want; it just builds the JE mechanically from your exports.

Quickstart

git clone <your-fork-or-zip>
cd reconcilly
pip install -e ".[dev]"
cp config.example.yaml config.yaml
# edit config.yaml: set entity codes, channels, cash account names

uvicorn app.main:app --reload
# browse to http://localhost:8000

The web UI lets you upload a settlement file and download a zip with the JE CSV plus the markdown report. There's also a CLI for the Shopify channel:

python -m app.reconciliation.shopify --period 2026-03 \
    --csv-dir samples/2026-03/ --entity ACME

Configuration

All customer-specific values live in config.yaml (gitignored). Copy config.example.yaml and edit:

entities:
  - code: ACME
    label: "ACME LLC"
    channels: [amazon, shopify, tiktok]
    cash_accounts:
      amazon:  "Cash — ACME Amazon"
      shopify: "Cash — ACME Shopify"
      tiktok:  "Cash — ACME TikTok"
    shop_slugs:
      tiktok: ["YOURSHOPSLUG"]

tiktok:
  default_entity: ACME

The full schema is documented in config.example.yaml.

Environment variable overrides (whitelist):

• RECONCILLY_CONFIG_PATH — explicit config file path
• RECONCILLY_USE_GCS — toggle GCS storage (Cloud Run)
• RECONCILLY_GCS_BUCKET — GCS bucket name

Development

pytest                # all synthetic; no setup required
ruff check .          # lint

To run integration tests against your own data, drop real export files under a gitignored samples/ directory; the existing test infrastructure gates real-file tests behind skipif(not PATH.exists()) so they auto-skip when no samples are present.

Deployment

A Dockerfile and deploy/cloudbuild.yaml are included for Google Cloud Run. The cloudbuild substitutes the service / repo / image names; edit those for your project before deploying. Set RECONCILLY_USE_GCS=true and RECONCILLY_GCS_BUCKET=<your-bucket> on the Cloud Run service so uploads and outputs persist across instances.

License

Proprietary. See LICENSE.md for terms (Reconcilly Commercial License v1.0). Contact [e-mail] for licensing or refunds.