BillingHub API

Quick start

Mint a key on your API & webhooks settings page, then ask for your credit balance. It is the smallest request there is, and it proves the key works before you create anything with it.

curl https://billinghub.online/api/v1/balance \
  -H "Authorization: Bearer bh_live_a1b2c3d4_YOUR_SECRET"

{"credits": 42}

Every request goes to https://billinghub.online over HTTPS, sends and receives JSON, and carries the key in an Authorization header.

Authentication

A key looks like bh_live_<prefix>_<secret> and goes in one place:

Authorization: Bearer bh_live_a1b2c3d4_YOUR_SECRET

Never in a query string. A key in a URL lands in access logs, proxy logs and browser history, and you cannot get it back out of any of them. Requests that put it anywhere but this header are refused.

The secret is shown once, by the page that mints it. We store a hash, so nothing can show it to you again — if you lose it, mint another key and revoke the old one. Revoking takes effect immediately.

Keys are per account, not per user, and each one is rate limited on its own. Give a separate key to each integration: if one runs away, the others keep working.

Rate limit

60 requests a minute, per key. Not per address — a key names exactly one account, so one office behind one connection is not sharing a budget with its neighbours, and one integration spread over twenty hosts does not get twenty budgets.

Over the limit answers 429 with a Retry-After header giving the seconds to wait. Documents are created when work is done rather than in a loop, so this is here to stop a runaway retry, not to meter you: what you are sold is credits.

Errors

A refusal carries a JSON body — {"error": "…"}, or {"errors": {…}} when individual fields are at fault. The status code is the part to branch on, and the four that get confused mean genuinely different things:

Every failure under /api/ answers this way, whatever Accept you sent and however deep it happened — an unknown path, a rejected key, a malformed body, an outage of ours. One shape, one field to read: error. You will never get an HTML page here.

{
  "errors": {
    "buyer.name": "This field is required.",
    "items.0.rate": "This amount could not be read."
  }
}

Idempotency

Two requests here spend money — creating a document and issuing one — and a timeout tells you nothing about whether either went through. Send an Idempotency-Key header on POST /api/v1/documents/<type> or on POST /api/v1/documents/<reference>/issue and you can retry the same request as often as you like: the first one does the work, and every later one is answered with that same first response.

curl -X POST https://billinghub.online/api/v1/documents/invoice \
  -H "Authorization: Bearer bh_live_a1b2c3d4_YOUR_SECRET" \
  -H "Idempotency-Key: 8f14e45f-ea2b-4c53-9d6f-1b0a7c2e5a91" \
  -H "Content-Type: application/json" \
  -d '{ … }'

Use a fresh key — a UUID is the usual choice — for each document you mean to create, and reuse it for every retry of that one. A replayed answer carries Idempotency-Replayed: true, so you can tell it from a document that was created just now.

A key is a promise about one request. Reusing one with a different body answers 409 rather than handing back the first document, because that would be us quietly returning the wrong answer. A key belonging to a request still in flight answers 409 too; retry it in a moment.

Keys are remembered for 24 hours and are scoped to your account, so they need only be unique to you. Only a success is remembered: a request refused with 402 or 422 created nothing and charged nothing, so the key is free again immediately and the retry those statuses ask for is the retry you can make. Use a fresh key per document — one key cannot cover creating a document and then issuing it, and reusing it across the two answers 409.

The header is optional and no other endpoint takes it — reads have nothing to duplicate, and a send is already safe to repeat.

Endpoints

<type> is invoice, estimate or quote. <reference> is the id a document is created with — the same one that appears in its portal URL.

{"credits": 42}

curl -X POST https://billinghub.online/api/v1/documents/invoice \
  -H "Authorization: Bearer bh_live_a1b2c3d4_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "issue": true,
    "number": "INV-0042",
    "currency": "USD",
    "buyer": {
      "name": "Northwind Trading",
      "email": "ap@northwind.example",
      "addressLine1": "12 Harbour Road",
      "city": "Portland",
      "zipCode": "97205"
    },
    "items": [
      {
        "name": "Site survey",
        "description": "Half a day on site",
        "quantity": 1,
        "rate": "450.00",
        "taxes": [{"name": "Sales Tax", "rate": 8250}]
      },
      {
        "name": "Drone photography",
        "quantity": 3,
        "rate": "120.00"
      }
    ],
    "notes": "Thank you for your business.",
    "terms": "Payment due within 14 days."
  }'

{
  "reference": "K3mQ8vT2xLpZ",
  "type": "invoice",
  "status": "issued",
  "number": "INV-0042",
  "pdfUrl": "https://billinghub.online/api/v1/documents/K3mQ8vT2xLpZ/pdf"
}

GET /api/v1/documents/invoice?limit=25&offset=50

{
  "documents": [
    {
      "reference": "K3mQ8vT2xLpZ",
      "type": "invoice",
      "status": "issued",
      "number": "INV-0042",
      "issuedAt": "2026-08-09",
      "currency": "USD",
      "totalCent": 84150
    }
  ],
  "total": 128
}

{
  "reference": "K3mQ8vT2xLpZ",
  "type": "invoice",
  "status": "issued",
  "number": "INV-0042",
  "currency": "USD",
  "issuedAt": "2026-08-09",
  "dueAt": "2026-08-23",
  "yourReference": "PO-88123",
  "buyer": {
    "name": "Northwind Trading",
    "email": "ap@northwind.example",
    "addressLine1": "12 Harbour Road",
    "addressLine2": "",
    "city": "Portland",
    "state": "",
    "zipCode": "97205",
    "country": "USA"
  },
  "items": [
    {
      "name": "Site survey",
      "description": "Half a day on site",
      "quantity": 1,
      "unitPriceCent": 45000,
      "amountCent": 45000,
      "taxes": [{"name": "Sales Tax", "rate": 8.25, "number": ""}]
    }
  ],
  "subtotalCent": 81000,
  "discountPercent": null,
  "discountCent": 0,
  "taxCent": 3150,
  "shippingCent": 0,
  "paidCent": 0,
  "totalCent": 84150,
  "amountDueCent": 84150,
  "notes": "Thank you for your business.",
  "notesName": "",
  "terms": "Payment due within 14 days.",
  "termsName": "",
  "payUrl": "https://billinghub.online/pay/9f3c…",
  "pdfUrl": "https://billinghub.online/api/v1/documents/K3mQ8vT2xLpZ/pdf"
}

curl https://billinghub.online/api/v1/documents/K3mQ8vT2xLpZ/pdf \
  -H "Authorization: Bearer bh_live_a1b2c3d4_YOUR_SECRET" \
  -o invoice-0042.pdf

{
  "reference": "K3mQ8vT2xLpZ",
  "type": "invoice",
  "status": "issued",
  "number": "INV-0042",
  "changed": true,
  "pdfUrl": "https://billinghub.online/api/v1/documents/K3mQ8vT2xLpZ/pdf"
}

{
  "status": "queued",
  "recipient": "ap@northwind.example"
}

{
  "reference": "K3mQ8vT2xLpZ",
  "type": "invoice",
  "status": "paid",
  "number": "INV-0042",
  "changed": true,
  "pdfUrl": "https://billinghub.online/api/v1/documents/K3mQ8vT2xLpZ/pdf"
}

Request body

Only buyer.name is required. Everything else is optional and has a sensible default; a value that is present and malformed is what gets refused.

Everything in this table is applied to the document. The one field that is refused rather than used is logo, and it answers 422 saying so: a document prints the logo on your business profile, and a request that seemed to set one and did not is worse than one that was turned away.

Limits

One request is bounded, so that no single document can hold a worker for a minute. Everything here is refused with 422 naming the field, before any of the work it bounds is done.

The two document-wide ones exist because the per-field limits multiply: 100 items each carrying 20 taxes is 2000 places a tax gets printed, which every individual limit accepted and which cost a minute of a worker to render.

Webhooks

Register an endpoint on your API & webhooks settings page and we POST JSON to it when something happens that you cannot learn any other way without polling. Your signing secret is shown there whenever you need it.

{
  "event": "invoice.paid",
  "data": {
    "reference": "K3mQ8vT2xLpZ",
    "type": "invoice",
    "status": "paid",
    "number": "INV-0042",
    "totalCent": 84150,
    "currency": "USD"
  }
}

Verifying a delivery

Every delivery carries a signature over the exact bytes we sent, in Stripe's shape — if you have wired up Stripe, you have written this already:

BillingHub-Signature: t=1786195200,v1=5257a869e7ecebeda32affa62cdca3fa…

v1 is HMAC-SHA256 of <t>.<raw body>, keyed with your endpoint's secret. The timestamp is inside the signed string, not merely beside it: that is what stops a captured delivery being replayed at you for ever. Reject anything more than 300 seconds out of date, and compare in constant time.

Sign the raw request body, before any JSON parsing — re-encoding it changes the bytes and the signature will not match.

function verify(string $body, string $header, string $secret): bool
{
    $parts = [];
    foreach (explode(',', $header) as $piece) {
        $pair = explode('=', trim($piece), 2);
        if (count($pair) === 2) {
            $parts[$pair[0]] = $pair[1];
        }
    }

    $timestamp = $parts['t'] ?? '';
    $signature = $parts['v1'] ?? '';

    if (!ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) {
        return false;
    }

    return hash_equals(
        hash_hmac('sha256', $timestamp . '.' . $body, $secret),
        $signature
    );
}

const crypto = require('crypto');

function verify(body, header, secret) {
  const parts = Object.fromEntries(
    header.split(',').map((piece) => piece.trim().split('=', 2))
  );

  const timestamp = Number(parts.t);
  if (!Number.isInteger(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(timestamp + '.' + body)
    .digest();
  const given = Buffer.from(parts.v1 || '', 'hex');

  return expected.length === given.length
    && crypto.timingSafeEqual(expected, given);
}

Retries

Answer 2xx and the delivery is done. Anything else, or no answer at all, is retried five times with a widening gap — 30 seconds, then 1, 2 and 4 minutes — and then given up on. Two deliveries of one event can reach you if a retry crosses a slow answer, so key your side off data.reference and the event name and make handling one twice cost nothing.

An endpoint must be a public http or https address — use https, because the payload carries your client's name and your figures. Private, loopback and link-local addresses are refused when you register the endpoint and checked again before every delivery, since a name can start resolving somewhere else in between. Redirects are not followed.