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. The contract with one customer: who is billed, in which currency, for what. Its status is DRAFT / ACTIVE / PAUSED / CANCELLED; there is no trial or dunning status (a trial is a phase priced free, dunning shows in billing_state.dunning_stage: WARNED / GRACED / SUSPENDED). What was agreed lives in its revisions. 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. Organization setting fx_policy_invoice, set with PUT /v1/organization/settings - see Exchange rates.
Subscription concepts
Revision. One version of a subscription's deal: an ordered list of phases. Exactly one revision is live once the subscription has started, earlier ones are superseded, and at most one draft is open. Every change to what is billed is a new revision, opened with a cut or a copy and made live by publishing it. See Subscriptions → The deal.
Phase. A window of a revision with its own lines. It opens fixed on a date or after_previous, ends on a date, after a duration, on an event or never, and says what follows: next, open (the deal runs on) or stop (the subscription ends). See Subscriptions → Phases.
Line. One product billed in a phase: product_id, its origin (the plan or product version it came from) and its values: quantity, price, allowance, cadence, timing, track, version_change.
Value ladder. How a line value is resolved: stated on this phase, else carried from an earlier phase, else the catalog origin, else the subscription default. A value is stated, reset (back to the catalog, and stored) or absent (inherit).
Cut. Opening the next draft revision at an instant: phases before it are kept, the phase containing it is split, everything after is superseded. The way to change a live deal from a date on; the draft is then written whole with PUT /v1/subscriptions/{id}/revisions/draft.
Billing period. The span one invoice covers. Its length is the subscription's cadence (week, month or year times a count); where periods fall is its alignment (start, day_of_month with a day 1–28, or last_day). The period in force is current_period.
Proration. Settling a change that lands inside a billing period, instead of billing the whole period at the previous or the new amount.
Scheduled cancellation. A cancellation planned with when at or period_end, read back as scheduled_cancellation on the subscription (include=scheduled_cancellation) and withdrawn with DELETE /v1/subscriptions/{id}/scheduled-cancellation.
Commitments
Exit rules. The exit block of a phase: gate (none / warn / block), not_before (the phase before whose end the subscription cannot be cancelled), notice_duration and fee. A block gate with an unfinished not_before phase refuses a cancellation with 409 SUBSCRIPTION_EXIT_BLOCKED. There is no separate agreement object. See Commitments and exit rules.
Co-termination. Subscriptions sold on one contract held to one end: each one's not_before names the same phase of one subscription (with its subscription_id), so none can be cancelled before that phase ends. See Commitments and exit rules → Co-terminated deals.
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 PATCH /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 that clears the overdue invoices ends the dunning episode: billing_state.dunning_stage is cleared and subscription.recovered is emitted.
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. A Change authored with POST /v1/changes: one operation (for example catalog.publish_version or subscription.set_status) on one subject, now or at a wall-clock time in a zone. Its status is planned, running, applied, failed, cancelled or superseded; a planned one is cancelled with DELETE /v1/changes/{id}. See Scheduled changes.
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; each subscription reports its own as live.mrr (include=live); ARR is 12 × live.mrr. Workspace-level metrics and time series come from GET /v1/analytics/metrics and GET /v1/analytics/series. See Analytics.
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.