Glossary
Quick reference for the terminology used across these guides. Each entry links to the detailed page where the concept is operationalized.
Core entities
Customer. A person or organization that owes money. Owns subscriptions, invoices, payment methods, wallets, and verifications. See Customers.
Subscription. A recurring billing agreement linking a customer to a plan. Carries its own status (DRAFT / ACTIVE / CANCELLED / EXPIRED); billing-mode (trial / paused / dunning) rides on the active phase's phase_kind, not on the status. While in a dunning phase it tracks a dunning_stage sub-state (WARNED / GRACED / SUSPENDED). See Subscriptions.
Plan. A reusable bundle of products + pricing. Versioned (PlanVersion) so live subscriptions keep replaying their pinned snapshot even after newer versions ship. See Plans.
Product. A billable item in your catalog. Its quantity_source (DECLARED | METERED) says where billed quantity comes from - declared on the subscription item (seats, flat charges) or supplied by the meter. Pricing model (VOLUME, STAIRCASE, PACKAGE) is set on the product, not the price. See Products.
Price. Tiered monetary configuration for a product within a plan or override. Versioned via PriceVersion. See Pricing models and Pricing (advanced).
Invoice. The financial artifact a customer pays. State machine draft → finalized → paid / overdue / void / error. Tax and FX state pinned at finalize. See Invoices.
Credit note. Audit-clean reversal of a finalized invoice. Two-step issue → apply flow with statuses draft / issued / partially_applied / applied / void. See Credit notes.
Money & currency
Money envelope. Decimal-string + currency pair: { "value": "100.00", "currency": "EUR" }. Per-currency decimal scale enforced (e.g. JPY = 0, EUR = 2). See Currencies.
Minor units. Integer cents - used as a wire shape on a small set of internal fields (e.g. refund amount). Most public surfaces use the Money envelope.
Exchange rate. Per-currency-pair rate row valid over a [from, to) window. Pinned three ways per finalize so policy changes don't strand replay. See Exchange rates.
FX policy. Which point-in-time the conversion uses: invoice_issue (default), period_start or daily_snapshot. Org-level setting - see Exchange rates.
Subscription concepts
Billing period. How often invoices generate (MONTHLY, QUARTERLY, ANNUAL, WEEKLY, etc.).
Billing anchor. The day of the month (or week) that subsequent cycles align to. Calendar-accurate - month-end anchors snap to the last day of shorter months.
Phase. A scheduled segment of a subscription's lifetime. Five phase kinds - setup, trial, standard, paused, dunning. See Subscriptions → Phases.
Proration. Mid-cycle math when something changes - adds PRORATION_CREDIT / PRORATION_CHARGE lines to the next invoice.
Add-on. A subscription item attached outside the base plan, billed alongside regular charges.
Plan transition. Move a subscription from one plan version to another. Either immediate (with prorations) or scheduled at the next renewal - see Subscriptions → Plan transitions.
Agreements and terms
Agreement. One negotiated deal on one subscription: the term that was agreed, the negotiated rates that hold for it, what happens when it runs out, and how an early exit is treated. Created by signing a quote that carries an agreed term. pending and active are live; superseded, ended, terminated_early and cancelled are terminal, and at most one agreement is live over any instant. See Agreements.
Term. The clock on an agreement. term_unit (week / month / year) times term_count, counted from the day the subscription starts; ends_at is derived from the pair and never set on its own. Not the same thing as how long the subscription runs - a subscription that renews monthly can carry a three-year term. See Agreements → The term.
Action at term end. What happens on the term's last day: RENEW, RENEW_ONCE, CONTINUE_WITHOUT_TERM, SWITCH_PLAN, CANCEL or RENEGOTIATE. Total by design, so something always happens and the agreement says what. A quote-signed agreement records CONTINUE_WITHOUT_TERM, which lets the rates lapse and leaves the subscription running at catalog prices. See Agreements.
Ramp. Agreed changes to one line's rate during the term, each step an offset from the deal's start rather than a date. A ramp is different prices at different times; a tier ladder is different prices at different volumes; a line may carry both. Authored as negotiated_ramp on a quote line, at most 50 steps. See Quotes → Ramped rates.
Negotiated rate. The rate a line was agreed at, as a decimal string in major units, which replaces the catalog tier walk for the life of the deal. It carries its own window, never longer than the agreement that governs it, and subscription.negotiated_price_expired announces the day it lapses.
Early-termination gate. What an agreement does when a governed operation is attempted inside the term. NONE allows it silently, WARN allows it and records the attempt, BLOCK refuses with 409 until an override_reason arrives. Defaults to WARN, and governs cancellation unless the agreement says otherwise. See Agreements → Leaving before the end.
Override reason. The free text that gets a governed operation past a BLOCK gate, sent on cancel, on an item quantity update and on an item removal. Required rather than optional: a gate with no auditable way through is one people work around by editing rows, and then nobody can tell that it happened. Recorded against the agreement with the principal who sent it.
Early-termination fee. What an agreement charges for leaving inside its term. Quoted inside the refusal itself, with its currency and a sentence explaining how it was reached, because "you may not do this" and "you may not do this without paying 12,000" are different answers. Billed after the cancellation succeeds, never before.
Notice period. A delay, not a veto. A cancellation asked for under a notice period is accepted and booked as a scheduled change for the day the notice runs out, clamped to the term's end. It applies to cancellation only, never to a quantity change.
Co-termination group. Agreements that end on the same day because they are one contract. Members cannot drift apart, renewals stay grouped, and a refusal reports cotermination_group_size so nobody cancels one of five believing the other four follow. They do not.
Commitment. Reserved, and not what a term is. Across this industry the word means a minimum spend, and Kontier keeps it for that: a future money object with its own drawdown ledger. The time lock-in this platform ships today is a term, on an agreement. If you are looking for "how long is this customer locked in", read Agreements.
Pricing models
Volume. The tier containing the total quantity sets one rate that applies to every unit. Total = quantity × unit_amount + flat_amount for the matching tier.
Staircase (graduated). Each tier's rate applies only to units within its range. Customers pay lower rates on early units even as total reaches higher tiers.
Package. Charges by bundles. total = ceil(quantity / package_size) × package_price for the matching tier.
Rate expression. Optional per-tier formula evaluated at billing time (cost * 1.15 + 200). Overrides the static unit_amount when present. See Pricing models → Rate expression.
Price formula. A reusable named expression with typed variables and defaults - referenced by name from rate_expression.
Customer price override. Per-customer pricing that wins over plan + catalog prices via the resolver cascade.
Keyed price. A price keyed by price_key so a single product covers multiple SKUs (e.g. one usage product with price_keys for eu-west, us-east). See Pricing (advanced) → Keyed prices.
Usage & metering
Usage event. A raw data point recording one unit of consumption. Idempotency-keyed at the event level. See Usage.
Aggregator. Rule that turns usage events into a billable quantity. Eight functions: SUM, COUNT, MAX, MIN, AVG, UNIQUE_COUNT, LAST, P95. The time slice is set by a meter window (kind = CALENDAR_HOURLY / CALENDAR_DAILY / CALENDAR_PERIOD / SLIDING / TUMBLING), defaulting to CALENDAR_PERIOD (the whole billing period).
Allowance. Included quantity inside a plan tier (e.g. "10k API calls included before metered pricing kicks in"). May roll over per plan rules.
Reserve outcome. Usage credit/debit pending capture into billing. Status walks PENDING → PROCESSING → CAPTURED / FAILED.
Promotions
Promotion. Discount, free period, or wallet-credit campaign. State machine plus per-redemption state. See Promotions.
Condition. A rule that gates redemption (7 types: minimum_spend, subscription_plan, external_verification, product_combination, quantity_threshold, first_purchase, usage_threshold).
Effect. What happens when a promotion redeems (7 types, e.g. percentage_discount, free_periods, wallet_credit). Effects apply in a canonical order so combined promotions are deterministic.
Phase. Promotion lifecycle state - draft / scheduled / active / archived.
Payments
Payment gateway. Configured integration with an external processor - stripe, gocardless, mollie, adyen. See Payments.
Payment method. Customer-owned reference to a tokenized instrument at a provider. Seven types: CREDIT_CARD, BANK_ACCOUNT, SEPA_DIRECT_DEBIT, SEPA_DIRECT_DEBIT_B2B, ACH_BUSINESS, PAYPAL, EXTERNAL.
Provider resolver. Cascade that picks which gateway charges an invoice - customer-preferred → org default (is_default=true) → first enabled.
Payment intent / attempt. PaymentIntent is the persisted payment request; PaymentAttempt is one row per try (1, 2, 3…) with normalized error_type on failure.
Manual payment. Out-of-gateway payment recorded against an invoice with a source enum (BANK_TRANSFER, CASH, CHECK, WIRE, WRITE_OFF, EXTERNAL_PROCESSOR). See Invoices → Record a manual payment.
Wallets
Wallet. Per-customer balance in a single currency. Split between cash_balance (real money) and promotional_balance (campaign credit, may expire). One primary per customer; secondaries for additional currencies. See Wallets.
Mode. PREPAID or POSTPAID. Lives on the customer (denormalised onto wallets); flipped via PUT /v1/customers/{id}/mode.
Hold. Reservation against wallet balance pending capture. Lifecycle PENDING → CAPTURED / VOIDED / EXPIRED.
Auto top-up. Charges the customer's default payment method when cash_balance falls below low_balance_threshold and credits the wallet by auto_topup_amount.
Dunning
Dunning policy. Ordered sequence of escalation steps run against overdue invoices. One default per org plus optional per-plan overrides. See Dunning.
Step. Individual escalation action - send_email, grace, suspend, cancel. Triggered after days_after_due past the invoice's due date.
Recovery. A payment posting against an overdue invoice exits the dunning phase and returns the subscription to its standard phase (regardless of which dunning_stage it had reached), clearing last_dunning_step_index.
Tax
Determination flow. First-match decision matrix on (seller, buyer, product tax category, date) that resolves the right rate, EN 16931 category code, and exemption text. See Taxes → Determination flow.
Tax rule. Rate row keyed on (country, region, tax_type) valid over [valid_from, valid_to). Versioned and pinned per invoice line.
Product tax category. DEFAULT, REDUCED, ZERO, or EXEMPT set on the product - tells the engine which destination-country rate to apply.
EN 16931 tax category code. Output code stamped on each invoice line - S (standard), Z (zero), E (exempt), AE (reverse charge), K (intra-community supply), G (export), O (out of scope).
Inclusive vs exclusive. Inclusive prices are gross (tax baked in); exclusive prices add tax on top.
Reverse charge. Tax liability shifts to the buyer (intra-EU B2B and non-EU → EU business). Line emits tax_rate: 0, code AE, requires VIES-validated eu_vat.
KLEINUNTERNEHMER. German §19 UStG small-business regime - 0% tax with the §19 notice rendered on the invoice.
OSS (One-Stop Shop). EU VAT simplification - destination-country VAT for intra-EU B2C, reported through one country.
XRechnung. German EN 16931 / Peppol BIS XML format for B2G invoicing.
VIES. EU's VAT-ID validation service. An eu_vat verification that's verified is the precondition for B2B reverse-charge treatment.
Verifications
Verification. Customer check (KYC, VAT validation, payment-instrument confirmation) with a typed status pending / verified / expired / failed. See Verifications.
Invoice anatomy
Line. A typed row on an invoice. Nine line types: RECURRING, USAGE, PRORATION_CREDIT, PRORATION_CHARGE, ADD_ON, EXPENSE_PASSTHROUGH, MILESTONE, ADJUSTMENT, CREDIT.
Atom (InvoiceLineAtom). Per-segment audit rows beneath a line. Cover (price_key × time-segment) combinations and the per-tier walk for VOLUME / STAIRCASE / PACKAGE pricing. Returned with ?depth=full.
Pinning. Each line stamps price_version_id, tax_rule_id, segment_exchange_rate_id, and fx_policy_applied so a regenerated invoice replays bit-exact even after the live versions move.
Scheduled changes
Scheduled change. Typed, future-dated mutation queued against an entity (price, plan, promotion, tax rule, subscription). See Scheduled changes.
Stale. A scheduled change whose underlying entity was modified after scheduling. Refuses to release until reconfirm'd (or cancelled + re-scheduled).
Release strategy. AUTOMATIC (default) or MANUAL.
Webhooks
Endpoint. Registered URL that receives signed POSTs for the event types it subscribes to. See Webhooks.
Signing key / whsec_… secret. HMAC-SHA256 key whose signature lands in X-Webhook-Signature: sha256=<hex> of the raw body. Plaintext returned only at create / rotate time.
Idempotency key. Per-originating-event UUID stable across broker resends and dispatcher retries. The field your endpoint deduplicates on - different from id, which is per-delivery.
Replay. Operator re-POST of an existing delivery via POST /v1/webhook-endpoints/{id}/deliveries/{delivery_id}/replay.
API contract
RFC 9457 Problem Details. Error response shape: application/problem+json with type, title, status, detail, code, request_id, plus extension members. Always switch on code. See Errors.
Cursor pagination. Keyset pagination - limit, cursor, has_more, total_count. Cursors are opaque and endpoint-specific. See Pagination.
Idempotency key (request-level). Idempotency-Key header that makes a write retry-safe. Distinct from the per-event idempotency key in webhooks.
Custom field. Typed extension on a core entity - 9 data types, attaches to one or more of 4 entity types (CUSTOMER, PRODUCT, PLAN, SUBSCRIPTION), filterable via ?custom_fields.<key>__<op>=.... See Custom fields.
Analytics
MRR (Monthly Recurring Revenue). Normalized monthly revenue from active recurring subscriptions. Returned by /v1/analytics/mrr with current/previous/change_rate + a 12-to-36-month time series. See Analytics.
Churn rate. churned / (active + churned) for the period. Returned by /v1/analytics/churn.
Testing
Sandbox. Org running in mode: sandbox - separate from production data, with a test clock and payment simulations.
Test clock. Frozen-time clock advanceable in a sandbox to simulate billing cycles instantly.
Payment simulation. Pinned outcome (success, decline, insufficient_funds, expired_card, fraud, processing_error, network_error) for a sandbox payment method - exercises the dunning + retry paths without hitting a live gateway. See Payments → Test-mode simulations.