The Billr API

Every endpoint lives under one base URL, speaks JSON, and needs one header. There is no SDK to install and nothing to configure. If you can send an HTTP request, you are ready.

Create a key on the developers page inside your account, then list your five most recent documents:

curl https://billr-app.com/api/v1/invoices?limit=5 \
  -H "Authorization: Bearer billr_live_YOUR_KEY"

That is the whole learning curve. The rest of this page is reference material for when you need a specific field.

Send your key as a bearer token on every request. Keys start with billr_live_ and are tied to one account, so the API never has to be told which organisation you mean.

Authorization: Bearer billr_live_YOUR_KEY

A key is shown to you exactly once, at the moment you create it. Only a hash of it is stored, which means a lost key can be replaced but never recovered. Revoking one takes effect on the next request.

Money is never a decimal number. Every amount is an integer, so nothing is ever off by a cent after a currency conversion or a JSON round trip. Three unit conventions follow from that, and they hold everywhere in the API and in every webhook.

Responses are sent with Cache-Control: no-store. List endpoints wrap their results in an envelope, single records are returned on their own:

{
  "data": [ { … }, { … } ],
  "limit": 50,
  "count": 2
}

Every failure returns the same envelope, with a stable machine readable code and a message written for whoever has to read the log at two in the morning.

{
  "error": {
    "code": "invalid_body",
    "message": "Every line needs a description (lines.0.description)"
  }
}

A 401 also carries WWW-Authenticate: Bearer realm="Billr API", so a generic HTTP client knows what to ask for.

GET/api/v1/invoices

Lists your invoices and credit notes, newest first.

curl "https://billr-app.com/api/v1/invoices?status=PAID&limit=20" \
  -H "Authorization: Bearer billr_live_YOUR_KEY"

POST/api/v1/invoices

Creates a draft and returns it with status 201. The number is assigned for you, in sequence, using the same counter the app uses, so an invoice made through the API sits in the same unbroken series as one made by hand.

Creating is deliberately separate from sending. Nothing is e-mailed to your client until you send it from the app, which means a script with a bug cannot mail a stranger.

curl -X POST https://billr-app.com/api/v1/invoices \
  -H "Authorization: Bearer billr_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "cl_example",
    "dueDate": "2026-09-30",
    "lines": [
      {
        "description": "Design work, September",
        "quantityMilli": 12500,
        "unit": "hour",
        "unitPriceCents": 8500,
        "taxRateBp": 2100
      }
    ]
  }'

Totals are computed for you. A line amount is the quantity times the unit price, tax is summed once per rate rather than once per line, and any discount is spread across the lines in proportion so the printed tax base always reconciles with the total charged.

GET/api/v1/invoices/{id}

Returns one invoice with its lines. An id that belongs to another account answers 404, exactly as one that does not exist, so the API never confirms that a record is out there somewhere.

GET/api/v1/clients

Lists your clients, sorted by name.

POST/api/v1/clients

Creates a client and returns it with status 201. Only a name is required, so a client captured from a form with one field is still a valid client.

curl -X POST https://billr-app.com/api/v1/clients \
  -H "Authorization: Bearer billr_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Amelie Janssens",
    "company": "Studio Noord",
    "email": "[email protected]",
    "city": "Antwerp",
    "country": "Belgium",
    "currency": "EUR"
  }'

There is one definition of an invoice as JSON and one of a client, shared by the endpoints and the webhooks. Anything that can read a webhook can read the API, and the other way round.

The invoice object

{
  "id": "inv_example",
  "number": "2026-0042",
  "type": "INVOICE",
  "status": "SENT",
  "clientId": "cl_example",
  "billTo": {
    "name": "Amelie Janssens",
    "company": "Studio Noord",
    "email": "[email protected]",
    "vatNumber": "BE0123456789",
    "address": "Kloosterstraat 12\n2000 Antwerp"
  },
  "issueDate": "2026-09-01T00:00:00.000Z",
  "dueDate": "2026-09-30T00:00:00.000Z",
  "currency": "EUR",
  "subtotalCents": 106250,
  "discountCents": 0,
  "taxCents": 22313,
  "totalCents": 128563,
  "paidCents": 0,
  "notes": null,
  "terms": "Payment within 30 days.",
  "publicUrl": "https://billr-app.com/i/…",
  "sentAt": "2026-09-01T09:12:44.201Z",
  "viewedAt": null,
  "paidAt": null,
  "createdAt": "2026-09-01T09:11:02.884Z",
  "updatedAt": "2026-09-01T09:12:44.204Z",
  "lines": [
    {
      "id": "ln_example",
      "position": 0,
      "description": "Design work, September",
      "quantityMilli": 12500,
      "unit": "hour",
      "unitPriceCents": 8500,
      "taxRateBp": 2100,
      "amountCents": 106250
    }
  ]
}

The client object

{
  "id": "cl_example",
  "name": "Amelie Janssens",
  "company": "Studio Noord",
  "email": "[email protected]",
  "phone": null,
  "vatNumber": "BE0123456789",
  "address": {
    "line1": "Kloosterstraat 12",
    "line2": null,
    "postalCode": "2000",
    "city": "Antwerp",
    "country": "Belgium"
  },
  "notes": null,
  "currency": "EUR",
  "archived": false,
  "portalUrl": "https://billr-app.com/p/…",
  "createdAt": "2026-08-14T15:02:19.771Z",
  "updatedAt": "2026-08-14T15:02:19.771Z"
}

portalUrl is the client portal: one page holding every invoice you ever sent that client, which you can share once instead of re-sending links.

Add an endpoint on the developers page, choose the events you care about, and Billr posts JSON to your URL as things happen. Nothing has to poll.

The body is the same every time. data holds the invoice object described above, so you rarely need a second call to find out what happened.

{
  "id": "4e1c2f8a-…",
  "event": "invoice.paid",
  "createdAt": "2026-09-14T11:04:52.317Z",
  "data": { … the invoice object … }
}

Verifying a delivery

Sign the raw bytes you received, before any JSON parsing, and compare in constant time. Reformatting the body first will change the signature.

import crypto from "node:crypto";

export function isFromBillr(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody, "utf8")
    .digest("hex");

  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(signature, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

A short list, kept accurate on purpose. Knowing the edges up front is worth more than finding them in production.

• Invoices and clients can be listed and created through the API. Updating and deleting stay in the app for now.
• Sending an invoice by e-mail is an action you take in the app, so a script can never mail a client by accident.
• A webhook is delivered once, with a five second timeout and no retry queue. The last status is recorded on the endpoint so a failure is visible rather than silent.
• There is no rate limit today. Keep your request rate sensible, and if a limit is ever added it will be announced before it takes effect.
• The API is versioned in the path. A change that would break existing code lands on a new version rather than on v1.

Missing something you need? Say so and it goes on the list. The API grows in the direction people actually push it.