Copy page

Get started

Kontorion Billing API

Kontorion is a billing API for subscription, usage-based, and hybrid commercial models. One surface handles catalog, customers, subscriptions, invoicing, payments, taxes, and FX - same data model for finance, engineering, and ops.

Capabilities

Area	What you can do
Catalog	Products, plans, versioned prices; volume / staircase / package pricing models with formula expressions
Customers	Accounts with custom fields, tax IDs, billing addresses, and per-customer price overrides
Subscriptions	TRIALING → ACTIVE → PAUSED → DUNNING → CANCELLED lifecycle, mid-cycle proration, scheduled changes
Usage	High-volume event ingest with idempotency, aggregator-driven billing, real-time queries
Invoices	Auto-generation on cycle close, manual one-offs, PDF + EN 16931 / XRechnung exports, replay-safe FX and tax pinning
Payments	Multi-gateway (Stripe, GoCardless), wallets with holds, manual payment recording on invoices
Money movement	Credit notes, dunning policies, refunds via gateway round-trip
Tax & FX	Versioned tax rules, reverse charge, VIES validation, per-policy FX rate selection
Promotions	Coupon-, condition-, and event-driven discounts with budgets and stacking rules
Webhooks	Signed at-least-once event delivery with idempotency keys

Base URL

Code
https://api.kontorion.eu/v1

Authentication

Pass your API key as a Bearer token on the Authorization header:

Code
Authorization: Bearer sk_live_…

API keys are scoped to one organization. All requests automatically resolve to that org's data - there's no separate organization parameter.

For sandbox keys, test clocks, and payment-outcome simulation, see Authentication.

First call

Code
curl https://api.kontorion.eu/v1/customers \
  -H "Authorization: Bearer sk_live_…"

Lists customers in your organization. A fresh org returns an empty data array.

A minimal end-to-end setup - customer, product, plan, price, subscription - takes five calls in sequence. See Customers, Products, Plans, Pricing models, and Subscriptions for the field-by-field bodies. IDs are UUIDs everywhere; the cust_… / plan_… placeholders in the docs are illustrative.

Response shape

Single resources are wrapped in a data envelope:

Code
{ "data": { "id": "cust_…", "name": "Acme GmbH" } }

Lists carry the same envelope plus a cursor-based pagination block:

Code
{
  "data": [ /* … */ ],
  "pagination": {
    "cursor": "WzQuMjEsIjIwMjYtMDQtMjdU…",
    "has_more": true,
    "total_count": 1247
  }
}

Pass cursor back as a query parameter to fetch the next page. total_count is opt-in per endpoint - absent when the count query is too expensive. See Pagination for filtering, sorting, and the counts group-by extension.

Errors

Error responses follow RFC 9457 Problem Details at Content-Type: application/problem+json:

Code
{
  "type":       "https://api.kontorion.eu/errors/CUSTOMER_NOT_FOUND",
  "title":      "Customer Not Found",
  "status":     404,
  "detail":     "Customer 7f5a-… could not be found.",
  "code":       "CUSTOMER_NOT_FOUND",
  "request_id": "01HKZ…"
}

Always switch on code (machine-readable, stable). See Errors for the full code catalog and idempotency.

Where to next

• New to Kontorion's commercial models - pick the closest pattern in Business models.
• Building an integration - start with Authentication, then Customers, Plans, and Subscriptions.
• Looking for a specific endpoint - the API reference is a searchable, interactive playground.