> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paygentic.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Billing Versions
> Understand the differences between Legacy and Standard billing models
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.
New plans are always created on Standard Billing (`billingVersion: 1`) — `billingVersion: 0` is rejected on plan creation. Existing Legacy plans continue to work without changes.
Entitlements are pre-authorized wallet reservations denominated in currency. Supports the
`instant` payment term for real-time wallet debits.
Still supported for existing integrations.
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
**Legacy Billing** is only available on plans created before this restriction — it can't be set on new plans, even for integrations that specifically need the `instant` payment term.
### Setting billingVersion on a plan
`billingVersion` can only be set at plan creation, and only `1` is accepted. Omitting the field also defaults to `1` (Standard); passing `0` returns a validation error:
```json theme={null}
{
"name": "Pro Plan",
"billingVersion": 1
}
```
See the [Plans](/platform/pricing/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
| Capability | Legacy Billing (`billingVersion: 0`) | Standard Billing (`billingVersion: 1`) |
| -------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Available on new plans | No — `billingVersion: 0` is rejected on creation | **Yes** (only option; also the default) |
| Payment terms | `instant`, `in_advance`, `in_arrears` | `in_advance`, `in_arrears` only |
| Subscription activation | Upfront payment session | Invoice 0 — must be paid to activate ([see below](#invoice-0)) |
| When money moves | Each usage event triggers a transaction against the customer's account | Only when an invoice is paid |
| Entitlements model | Currency-denominated wallet reservations (no rollover) | Unit-denominated grants with rollover and overage ([see below](#entitlements-vs-grants)) |
| 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](/platform/billing/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`.
## Related pages
Create features and link them to plans. Requires Standard Billing.
Grant lifecycle, rollover, overage, and balance checking. Requires Standard Billing.
Pre-authorized payment reservations for Legacy Billing.
Report consumption and trigger billing. Works with both versions.