Request a guide
Post the problem in the "docs requests" category. If two more people want it, it goes on the writing queue that month.
Every guide, grouped by what you are trying to do.
Twenty-two written guides across six topics. Each one ends in working code against the sandbox, and each names the endpoints and scopes it touches so you know what a key needs before you start.
(02) — Suggested order
If you have four hours, read these four.
The rest of the library is reference-by-need. This track takes you from an empty workspace to a reconciled month.
Step 01
Post your first entry
Keys, scopes, and the one rule that governs everything: lines must sum to zero.
~20 min · sandbox
Step 02
Design the chart of accounts
Naming, nesting with colons, and why you should not encode reporting structure into account names.
~45 min · design work
Step 03
Make writes safe to retry
Idempotency keys derived from your own domain, and how to read a 409 without panicking.
Step 04
Close a reconciliation window
Open a window against a statement, match lines, and read the residual before you sign off.
~60 min · code
(03) — Index
The full library.
Filter by level. Every guide states the endpoints it calls, so you can check a key's scopes before you open the page.
Getting started
4 guidesFrom nothing to a balanced posting. Read in order the first time.
01Beginner
Post your first balanced entry
Create a workspace, take a sandbox key, and write two lines that sum to zero. Ends with a 201 and an entry ID you can fetch back.
POST /v2/entries20 min02Beginner
Keys, scopes and environments
Why a read key cannot post, how sk_test_ and live keys are kept apart, and where to rotate a key that leaked into a log.
entries:read15 min03Beginner
Reading an entry back
Fetch a posting with its lines, and understand which fields are derived rather than stored — including balanced.
GET /v2/entries/:id10 min04Beginner
Sandbox habits that survive production
What the sandbox resets, what it does not, and the three checks worth wiring into CI before your first live key exists.
sandbox25 minAccounts & the chart
4 guidesThe chart of accounts is the one thing that is genuinely hard to change later. These four are worth the time.
05Intermediate
Designing a chart that survives a rewrite
Colon-nested names like cash:operating and ar:acme-holdings, plus the reporting structure you should keep out of the name.
POST /v2/accounts45 min06Intermediate
Balances are derived, not stored
Why there is no balance column, what that buys you in an audit, and how the at parameter turns any timestamp into a balance.
GET /v2/accounts/:id/balance30 min07Intermediate
Renaming and re-tagging safely
PATCH /v2/accounts/:id changes the label, never the history. What downstream reports see, and when to open a new account instead.
PATCH /v2/accounts/:id20 min08Advanced
Multi-currency lines in one entry
Each currency must balance independently. How the FX line is expressed, and why rounding is settled at write time rather than at read.
POST /v2/entries50 minWrites, retries & idempotency
3 guidesEverything about making a write safe to send twice. The core concept article lives on the overview page.
09Intermediate
Idempotent postings — the full article
Replay behaviour, the Replayed: true header, the 24-hour window, and every outcome for a repeated key including 409 idempotency_conflict.
Idempotency-Key35 min10Intermediate
Deriving keys from your own domain
Invoice IDs, payout batches, settlement references. A recipe for keys that are stable across process restarts and job requeues.
POST /v2/entries25 min11Advanced
Backoff that respects the rate limiter
Reading X-RateLimit-Remaining and Retry-After, and why replays do not spend your write budget.
42930 minReconciliation
4 guidesMatching the ledger against something outside it — a bank statement, a processor payout file, a partner report.
12Intermediate
Reconciliation windows, end to end
Open a window against a statement date range, match lines, read the residual, and close it. The full reference article.
POST /v2/reconciliations60 min13Advanced
Matching strategies for messy statements
Exact, amount-and-date, and many-to-one matches. When to let a residual stand overnight rather than force a match.
recon:write55 min14Advanced
What a non-zero residual actually means
Timing, fees, and genuine breaks — told apart by where the residual sits. A decision tree you can hand to an operations team.
residual40 min15Intermediate
Correcting with reversing entries
Nothing is edited. Post a reversal that references the original, then post the correction — and keep the audit chain intact.
POST /v2/entries30 minOperating in production
4 guidesWebhooks, limits, regions and the things that only matter once real money is moving through the ledger.
16Intermediate
Webhook subscriptions per event type
Subscribing, verifying signatures, and the exponential retry schedule that spans six hours before a delivery is abandoned.
DELETE /v2/webhooks/:id40 min17Intermediate
Living inside 600 writes a minute
Batching, queue shapes, and the burst allowance. Includes a worked example of a month-end posting job that fits comfortably.
X-RateLimit-Remaining35 min18Beginner
Choosing a region, and why it is permanent
Dublin, Frankfurt, Virginia or Sydney — pinned at workspace creation. What to do if you picked wrong.
eu-dublin-115 min19Advanced
Exporting the whole history
Cursor-walking GET /v2/entries as newline-delimited JSON, and what the audit hash chain lets you prove afterwards.
ledger export --all30 minMigrations
3 guidesMoving onto Ledgerdoc, and moving between its major versions. Each names the release that changed the behaviour.
20Advanced
Off PATCH /v2/entries/:id (v2.2.0)
The edit endpoint was removed when immutability moved into the storage layer. The reversal pattern that replaces it, with code.
v2.2.045 min21Intermediate
From /v2/hooks to /v2/webhooks (v2.3.0)
The legacy alias is gone and subscriptions are now per event type. A mechanical rewrite, but the event list changed shape.
v2.3.025 min22Advanced
Importing a spreadsheet ledger
Backdating with posted_at, deriving idempotency keys from row identity, and proving the opening balances tie out.
POST /v2/entries90 min
No guides at this level
Nothing in the library matches that filter yet. Choose another level, or browse all 22.
(04) — Missing something
Ask for a guide that does not exist.
Most of this library started as a forum thread. If you had to work something out yourself, say so and we will write it up.
Office hours
Thursdays at 16:00 UTC. Bring a failing request and an engineer will read the trace with you — often faster than any guide.
Fix a guide yourself
Every page has an "edit this page" link into the docs repository. Copy corrections are merged without ceremony.
Read the reference while you write.
The reference is the same eight endpoints the guides call, with every field and error code spelled out. Keep it in a second tab.
Perfect for: platform teams replacing a spreadsheet ledger with something auditable