How bookkeeping records work

When to use these endpoints

Use the bookkeeping endpoints when your app keeps a company's books: it enters vendor bills, records card and bank expenses, books adjusting journal entries, or raises invoices, and needs to correct them later.

Each record gets a HelloLedger ID when you create it (bill_id, expense_id, journal_id, invoice_id). Save it and use it in the URL for every later read, edit, post, or void.

Syncing charges and payments from a billing system by your own IDs instead? Use the receivables endpoints (PUT …/by-external-id/…). Both work on the same company.

Draft, posted, voided

Every record starts as a draft or is posted right away. Send "post": true on create to post immediately; leave it out to save a draft that changes nothing in the ledger until you post it.

• A voided record stays voided. Create a new one for the corrected version.
• A record that has been paid, credited, or matched to a bank transaction returns 409. Undo that in HelloLedger first.
• Dates in a period that has been reconciled return 409 period_reconciled.
• Records created by other integrations (Stripe, daily revenue, and so on) can be read but not changed, and return 409 managed_by_integration.

Your own ID (optional)

Send external_id with any record to store your system's ID next to it. HelloLedger doesn't use it to find records; the HelloLedger ID is the key. It is returned on every read, and the list endpoints accept ?external_id= so you can find a record if you lost its HelloLedger ID.

Retrying a create safely

Network errors happen. Send an Idempotency-Key header (1–128 letters, numbers, and . _ : -) on every create. If you send the same key with the same body again, HelloLedger returns the record it already created with 200 and result: unchanged, instead of creating a second one.

Reusing a key with a different body returns 409 idempotency_key_reused. Use a new key for each new record, such as your own record ID.

Idempotency-Key: bill-INV-77-2026-10

Vendors and customers

Bills and expenses name a vendor, and invoices name a customer. Send either the HelloLedger ID (vendor_id, customer_id) or a details block (vendor, customer).

With a details block, HelloLedger looks for an existing vendor or customer with the same name, ignoring case. If none exists, it creates one, marks it needs_review so the bookkeeper can check it, and returns vendor_created: true (or customer_created: true). Create vendors up front with POST /vendors if you'd rather control the details.

Scopes

The Bookkeeping sync template on Profile → Developers grants all of these. A write scope also lets the key read that resource.

The result field

Write responses include result: created, updated, posted, voided, or unchanged, so you know what happened without reading the record again.