Import into QuickBooks — CSV, Excel & PDF

• Overview
• From
• Into

Importing for your users — or for yourself?

Building a product that writes into QuickBooks? A product that writes customers, invoices or bills into clients’ books, tools for accounting practices — this page is your integration guide: your users bring files, clean records land in the books (and your backend sees every row first), and nobody leaves your app. Read on.

Just trying to get your own file into QuickBooks? You have the file and the books; the file is the problem — renamed headers, merged columns, a PDF where a spreadsheet should be. See the wizard handle genuinely messy files in the playground (free, no signup). And a run-it-yourself importer is in the works: authorized through your own Intuit login, runs on your machine, every row staged for review — and revertible after it lands. Join the waitlist.

Goal: your users bring the file they have — CSV, Excel, even a PDF or a scan — and clean records land in QuickBooks Online without leaving your product, and without you writing a mapping/validation UI. The pattern is the same every time: embed → validate → deliver. Mildport handles the first two; your webhook handler owns the write into QuickBooks Online.

1. Embed the importer

<mildport-import
  api-base-url="https://imports.your-infra.example"
  license-key="SIGNED_TENANT_KEY"
  catalog-key="quickbooks"
></mildport-import>

2. Publish a catalog that mirrors QuickBooks Online

The schema lives in a target catalog, not in host code. Create it in the catalog editor (/admin/catalogs on your engine, or embed <mildport-catalog-editor>), match Customers (and Invoices if you write those), and publish. The widget loads that published catalog by catalog-key.

Display name is required on a Customer. Keep keys aligned with the QBO resource (DisplayName, PrimaryEmailAddr, PrimaryPhone, CompanyName) so the apply payload is a thin map onto the API.

Users then upload anything — renamed headers, six languages, XLSX/ODS, even PDF tables — and Mildport’s deterministic matcher plus the review step produce typed, validated rows.

Need the schema computed per user at runtime, or versioned with your app? That’s the schema-as-code path — pass targets from host code instead of catalog-key.

3. Deliver from your webhook

Clean rows arrive on your signed apply webhook; your handler writes to QuickBooks Online:

POST /v3/company/{realmId}/customer (OAuth2) — or the $batch endpoint, 30 operations per request

QuickBooks Online-specific gotchas

• DisplayName must be UNIQUE per company — query-and-upsert instead of blind create, or imports die on the first returning customer.
• updates require the current SyncToken (optimistic locking): fetch → merge → update in the handler.
• throttling is per-realm — pace batches and honor Retry-After on 429s.

Why not hand-rolled import?

QBO’s own import is an accountant-facing tool inside QuickBooks. If your product provisions customers or invoices into a client’s books, the import UX belongs in YOUR app — with validation before anything touches the ledger.

---

Try the flow first: the playground (no signup), then the Quickstart and target catalogs. Prices are published — hosted and flat-annual self-host — at mildport.com/#pricing.