Kontier Billing API

A customer represents a person or company that purchases your products and services. Customers are the foundation of your billing relationship - every subscription, invoice, and payment is tied to a customer record. Each customer has a billing profile including address, preferred currency, tax identifiers, and custom fields. Customers can be tagged for segmentation, merged when duplicates are discovered, and validated through identity verification providers. Key concepts:

• External ID - your internal identifier for this customer, used for idempotent upserts
• Billing model - controls how charges are calculated (prepaid, postpaid, or hybrid)
• Customer type - individual or company, affects tax treatment and invoice formatting
• Metadata - arbitrary key-value pairs for your own bookkeeping

A subscription is the deal between your business and one customer: what is billed, at which price, from when to when. Status: DRAFT → ACTIVE ⇄ PAUSED → CANCELLED. A trial is not a status; it is a phase whose price is free. Revisions, phases and lines. The deal is held in a revision. A revision is an ordered list of phases (each with an opening rule, a closing rule and what follows it), and each phase bills lines: one per product, pre-filled from a plan or product version (the line's origin). A line value — quantity, price, allowance, cadence, timing, track — is either stated on the phase, carried from an earlier phase, or taken from the catalogue. Lifecycle through the API:

1. POST /subscriptions creates the envelope (customer, name, currency) in DRAFT with an empty draft revision 1.
2. PUT /subscriptions/{id}/revisions/draft writes the phases and lines of revision 1.
3. POST /subscriptions/{id}/activate publishes revision 1 and starts the subscription.
4. To change a running deal, open the next revision (POST /subscriptions/{id}/revisions/cut or POST /subscriptions/{id}/revisions/draft), edit it, and publish it with POST /subscriptions/{id}/revisions/draft/publish.
5. POST /subscriptions/{id}/pause, /resume and /cancel (now, at a date, or at the end of the billing period); DELETE /subscriptions/{id}/scheduled-cancellation withdraws a planned cancellation.

To plan a change for later instead of making it now, use the Changes operations.

An invoice is a formal request for payment sent to a customer. Invoices are generated automatically at the end of each billing period, or manually for one-off charges, credits, and adjustments. The invoice lifecycle is: draft → finalized → sent → paid (or void / uncollectible). Draft invoices can be edited; finalized invoices are immutable and receive a sequential invoice number. Key concepts:

• Invoice type - subscription (recurring), one_off (manual), or credit_note (refund/adjustment)
• Line items - individual charges with product, quantity, amount, and tax breakdown
• Credit notes - partial or full reversals of a finalized invoice
• PDF export - generate a formatted PDF for download or email delivery
• XRechnung - EU-compliant electronic invoice format (XML) for B2G billing
• Buyer reference - PO number or reference that appears on the invoice for the customer's records

A plan is a reusable bundle of products and prices that a subscription line can take its values from. Versions. Edits land in the plan's working draft; they never change what subscribers are billed. A draft goes live as a new version through POST /changes with operation: catalog.publish_version — now or at a scheduled time. scheduled_versions lists versions waiting to publish, GET /plans/{id}/history lists the published ones. Subscribers. Each subscription line either follows its plan (moves to new versions, by its version_change strategy) or is pinned to the version it was sold on.

A wallet is a prepaid credit balance associated with a customer. Wallets allow customers to pre-fund their account, receive credits (promotional or otherwise), and have charges automatically deducted from their balance before falling back to a payment method. Each customer has a primary wallet created automatically, and can have additional wallets in different currencies. Key operations:

• Credit - add funds to the wallet (from a payment, promotion, or manual adjustment)
• Debit - remove funds (applied automatically during invoicing, or manually)
• Hold - reserve an amount for a pending charge (released or captured later)
• Transfer - move funds between wallets (e.g., currency conversion)
• Adjust - correct the balance without a formal credit/debit (e.g., migration adjustment)

Credit notes: drafts, issuing, application against invoices, cash refunds, and PDF/XRechnung artifacts.

A reservation places a hold on a customer's wallet, reserving funds for a unit of work that is later captured (settled) or released. This is the reserve → capture → release lifecycle - the authorize/capture pattern applied to wallet balance. Reservations are the primary money-gating surface for prepaid usage.

Quotes are offers a buyer signs. A quote names the subscriptions it acts on (POST /quotes/{id}/revisions): a new DRAFT subscription, or a new revision of an existing one, whose phases and lines are authored with the subscription revision operations. Sending the quote gives the buyer a signing link; signing publishes the bound revisions. Contract clauses and quote presets are managed here too.

One list of every money movement — provider payments and refunds, manual payments, credit notes and wallet movements. Payment attempts (dunning steps, deprecated) are listed only when requested by kind.

A product represents a billable item in your catalog - a feature, service, or resource that customers pay for. Products are the building blocks of plans and appear as line items on invoices. Products can be recurring (charged every billing period), usage-based (metered and charged based on consumption), or one-time (charged once at purchase). Key concepts:

• Product type - recurring, usage, one_time, or seat - determines how charges are calculated
• External ID - your internal SKU or product code for integration with other systems
• Cost tracking - named COGS entries via costs[] (per-product or org-scoped) for margin analysis
• Dependencies - requires_product_ids enforces that certain products must be purchased together

A price defines the monetary amount charged for a product within a plan. Prices support multiple currencies, billing periods, and pricing models - from simple flat fees to complex tiered and formula-based calculations. Pricing models:

• Flat - a fixed amount per billing period (e.g., $49/month)
• Per-unit - a fixed amount multiplied by quantity (e.g., $10/seat)
• Tiered - different rates at different volume thresholds (e.g., $0.10/unit for 0–1,000, $0.08/unit for 1,001–10,000)
• Volume - the tier that contains the total quantity determines the rate for all units
• Graduated - each tier's rate applies only to units within that tier's range
• Formula - a mathematical expression evaluated at billing time (see Price Formulas)

Key concepts:

• Effective date - prices can be scheduled to take effect in the future
• Country code - geo-specific pricing for different markets
• Currency - each price is denominated in a single currency; use multiple prices for multi-currency support

Price formulas let you define dynamic pricing using mathematical expressions that are evaluated at billing time. This is useful for pricing models that depend on runtime variables - usage volume, contract size, exchange rates, or custom metrics. Formulas support standard arithmetic operators, conditional logic, and named variables. Each variable has a type and optional default value. At billing time, the formula engine resolves all variables and computes the final price. Example: base_price * (1 - volume_discount) where volume_discount increases with usage.

Rate tables provide structured lookup pricing - a grid of rates indexed by one or more dimensions. Use rate tables for complex pricing that depends on multiple variables like geography, volume tier, customer segment, or contract term. Example: A shipping rate table with dimensions for weight range, origin country, and destination country.

Promotions allow you to offer discounts, credits, and special pricing to customers through coupon codes, automatic rules, or manual application. Key concepts:

• Code - the coupon code a customer enters (e.g., SAVE20)
• Effects - what the promotion does: percentage discount, fixed discount, free trial extension, or credit grant
• Conditions - eligibility rules: minimum spend, specific plans, customer segments, date ranges
• Budget - optional spending cap; the promotion deactivates when the budget is exhausted
• Stackable - whether this promotion can combine with other active promotions
• Simulation - preview the financial impact of a promotion before activating it

Product and org-scoped cost definitions consumed by pricing formulas.

Key sets: the org-global registries of pricing keys that rate tables and prices resolve against.

Saved customer selections defined by rules. An audience narrows who a promotion or a Change applies to; preview it, ask whether a customer is a member, and see what uses it.

Send usage events, read them back, and aggregate them over time. Each event records a quantity of one metric for one customer and subscription; the meters of the subscription's products turn the events into billed quantities on the next invoice. Use the aggregate to build usage dashboards, and GET /usage-events/billing to find the invoice that billed one event.

Usage meters: definitions, threshold breaches, and consuming products.

Bindings that attach meters to products and map them to pricing variables.

A payment gateway configuration connects Kontier to an external payment processor (Stripe, GoCardless, or other providers) for collecting payments from customers. Each organization can have multiple gateway configurations - for example, Stripe for card payments and GoCardless for SEPA direct debits. One gateway is marked as the default. Key concepts:

• Provider - the payment processor (stripe, gocardless, etc.)
• Mode - live or test - determines whether real charges are made
• Supported currencies - which currencies this gateway can process
• Supported methods - which payment methods this gateway handles (card, direct_debit, etc.)

A payment method is a stored instrument (credit card, bank account, direct debit mandate) that a customer uses to pay invoices. Payment methods are tokenized through the configured payment gateway - Kontier never stores raw card numbers or bank details. Each customer can have multiple payment methods. One is marked as is_default and is used automatically when invoices are finalized.

Tax rules define the tax rates applied to charges based on jurisdiction, product category, and customer location. Kontier evaluates tax rules at invoicing time and adds the appropriate tax line items to each invoice. Key concepts:

• Jurisdiction - country and optional region the rule applies to
• Tax type - vat, sales_tax, gst, hst, etc.
• Inclusive vs. exclusive - whether the tax is included in the listed price or added on top
• Compound tax - whether this tax is calculated on the pre-tax amount or on the amount including other taxes
• Apply order - controls the sequence when multiple tax rules apply

Manage your organization's tax profile and access EU VAT rates. The tax profile stores your legal entity details (VAT ID, tax regime, legal address) used on invoices and for reverse-charge determination. EU VAT rates are maintained automatically and include standard, reduced, super-reduced, and parking rates for all EU member states.

E-invoice artifacts (EN 16931 / XRechnung / Peppol): generation, validation findings, and document downloads.

Individual payments and payment reconciliation findings.

Hosted checkout links that let a buyer subscribe on their own; create, update and delete them.

A Change is an operation planned for an instant: publishing a catalog version, cancelling, pausing or resuming a subscription, transforming a subscription onto another plan or version, and more. GET /changes/operations lists the operations this deployment can schedule, with the when kinds each accepts (now, a wall-clock time, the end of the billing period, …) and the schema of its payload. Author with POST /changes, preview first with POST /changes/preview, move one with PATCH /changes/{id}, cancel one with DELETE /changes/{id}, and read what it did with GET /changes/{id}/outcomes. Publishing a plan, product, rate table, tax rule or price formula draft is always a Change: operation: catalog.publish_version.

How unpaid invoices are chased. The dunning policy — the organization's own, or one shared from the organization above — and per-plan overrides set the steps, timing and final action; dunning cases are the runs it produces. A subscription's current stage is also on its billing_state, and stage changes are delivered as webhook events.

Webhook secrets are the HMAC signing keys used to authenticate inbound webhook payloads. Each secret is scoped to an entity (e.g., a specific integration endpoint) and can be rotated without downtime by creating a new secret before deactivating the old one.

The URLs Kontier delivers webhook events to. Choose the event types per endpoint (GET /webhook-endpoints/event-catalog lists them), read delivery attempts and requeue one. The payload of every event type is documented under Webhooks in this reference.

Test a Slack notification webhook.

Approval requests raised by checkpoints on guarded operations (refunds, wallet adjustments, scheduled changes with gate: approval, …). A gated call answers 202 with an approval_request_id; read the request here, or wait for the approval.* webhook events whose request_id is that id. Deciding, cancelling and retrying a request is a person's act in the dashboard: an API key cannot decide.

Background jobs of your workspace (exports, imports, sends, …) and their runs. Read-only. Events such as jobs.dead_lettered carry a job_id you can look up here.

Organization and workspace settings — defaults, numbering, sign-in policy, approval checkpoints, mail house defaults and more — as typed keys on a ladder (workspace over organization over the organization above, over the default). GET /organization/settings/catalog lists every key with its type; GET /organization/settings/resolve answers the effective value and where it came from. Also: sharing a resource (such as a dunning policy) with the organizations below yours, and e-invoicing channels and their credentials.

Custom field definitions extend the data model of core entities (customers, subscriptions, plans, products) with your own fields. Define the field type, validation rules, and visibility, then set values on individual records. Supported field types: text, number, boolean, date, enum, entity_ref Key concepts:

• Entity types - which resources this field applies to (e.g., customer, subscription)
• Field group - logical grouping for UI display
• Validation - regex patterns, min/max values, required/optional
• Auditable - whether changes to this field are tracked in the audit log
• Deprecation - soft-disable a field before permanent removal

Customer verification tracks identity checks and compliance validations performed through external verification providers. Each verification has a status lifecycle: pending → verified / failed / expired. Use verifications for KYC/KYB compliance, age verification, or business entity validation.

Workspace currency allowlist: which currencies are enabled for billing and catalog use.

Foreign-exchange reference data: ECB snapshots, sync status, and rate overrides.

Org-defined labels and their assignment to customers, products, plans, subscriptions, invoices, and credit notes.

Accounting integrations and export artifacts (DATEV and other providers).

Layouts for invoices, quotes and other documents: create, copy, preview and set a template as your organization's default for a document type.

Settings of the hosted customer portal.

Documents attached to Kontier records: upload in two steps (start, then confirm), share with the customer or not, get a download link, delete.

Legal identifiers (VAT ids, register numbers and similar) of your organization and of your customers, per country: which kinds apply, validation dry-runs, VIES checks and register facts.

Mail Kontier sends on your behalf: the message log with delivery events, resend, the suppression list, blocked-mail retry, and recipients' marketing consent. Templates, mail kinds and sending providers are configured in the dashboard.

Connections to external systems (accounting, CRM, payment and other providers): connect, configure, pause and resume an integration, run its sync or actions, and read the external objects it created and its activity log.

Run a marketplace between your own customers: sellers, sales between a buyer and a seller, the money each sale moved, payouts owed to sellers and seller statements.

Real-time business metrics for your billing operation. Track monthly recurring revenue (MRR), customer churn, revenue breakdown by plan, and other key indicators.

• MRR - the normalized monthly revenue from all active subscriptions
• Churn - the rate at which customers cancel or downgrade
• Revenue - breakdown by product, plan, currency, and time period

Asynchronous report exports: queue one, then poll it until its file is ready.

Test clocks simulate the passage of time in a sandbox. Instead of waiting for renewals, phase ends or dunning steps, advance the clock and every time-dependent operation on the resources attached to it runs as if that time had passed. Sandbox only: a live workspace answers 403.

Simulate payment outcomes in a sandbox without a real payment processor — success, failure, pending and dispute — to test how your integration handles each. Combine with test clocks to run a whole billing cycle. Sandbox only: a live workspace answers 403.

Global search across billing entities.

Sign your customers into their billing portal from your own app or dashboard. There is no public sign-in page and no self-service link request: a customer reaches the portal only through you. Your app authenticates the customer, asks Kontier for a sign-in link with your API key, and sends the browser there at once. The flow

1. Authenticate the customer in your own app, as you do today.
2. Find their Kontier customer: GET /v1/customers?email=jane@example.com (or keep the customer id you stored when you created them).
3. Issue a link: POST /v1/customers/{id}/portal-links with a short ttl_seconds and, if you want, a return_path.
4. Redirect the browser to the returned url at once. The customer lands signed in, on return_path if you gave one.

Code
curl -X POST https://api.kontier.eu/v1/customers/$CUSTOMER_ID/portal-links \
  -H "Authorization: Bearer $KONTIER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"ttl_seconds": 120, "return_path": "/portal/invoices"}'

Code
{"data": {"url": "https://app.example.com/portal/enter/eyJhbGciOi...", "token": "eyJhbGciOi...", "expires_at": "2026-10-25T10:02:00Z"}}

Every POST needs an Idempotency-Key. Use a new one for each sign-in: a retry with the same key replays the first answer, which is the same single-use link. Security contract

• Authenticate your customer first. Whoever holds the URL is signed in as that customer.
• Redirect, do not send. Never email, log or store the link unless delivering it is what you mean to do.
• Links are single-use and short-lived. A link signs in once; opening it again lands on the portal's expired page, exactly as an expired link does. It lives for ttl_seconds (60 up to the deployment's link TTL, 30 minutes unless configured otherwise). Ask for 60 to 120 seconds when you redirect at once. Links issued before single-use links were introduced carry no single-use id and are refused: issue a new one.
• Scope your key. The endpoint needs the portal.links.issue permission (area Portal Sign-in in the key's custom access). Give the key that signs customers in that permission and only what else it needs. Keys that held customer.write before this permission existed were granted it once, so existing integrations keep working.

return_path must be one of the portal's own pages, such as /portal/invoices, /portal/invoices/{id}/pay, /portal/quote/{id} or /portal/subscriptions/{id}. Anything else (another host, a query, //) is refused with 400. Each link you issue is recorded in the audit log as customer.portal_access_issued: who issued it, for which customer, the landing page and the expiry. The link itself is never stored.

Your organization: its profile and company profile, invitations, recipient lists, delegated access, and restrictions on organizations below yours.

Workspaces of the active organization (for example a live and a sandbox workspace): list, create, read, update and delete.

The organization's roles: built-in roles and custom roles with their permission sets.

The permission catalog: every permission an API key or role can hold.

Create, rotate and revoke the API keys your integration authenticates with. See Authentication.

Single sign-on for your organization: linked identity providers and the email domains that route to them.

Organizations below yours — affiliates and organizations provisioned from a subscription: list and read them, grant capabilities, invite their admins and manage their members.

Resolve display names for many entity ids in one call.

The people in your organization: list them, change their roles, suspend or restore them, remove them. Invite new members under Organizations (POST /invitations).

The workspace's audit log: every recorded act with who did it, through which request, job or webhook, and what changed. Filter the list, read one operation with all its rows, and list the sources operations started from. One customer's customer-visible feed is GET /customers/{id}/audit-events.