> ## 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.

# Plans

> Package your pricing tiers

Plans bundle prices together into offerings for your customers. Each plan represents a specific pricing tier or custom deal — a rate card that belongs to one product, contains prices for that product's metrics, defines billing frequency, and sets the currency.

When customers subscribe, they choose a plan. That plan determines what they pay for each metric they consume.

## Plan structure

Every plan requires a **product ID** to associate it with a product, a **name** for internal identification (e.g., "Enterprise Q4 2024"), and an **invoice display name** that customers see on their invoices.

You also set a **billing interval** (monthly or yearly), a **currency** that must match your account's currency, and the **prices** — a list of price objects for the product's metrics.

Finally, the **billing version** controls which billing model the plan uses. New plans are always created on `1` (Standard Billing) — omit the field or set it explicitly. See [Billing Version](#billing-version) below.

## Billing version

New plans are created on Standard Billing (`billingVersion: 1`) — the only value accepted for new plans. It's required for features, metered entitlements, Invoice 0 payment gating, and supports `in_advance` and `in_arrears` payment terms.

Legacy Billing (`billingVersion: 0`) exists only on plans created before this restriction. Passing `billingVersion: 0` on plan creation is rejected with a validation error; it can't be set on new plans, and it can't be changed after creation.

Omitting `billingVersion` defaults to Standard Billing.

```json theme={null}
{
  "name": "Pro Plan",
  "billingVersion": 1
}
```

See [Billing Versions](/platform/billing/billing-versions) for a full comparison of capabilities and constraints.

## Billing cadence

Plans use an ISO 8601 duration string for the `billingCadence` field:

| Value | Period    |
| ----- | --------- |
| `P1M` | Monthly   |
| `P3M` | Quarterly |
| `P1Y` | Yearly    |

**Monthly** billing is the SaaS standard. It gives customers predictable costs and makes upgrades and downgrades straightforward.

**Quarterly** billing reduces payment processing overhead compared to monthly while keeping the commitment period shorter than annual.

**Yearly** billing collects revenue upfront and reduces payment processing overhead. Annual plans are often paired with a discount to incentivize commitment.

Choose based on your business model — or offer multiple cadences and let customers decide.

<Note>
  **Parsing ISO 8601 durations in your code**

  The `billingCadence` field uses ISO 8601 duration format (e.g., `P1M` for monthly, `P3M` for quarterly, `P1Y` for yearly).

  **JavaScript / TypeScript** — use [Luxon](https://moment.github.io/luxon/):

  ```js theme={null}
  import { Duration } from 'luxon';
  const days = Duration.fromISO('P3M').as('days'); // ≈ 91.3
  ```

  **Python** — use [isodate](https://pypi.org/project/isodate/):

  ```python theme={null}
  import isodate

  # Parse ISO 8601 duration from API response
  duration = isodate.parse_duration('P3M')  # returns timedelta or Duration
  ```
</Note>

<Note>
  **`billingInterval` deprecation**

  The older `billingInterval` string field (`"monthly"`, `"quarterly"`, `"yearly"`) is deprecated. It is still returned in plan responses for backwards compatibility, but `billingCadence` is the source of truth. When creating or updating plans, prefer `billingCadence`. See the [migration guide](/changelog) for the full mapping.
</Note>

## Common strategies

### Tiered offerings

Create multiple plans for market segmentation. A **Hobbyist** plan offers low per-unit costs with usage caps and community support. A **Professional** plan improves the rates and limits with email support. An **Enterprise** plan adds volume discounts, unlimited usage options, and dedicated support. Each tier should offer clear value over the previous one.

### Customer-specific plans

For sales-led businesses, create custom plans per deal — "Acme Corp - Annual 2024", "TechCo - Q1 Pilot", "StartupX - Special Terms". Each plan reflects negotiated pricing and can be tailored to the customer's specific usage patterns.

### Freemium model

Combine free and paid tiers. A free plan sets zero cost for base metrics with hard usage limits, prompting upgrades when customers hit those limits. Paid plans introduce graduated pricing, additional features, and no hard caps.

## Examples

### LLM platform

A **Developer Plan** (monthly) charges $0.002/1K input tokens and $0.006/1K output tokens, rate-limited to 100 req/min. The **Scale Plan** (monthly) halves those token prices, raises the rate limit to 1,000 req/min, and adds fine-tuning at \$5/hour. An **Enterprise Plan** (annual) offers custom token pricing, unlimited rate limits, priority GPU access, and SLA guarantees.

### Data warehouse

An **On-Demand Plan** (monthly) charges $0.023/GB-month for storage and $0.05/query-second for compute with no minimums. A **Reserved Plan** (annual) drops storage to \$0.015/GB-month and offers pre-purchased compute blocks at a 40% discount, with a minimum commitment required.

## Best practices

**Clear naming.** Use descriptive names that indicate target customer and terms.

**Logical progression.** Each tier should offer clear value over the previous.

**Predictable costs.** Help customers estimate their bills easily.

**Room to grow.** Always have an upgrade path available.

## Next steps

* [Billing Versions](/platform/billing/billing-versions) — understand billing model capabilities and constraints
* [Define prices](/platform/pricing/prices) — configure pricing models and payment terms
* [Create subscriptions](/platform/core-concepts/customers-and-subscriptions) — connect customers to plans
* [Meter Events](/platform/metering/meter-events) — report usage for Standard Billing metered prices