# Send payments to Billit

Source: https://developers.weerom.com/docs/use-cases/billit

> Turn every payment a shop notes in WeerOm into an invoice in Billit, from the payment.completed webhook or by polling the payments list.

**For** a shop that sends its invoices from Billit, or any other invoicing tool, and the developer or bookkeeper who connects the two.

A shop notes a payment in WeerOm when a customer pays at the chair. WeerOm does not take the money. It records the amount, the method and the moment. This job makes one invoice in Billit for each of those payments.

| What | You need |
| --- | --- |
| Key | **Read key** A read key, on a server. |
| Webhook | An address for **Payment noted**, which the shop adds in its admin. See [Webhooks](https://developers.weerom.com/docs/webhooks#add-an-address). Optional with polling. |
| Endpoints | `GET /payments`, `GET /shop` for the time zone, `GET /customers/{id}` for a postal code. |
| Billit | An account with API access. Billit documents its API at [docs.billit.be](https://docs.billit.be/docs/get-started). |

## Two ways to run it

| Way | How | Fits |
| --- | --- | --- |
| Webhook | WeerOm posts a `payment.completed` message to your server a few seconds after staff note a payment. | A server with a public HTTPS address. The invoice exists before the customer is out of the door. |
| Polling | A job asks `GET /payments?paid_after=...` every 15 minutes. | A script without a public address, or a shop that invoices once a day. |

Run both when no payment may be missed. The polling job catches a message your server lost while it was down for more than 33 hours. Both check the payment's `id` first, so a payment gets one invoice.

## What a payment holds

```json
{
  "object": "payment",
  "id": "0b6f2a4e-5d1c-4f7a-9a3e-2c8d1e6f4b90",
  "booking_id": "0b6f2a4e-5d1c-4f7a-9a3e-2c8d1e6f4b90",
  "booking_code": "UEAMEFC9",
  "paid_at": "2026-11-21T10:12:40.000Z",
  "starts_at": "2026-11-21T09:30:00.000Z",
  "description": "Knippen en baard",
  "amount_cents": 4000,
  "list_price_cents": 4000,
  "discount_percent": 0,
  "net_cents": 3306,
  "vat_cents": 694,
  "vat_percent": 21,
  "tip_cents": 200,
  "currency": "EUR",
  "method": "bancontact",
  "service_id": "c2a41f6e-8d3b-4e97-b5a0-1f7c9e2d4a68",
  "staff_id": "8e1d5b7c-3a9f-4d20-b6c4-7a2e0f9d1c53",
  "customer": {
    "id": "5f0c9d3a-7b2e-4c61-8a4d-9e1f3b6c2d75",
    "name": "Lotte Peeters",
    "email": "lotte@example.com",
    "phone": "+32470123456"
  }
}
```

## Map a payment to an invoice

The left column is the field in WeerOm. The right column says what it is for on the invoice. Take the field names for the right side from Billit's own API documentation. This page does not name them.

| Payment field | On the invoice |
| --- | --- |
| `id` | Your own record that this payment has an invoice. Store it, so you never invoice a payment twice. |
| `booking_code` | The reference on the invoice. Staff can find the booking in WeerOm by this code. |
| `paid_at` | The invoice date. Convert it from UTC to the shop's `time_zone` from `GET /shop` first, or a payment at 00:30 in Brussels lands on the day before. |
| `customer.name`, `customer.email` | Who the invoice is for. `customer.id` leads to `GET /customers/{id}`, which also has `postal_code`. |
| `description` | The text of the one invoice line: the service's name. |
| `net_cents` | The line's amount without VAT. |
| `vat_percent` | The line's VAT rate. `0` means the shop works under a VAT exemption. |
| `vat_cents` | The VAT on the line. `net_cents + vat_cents` is always `amount_cents`. |
| `amount_cents` | The total the customer paid for the service, VAT included. |
| `currency` | The invoice currency. |
| `method` | How the customer paid, such as `cash` or `bancontact`. Mark the invoice as paid with this method. `null` when staff did not say. |

Amounts are whole cents. Divide by 100 only when your tool wants euros, and round nowhere else: WeerOm has already split the total into net and VAT, rounding half up.

`tip_cents` is not part of `amount_cents`. Whether a tip belongs on the invoice is a question for the shop's accountant.

> **Read each payment soon after it is made.** WeerOm works out `net_cents` and `vat_cents` with the shop's VAT rate as it is set today. If the shop changes its rate, older payments read from then on split at the new rate. A job that runs every 15 minutes reads each payment long before that can happen.

## With the payment.completed webhook

The shop adds your address under **Updates for other software** and switches on **Payment noted**. Each message holds the payment in `data.object`, the same object as above. Your server checks the signature, stores the message and answers 200 within 10 seconds. A worker calls Billit afterwards.

```js title="billit-webhook.js"
// Node 22. verify() is the function from the Webhooks guide.
import { createServer } from "node:http";
import { verify } from "./verify.js";

const SECRET = process.env.WEEROM_WEBHOOK_SECRET;

createServer((req, res) => {
  const chunks = [];
  req.on("data", (chunk) => chunks.push(chunk));
  req.on("end", async () => {
    const raw = Buffer.concat(chunks);
    if (!verify(raw, req.headers["weerom-signature"], SECRET)) {
      res.writeHead(400).end();
      return;
    }
    const message = JSON.parse(raw.toString("utf8"));
    if (message.type === "payment.completed") {
      await queuePayment(message.id, message.data.object);
    }
    // Answer 200 to the test message and to events you do not use, too.
    res.writeHead(200).end();
  });
}).listen(3000);

// The worker, run from your own queue.
export async function invoicePayment(eventId, payment) {
  // The same message can arrive twice. Skip an event you handled.
  if (await seenEvent(eventId)) return;

  if (await hasInvoice(payment.id)) {
    // Staff corrected a payment that already has an invoice.
    await askAPerson(payment);
  } else {
    await createBillitInvoice(payment);
  }
  await markSeen(eventId);
}
```

`queuePayment`, `seenEvent`, `hasInvoice`, `markSeen` and `askAPerson` stand for your own storage. [Webhooks](https://developers.weerom.com/docs/webhooks#verify-the-signature) has `verify()` in JavaScript, PHP and Python.

## The polling job

1. A job runs every 15 minutes.
2. It asks for payments noted since the last one it handled: `GET /payments?paid_after=...&order=asc`.
3. It makes an invoice for each new payment.
4. It remembers the `paid_at` of the last payment it handled, for the next run.

Pick any interval that suits the shop. A run with no new payments costs one request, so every 15 minutes is 4 requests an hour, far under the 120 a minute a key may make.

The sketch below is JavaScript for Node 22. It keeps its state in a small JSON file. `createBillitInvoice(payment)` stands for your own code that calls Billit with the mapping above. Fill it in from [Billit's API documentation](https://docs.billit.be/docs/get-started). Billit signs requests with OAuth 2.0 and has a sandbox at `api.sandbox.billit.be` for tests, according to its pages on [authentication](https://docs.billit.be/docs/authentication) and [sandbox and production](https://docs.billit.be/docs/sandbox-vs-production-1), read on 2026-11-21.

```js title="sync-payments.js"
import { readFile, writeFile } from "node:fs/promises";

const BASE = "https://api.weerom.com/v1";
const STATE_FILE = "./weerom-state.json";

// The first run starts here. Pick the moment the shop wants invoices from.
const START = "2026-12-01T00:00:00+01:00";

async function loadState() {
  try {
    return JSON.parse(await readFile(STATE_FILE, "utf8"));
  } catch {
    return { lastPaidAt: START, handled: [] };
  }
}

async function saveState(state) {
  await writeFile(STATE_FILE, JSON.stringify(state, null, 2));
}

async function getPage(cursor, since) {
  const url = new URL(`${BASE}/payments`);
  url.searchParams.set("paid_after", since);
  url.searchParams.set("order", "asc");
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);

  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.WEEROM_KEY}` },
  });
  if (!response.ok) {
    const { error } = await response.json();
    throw new Error(`${response.status} ${error.code}: ${error.message} (${error.request_id})`);
  }
  return response.json();
}

export async function syncPayments() {
  const state = await loadState();
  const since = state.lastPaidAt;
  let cursor = null;

  do {
    const page = await getPage(cursor, since);

    for (const payment of page.data) {
      // paid_after includes its own moment, so the last payment of the
      // previous run comes back once. Skip what already has an invoice.
      if (state.handled.includes(payment.id)) continue;

      await createBillitInvoice(payment);

      // Keep only the ids at the newest moment. Older ones cannot come back.
      if (payment.paid_at !== state.lastPaidAt) state.handled = [];
      state.handled.push(payment.id);
      state.lastPaidAt = payment.paid_at;
      await saveState(state);
    }

    cursor = page.has_more ? page.next_cursor : null;
  } while (cursor);
}

await syncPayments();
```

Run it every 15 minutes with cron, a scheduled function or your platform's job runner:

```txt
*/15 * * * * WEEROM_KEY=wo_live_... node sync-payments.js
```

## Details that matter

- **The time zone.** Read `GET /shop` once and keep its `time_zone`. The webhook does not carry it.
- **Ascending order.** `order=asc` hands you the oldest payment first. The job can then save `lastPaidAt` after each invoice, and a run that stops halfway picks up where it stopped.
- **The edge of `paid_after`.** `paid_after` returns payments noted at or after that moment. The last payment of one run comes back at the start of the next. The `handled` list catches it.
- **A crash between Billit and the state file.** If the job stops after Billit made the invoice but before `saveState`, the next run tries that payment again. Look for an invoice with that `booking_code` in Billit before you make another, or accept that this rare case needs a person.
- **Errors.** In the polling job, a 401 or 403 means the key was removed or the shop left Premium. Stop and tell someone. A 429 or 500 can wait for the next run. See [Errors](https://developers.weerom.com/docs/errors).
- **One key for this job.** Make a read key named "Billit" and use it only here. See [Authentication](https://developers.weerom.com/docs/authentication).
- **A corrected payment comes back.** When staff change the method or an amount of a payment they noted, `paid_at` moves to the moment of the change, and the payment shows up again in a later run with the same `id`. The webhook sends a new `payment.completed` message for it, with a new event `id` and the same `data.object.id`. The `handled` list of the polling job keeps only the newest ids, so it does not catch this. Keep every invoiced `id` in your own records, or look for the `booking_code` in Billit, and send a payment that comes back to a person: it may need a credit note.
- **Filter by method.** `GET /payments?method=cash` lists the payments of one method, for a shop that invoices those apart.

## Limits

The API cannot write back to WeerOm that a payment has an invoice, so the job keeps that record itself, in `handled`. It cannot note a payment either: staff note it in the admin, and the job reads it afterwards. A corrected payment comes back with a new `paid_at` and nothing says what changed, so the job cannot tell a correction from a new payment without its own records. A payment staff remove disappears from the list without a trace and sends no webhook. WeerOm does not take the money, so the API knows nothing about refunds.
