Skip to main content
The billingVersion field on a plan controls how Paygentic handles subscriptions, invoices, and entitlements for that plan. There are two billing models: Legacy Billing (billingVersion: 0) and Standard Billing (billingVersion: 1). Understanding the difference helps you build the right integration and take advantage of Standard-only capabilities like features, grants, and metered entitlements.
All new plans default to Standard Billing (billingVersion: 1). Existing Legacy plans continue to work without changes.

Legacy Billing

Entitlements are pre-authorized wallet reservations denominated in currency. Supports the instant payment term for real-time wallet debits.Still supported for existing integrations.

Standard Billing

Entitlements are unit-denominated grants with rollover and overage. Subscription activation is gated by Invoice 0.Recommended for new integrations.

​
Which Version Should You Use?

Use Standard Billing (recommended) if:
  • You are starting a new integration
  • You need features or metered entitlements
  • You want unit-denominated grants with rollover and overage
  • You want per-invoice itemization and tax
Use Legacy Billing only if:
  • You are maintaining an existing Legacy Billing integration
  • You specifically need the instant payment term for real-time wallet debits on usage events

​
Setting billingVersion on a plan

Set billingVersion when creating a plan. Omitting the field defaults to 1 (Standard): 
{
  "name": "Pro Plan",
  "billingVersion": 1
}
See the Plans page for complete plan creation details.

​
Overview

Legacy Billing Each usage event triggers a transaction against the customer’s account. Entitlements are pre-authorized payment reservations: when a customer buys an entitlement, funds are reserved from their account in currency (for example, $10). Usage events decrement that balance via the instant payment term. Standard Billing Money only moves when invoices are paid. Entitlements are unit-denominated grants (for example, 1,000 API calls), tracked separately from the customer’s account balance. Metered features, rollover, and overage are only available in Standard Billing.

​
Comparison

CapabilityLegacy Billing (billingVersion: 0)Standard Billing (billingVersion: 1)
Default for new plansNoYes
Payment termsinstant, in_advance, in_arrearsin_advance, in_arrears only
Subscription activationUpfront payment sessionInvoice 0 — must be paid to activate (see below)
When money movesEach usage event triggers a transaction against the customer’s accountOnly when an invoice is paid
Entitlements modelCurrency-denominated wallet reservations (no rollover)Unit-denominated grants with rollover and overage (see below)
Standard-only capabilities—Features, metered entitlements, grant rollover and overage
Standard Billing plans cannot include prices with paymentTerm: instant. Attempting to create or update a Standard Billing plan with an instant price returns a 422 error. This is the most common constraint to watch for when adding prices to a Standard Billing plan.

​
Entitlements vs Grants

The term “entitlement” means something different depending on billing version. In Legacy Billing, an entitlement is a pre-authorized payment reservation. Funds are reserved from the customer’s account in currency at usage time via the instant payment term. You can express “$10 worth of API calls,” but not “1,000 API calls” — the unit is always currency. In Standard Billing, an entitlement is a feature access record provisioned when a customer subscribes. The underlying mechanism is a grant: a unit-denominated allocation of a specific feature (for example, 1,000 API calls, 50 GB storage). Paygentic tracks the unit balance independently from the customer’s account balance. Grants support:
  • Rollover — unused units carry forward into the next period, up to a configurable cap
  • Overage — when a customer exceeds their balance, you can allow continued access and track the debt (soft limit) or block access (hard limit)
  • Sub-period resets — grants can reset on a shorter cycle (for example, daily) within a monthly subscription
  • Currency denomination — grants can also be expressed in currency, replicating the Legacy Billing commitment concept but with rollover and overage available
Metered entitlements and grants require Standard Billing. They cannot be used on Legacy Billing plans. This is enforced by the API.
For rollover rules, entitlement template configuration, and worked examples, see Metered Entitlements.

​
Invoice 0

When you create a Standard Billing subscription, Paygentic creates Invoice 0 — a special invoice that collects all in-advance charges for the subscription (setup fees, first-period recurring fees). The subscription does not activate until Invoice 0 is paid. Zero-amount Invoice 0: If no in-advance fees apply (for example, a plan with only in_arrears prices, or a free trial), Invoice 0 totals zero and is paid automatically. The subscription activates immediately without requiring any customer action. Unpaid Invoice 0: If Invoice 0 expires before the customer completes payment, the subscription is cancelled. A new subscription must be created.
Your subscription creation response includes Invoice 0’s payment sessions. Direct the customer to complete payment using those sessions. To confirm activation, listen for the invoice.paid webhook event where sequenceNumber is 0.

Features and Entitlements

Create features and link them to plans. Requires Standard Billing.

Metered Entitlements

Grant lifecycle, rollover, overage, and balance checking. Requires Standard Billing.

Entitlements

Pre-authorized payment reservations for Legacy Billing.

Usage Events

Report consumption and trigger billing. Works with both versions.