← Billy API integration

Billy API: a practical guide

What you need to know to read data from Billy: one access token per company, pages of at most 1,000, related data with include and amounts that live on postings. The examples use exactly the paths and parameters JaKonto itself calls.

Contents

  1. Authentication: X-Access-Token
  2. Paging: page and pageSize
  3. Related data: include with sideload or embed
  4. Invoices: state, isPaid and balance
  5. Postings: the amounts live on /postings
  6. Pitfalls we hit ourselves
  7. Or let JaKonto do it

Authentication: X-Access-Token

The base URL is https://api.billysbilling.com/v2, HTTPS only. Send your access token in the X-Access-Token header.

You create the token in Billy under Settings → Access tokens → Create access token. It belongs to one company and does not expire — if you have several companies, each needs its own. Store it encrypted.

curl https://api.billysbilling.com/v2/organization \
     -H "X-Access-Token: <ACCESS_TOKEN>" \
     -H "Content-Type: application/json"

Paging: page and pageSize

Lists take page and pageSize. pageSize is at most 1,000, which is also the default. The response has meta.paging with page, pageCount, pageSize, total and nextUrl — keep going until page reaches pageCount.

import requests

H = {"X-Access-Token": "<ACCESS_TOKEN>"}
invoices, page = [], 1
while True:
    data = requests.get("https://api.billysbilling.com/v2/invoices", headers=H, timeout=30,
                        params={"page": page, "pageSize": 1000}).json()
    invoices += data["invoices"]
    if page >= data["meta"]["paging"]["pageCount"]:
        break
    page += 1

Related data: include with sideload or embed

With include=resource.property:mode you get related objects in the same response. sideload (the default) puts them in a separate list alongside — e.g. contacts next to invoices; embed puts them inside each object.

Responses use singular and plural root keys: {"invoice": {…}} for one object, {"invoices": […]} for a list.

curl -G https://api.billysbilling.com/v2/invoices \
     --data-urlencode 'include=invoice.contact:sideload' \
     -H "X-Access-Token: <ACCESS_TOKEN>"

→ {"meta": {…}, "invoices": [{"contactId": "…", …}], "contacts": [{"id": "…", "name": "…"}]}

Invoices: state, isPaid and balance

state is only draft, approved or voided. Whether an invoice is paid is not in state but in isPaid (true/false), and the unpaid remainder is in balance. Both are read-only and change when a payment is registered.

To find overdue invoices, take approved ones with isPaid=false and a dueDate before today.

Postings: the amounts live on /postings

Amount, account and side (debit/credit) live on /postings, not on /transactions. Limit the period with minEntryDate and maxEntryDate (YYYY-MM-DD), leave out voided ones with isVoided=false and pull account and voucher with include.

curl -G https://api.billysbilling.com/v2/postings \
     --data-urlencode 'minEntryDate=2026-01-01' \
     --data-urlencode 'maxEntryDate=2026-06-30' \
     --data-urlencode 'isVoided=false' \
     --data-urlencode 'include=posting.account:sideload,posting.transaction:sideload' \
     -H "X-Access-Token: <ACCESS_TOKEN>"

Pitfalls we hit ourselves

  • Unknown or misspelled parameters are silently ignored — you get the whole list unfiltered. entryDatePeriod, for example, must be written dates:2026-01-01...2026-06-30 with three dots; with a comma every posting comes back.
  • A paid invoice still has state approved. Look only at state and every paid invoice counts as an open receivable.
  • Amounts are kroner with decimals; convert to øre (integers) before you add them up.
  • Billy has no documented webhooks. Changes have to be fetched with scheduled syncs.
  • Billy documents no rate limits. Fetch large pages (pageSize=1000) and don't run parallel calls against the same company.

Or let JaKonto do it

JaKonto handles the token, paging, sideloads, payment status and postings and gives you invoices, entries, accounts and contacts in the same shape as from e-conomic and Dinero — plus VAT, profit and loss and CSV. The Billy integration is in beta. Connect with your token:

curl -X POST https://jakonto.dk/api/v1/connections \
     -H "X-API-Key: jk_live_…" -H "Content-Type: application/json" \
     -d '{"system": "billy", "credentials": {"access_token": "<ACCESS_TOKEN>"}}'

curl https://jakonto.dk/api/v1/connections/$ID/invoices \
     -H "X-API-Key: jk_live_…"

Questions

Where is the official Billy API documentation?

At billy.dk/api. It describes every resource, its fields and the filters a list accepts.

Where do I find my Billy access token?

In Billy under Settings → Access tokens. The token belongs to one company and does not expire.

How many items can I fetch per page?

At most 1,000 (pageSize=1000), which is also the default.

Does Billy have webhooks?

None documented. Changes are fetched by syncing regularly.

Does JaKonto write to Billy?

No. JaKonto only reads.

e-conomic API integration · Billy API integration · Dinero API integration · MCP server