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 state machine (TRIALING / ACTIVE / PAUSED / DUNNING / CANCELLED) plus a dunning_stage sub-state (WARNED / GRACED / SUSPENDED) while in DUNNING, and its own billing cycle. 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 - FIXED_CHARGE, SEAT, or USAGE typed. 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 → pending_approval / 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, per_segment, or daily_snapshot. Org-level setting - see Exchange rates → FX policy.
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. Six phase types - TRIAL, INTRO, STANDARD, RAMP, OVERLAY, PROMOTION. 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.
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. Three functions: SUM, COUNT, MAX. Three windows: HOURLY, DAILY, 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. Queued usage credit/debit pending capture into billing. Three terminal statuses: queued → 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 (8 types, e.g. code_required, external_verification, customer_tag).
Effect. What happens when a promotion redeems (7 types, e.g. percent_discount, free_periods, wallet_credit). Effects apply in a canonical order so combined promotions are deterministic.
Phase. Promotion state segment - pending / upcoming / active / wound_down / 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. Five types: CREDIT_CARD, BANK_ACCOUNT, SEPA_DIRECT_DEBIT, 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 transitions the subscription back to ACTIVE (from DUNNING regardless of which dunning_stage it had reached) and clears 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 (Kleinunternehmer), 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. Ten line types: PLAN_BASE, SEAT, 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), MANUAL, or CANARY.
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 8 entity types, 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.