Core concepts

Orvlin separates what your product does (events) from what you charge for it (prices and plans). That separation lets you change pricing without changing your instrumentation.

​

Customers

A customer is the party you bill. Each customer has an ID (yours or Orvlin’s), a name, an optional billing email, a currency, and free-form metadata. Every other object refers to a customer by ID. Set id to your own identifier when you create a customer. Then you never have to store a mapping between the two systems.

​

Events

An event records something a customer did: an API call, a generated image, a row written. Each event has:

• customerId: who did it.
• eventName: what happened, such as api_call.
• timestamp: when it happened. Defaults to the time of ingestion.
• properties: details a metric can aggregate, such as latencyMs or tokens.
• idempotencyKey: optional. Events with the same key are counted once.

Events are the only input to metering. See Usage metering.

​

Metrics

A metric turns events into a number per billing period. The aggregation types are: Metrics can filter events and group them by a property.

​

Prices

A price charges for a metric (or for a flat fee, when it has no metric). Each price has:

• a config with a pricing model (unit, tiered, bulk, package, percentage, or license). See Pricing models.
• a cadence: monthly, quarterly, annual, one_time, or usage_based.
• a timing: in_advance (charged at the start of the period) or in_arrears (charged at the end).

​

Plans

A plan is a named bundle of prices. Customers subscribe to plans, not to individual prices. Editing a plan creates a new version, so existing subscriptions keep the terms they signed up for until you migrate them.

​

Subscriptions

A subscription connects a customer to a plan from a start date. Its status is one of active, trialing, past_due, paused, or canceled. You can cancel a subscription immediately or at the end of the period, amend it, schedule an amendment, or migrate it to a newer plan version.

​

Invoices

Orvlin creates invoices for each billing period, for prepaid credit purchases, and for manual charges. An invoice moves through these statuses:

​

Credits and wallets

Credits are a prepaid balance a customer spends as they use your product. Each credit type (for example ai_images) has its own wallet per customer. Usage can draw down a wallet automatically, and a wallet can top itself up when it falls below a threshold. See Prepaid credits.

​

Entitlements

An entitlement answers “may this customer use this feature right now, and how much is left?” It is derived from the customer’s subscription, plan, credits, and any grants you have added. See Entitlements.

​

Webhooks

Webhooks deliver events such as invoice.paid and subscription.created to an HTTPS endpoint you own, with a signature you can verify. See Webhooks.

​

Next steps