Beeswax API: Overview & Quickstart

Build on the Beeswax API. What it covers, how access works, and your first request in five minutes.

Overview

The Beeswax API is a JSON REST API over everything in your account: invoices, quotes, expenses, payments, the ledger, contacts, products & services, projects, tasks, time, documents and (for Australian accounts) tax returns. It is the same API that powers the Beeswax iOS app and the Beeswax MCP server for Claude and other AI assistants, so anything they can do, you can do.

Use it to:

  • Sync your books into a data warehouse, reporting tool or another accounting system, incrementally and without missing a change.
  • Automate bookkeeping: create invoices from your own systems, record payments as they land, post manual journals, keep contacts and your product catalogue current.
  • Reconcile: read any account's posted ledger over a period with opening balance, running balance and closing balance.
  • Connect no-code tools such as Zapier, Make and n8n with nothing more than an HTTP request block.
  • Give an AI assistant safe, scoped access to an account through MCP.

Where things live

I want to… Read
Understand tokens, scopes and account binding Authentication & scopes
Know the request/response conventions, errors and rate limits Requests, responses & errors
Tell what is on the ledger and what is a draft The ledger rule & document lifecycle
Keep a copy of my data in sync, and retry safely Sync & safe retries
Copy a working example: invoice, payment, journal, contact, reconciliation Recipes
Connect Zapier, Make, n8n, a script or an AI assistant Automation tools & assistants
Build a production integration properly Best practices for apps
Look up an endpoint or download the OpenAPI spec Endpoint reference
See what changed Changelog

How access works

Three facts shape every integration. Everything else in these docs follows from them.

  1. One token, one account. A token is bound to exactly one Beeswax account at creation. The account is never a request parameter, so a token can never read or write another account's data, even one the same user belongs to. Bookkeepers create one token per client account.
  2. Scopes decide what a token may do. Each token carries a list of scopes such as invoices:read or payments:write. A request outside the token's scopes is refused with a 403 before any data is touched. Grant the least you need.
  3. Tokens inherit the creating user's role. Scopes set the ceiling; the user's role on that account is still applied. A token with journal_entries:write created by a user whose role cannot post journals gets a 403 on that action, exactly as the web app would refuse them. A token also lasts only as long as its user's membership: remove the person from the account and their tokens stop working.

Tokens are managed under Account Settings → API Tokens by Owners and Super Admins. API access is included on every plan, including Free and the trial.

Quickstart: your first request

What you need: an Owner or Super Admin login to a Beeswax account, and a terminal with curl (or any HTTP client).

1. Create a token

  1. Open Account Settings → API Tokens and click Create New Token.
  2. Name it after the thing that will use it, for example "Reporting sync (read only)". You will thank yourself when you have six.
  3. Tick only the scopes you need. For this walkthrough, invoices:read and accounts:read are enough.
  4. Optionally set an expiry date. Save.
  5. Copy the token now. It is shown once. If you lose it, revoke it and create another.

Full details: API Tokens.

2. Check the connection

GET /meta works with any usable token and tells you what the token is: which account it is bound to, who created it, which scopes it carries, and the server clock.

curl https://app.beeswaxapp.com/new_api/v1/meta \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "latest_mcp_version": "1.7.0",
  "account": { "id": 11, "name": "steam" },
  "user": { "id": 3, "name": "Julian Chow" },
  "scopes": ["invoices:read", "accounts:read"],
  "server_time": "2026-09-07T06:41:12Z"
}

If you get 401 {"error":"Authorization header required"} the header is missing or misspelt. 401 {"error":"Invalid or expired token"} means the token was mistyped, revoked or expired, its account's subscription is not active, or its user no longer belongs to the account.

3. List some invoices

curl "https://app.beeswaxapp.com/new_api/v1/invoices?per_page=2" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "invoices": [
    {
      "id": 16102,
      "type": "Invoice",
      "number": "INV-1043",
      "title": "Brand refresh, phase 2",
      "state": "finalised",
      "posted": true,
      "sent_on": "2026-08-28",
      "due_on": "2026-09-11",
      "total": "4950.0",
      "paid": "0.0",
      "payable": "4950.0",
      "fully_paid": false,
      "overdue": false,
      "currency_code": "AUD",
      "updated_at": "2026-08-28T03:12:45.120Z",
      "project": { "id": 88, "name": "Acme rebrand" }
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 212,
    "total_count": 423,
    "per_page": 2,
    "filter": { "posted": true, "updated_since": null },
    "server_time": "2026-09-07T06:41:20.004Z"
  }
}

Three things to notice, because they recur everywhere:

  • Every listing is wrapped in a key named after the resource plus a meta block with pagination and the filters that were applied.
  • posted: true is the only reliable sign that a document is on the ledger. By default listings return posted documents only. See the ledger rule.
  • Money is a decimal string ("4950.0"), never a binary float. Parse it with a decimal type.

4. Try a filter

Overdue invoices on one project, dated this year:

curl "https://app.beeswaxapp.com/new_api/v1/invoices?overdue=true&project_id=88&from=2026-01-01" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

5. Make a write (optional)

Writes need the matching :write scope and an Idempotency-Key header so a retry can never create a duplicate. The Recipes article walks through creating and finalising an invoice, recording a payment and posting a manual journal, step by step.

Ground rules worth knowing before you build

  • Nothing in the API emails your clients. Creating or finalising an invoice or quote never sends it. Sending, and marking a quote accepted, stay human actions in the web app.
  • Ledger documents are voided, never deleted. DELETE works on drafts only. A finalised invoice or expense is voided, which keeps its number and history and removes it from the ledger.
  • There is no separate sandbox. Sign up for a free Beeswax account to develop against. It has the full API, and nothing you do there touches a real set of books. See Best practices.
  • Rate limits apply per token. 300 requests a minute. A 429 tells you how long to wait. See Requests, responses & errors.
  • Changes are announced. New fields and endpoints are added without notice in the changelog. Anything that changes existing behaviour is called out there as a behaviour change, with the date.

Getting help

  • Search this help centre; the Developers articles are indexed alongside everything else.
  • The in-app Help drawer on the API Tokens page shows the token article and answers questions with these docs.
  • Ask a question or report a problem: Contact, or the Report a Bug link in the app footer, which captures the page and account for you. Include the X-Request-Id header from the failing response and we can find the exact request in our logs.
Browse Topics