BillKitBillKit for developers
BillKit is a subscription billing API for European businesses. It runs plans, checkout, invoices, VAT, dunning and the customer portal on top of your own Mollie account.
What BillKit is, and what it sits on
BillKit does not process payments. Your tenant account connects a Mollie account, and BillKit drives it: it creates the payments, stores the resulting mandates, schedules renewals, closes periods, computes VAT, produces invoices and PDFs, retries failures and emits webhooks. Money moves through Mollie and settles into your Mollie balance.
That split explains most of the design. Card and SEPA details never reach BillKit. Anything Mollie decides (whether a charge needs Strong Customer Authentication, whether a SEPA debit eventually bounces) is reported to BillKit asynchronously, which is why almost every outcome you care about arrives as a webhook rather than in a response body.
How the API is shaped
REST over HTTPS, JSON in and JSON out, including errors. Amounts are integers in the smallest
unit of the currency (amount_cents). Timestamps are Unix seconds. Object ids carry a type
prefix, so sub_... is always a subscription.
| Base URL | https://api.billkit.eu |
| Auth | Bearer secret key: bk_live_… or bk_test_… |
| Request body | application/json. Unknown fields are rejected with 422. |
| Success status | 200 on almost every route, including creates |
| Lists | Cursor paginated: limit (default 10, max 100) and starting_after |
| Idempotency | Idempotency-Key header on any write |
There is no API version header. Live and test mode are selected by which key you send, not by a parameter.
curl https://api.billkit.eu/v1/ping \
-H "Authorization: Bearer $BILLKIT_API_KEY"{
"tenant_id": "7b0f1e2c-9a41-4d6e-8f30-1c5a2b7d4e88",
"mode": "test",
"object": "ping"
}Id prefixes
| Prefix | Object |
|---|---|
| cus_ | Customer |
| prod_ | Product |
| price_ | Price |
| cs_ | Checkout session |
| sub_ | Subscription |
| pay_ | Payment |
| inv_ | Invoice |
| re_ | Refund |
| cn_ | Credit note |
| coup_ | Coupon |
| tr_ | Tax rate |
| ur_ | Usage record |
| evt_ | Event |
| we_ | Webhook endpoint |
| dp_ | Dispute |
| tc_ | Test clock |
| osp_ | One-off payment |
The one thing that surprises people
You cannot POST /v1/subscriptions. A subscription is a side effect of a paid checkout: you
create a checkout session, the customer pays, Mollie tells BillKit the payment settled, and
BillKit creates the subscription and emits subscription.created. The reason is the mandate.
A recurring charge needs an authorised mandate, and only a real first payment through Mollie
produces one, so there is no honest way to hand you a subscription before that payment lands.
Everything starts in test mode. Test-mode objects are stored separately, carry
livemode: false, and are invisible to a live key. See Test mode.