> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paynext.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Plans
> Create and manage billing plans—define pricing, billing intervals, trial periods, and localized currencies.
Plans define what you charge customers. Create and manage plans entirely from **Dashboard → Plans**—no code changes required. Pass only the `plan.id` to checkout, and PayNext handles pricing, billing intervals, and localization automatically. Changes apply immediately when you save.
## How Plans Work
Define your pricing once in the Dashboard. At checkout, the correct price displays automatically based on the customer's country. If the plan includes a trial, the customer sees the trial terms before subscribing.
Your code only needs the `plan.id` — PayNext handles the rest.
Plan updates only affect new customers. Existing subscribers remain on their original plan terms—price changes, billing interval changes, and trial modifications do not apply retroactively.
## Plan Types
### Recurring Plans
For subscriptions and memberships. Charges on a schedule (daily, monthly, yearly, or custom interval).
**Features:**
* Billing frequency configuration
* Localized pricing by country
* Optional trial periods
#### Trial Periods
Offer free or reduced-price trials before the full subscription begins:
| Field | Description |
| ------------------------ | ---------------------------------------------------------- |
| **Trial Interval** | Unit of time: `days`, `months`, or `years` |
| **Trial Interval Count** | Number of units (e.g., `7` for 7 days, `1` for 1 month) |
| **Trial Price** | Amount to charge during trial (set to `0` for free trials) |
Trial pricing supports country-based overrides using the same logic as regular pricing.
### One-off Plans
For single purchases and setup fees. Single charge with no renewal.
**One-off plan features:**
* Static pricing
* Localized pricing by country
* Optional custom price per payment (see [Custom Pricing](#custom-pricing))
* No interval or trial configuration
## Create a Plan
Go to **Dashboard → Plans** and click **Create plan**
Select **Recurring** for subscriptions or **One-off** for single charges.
Assign an internal name (e.g., "Pro Monthly", "Enterprise Annual"). This name appears in the Dashboard and webhooks.
For recurring plans, set how often to charge: Every `[number]` `[Days | Months | Years]`.
If a customer starts on January 30 and the next month lacks that date, billing occurs on the last valid date (Feb 28/29).
Define default pricing and optional country-specific overrides. See [Localized Pricing](#localized-pricing) below.
Add a trial period if needed. See [Trial Periods](#trial-periods) above.
Click **Save** to create the plan. Use the generated `plan.id` in your integration.
## Localized Pricing
Charge different prices based on customer country. When you create a client session, pass the customer's country—PayNext automatically selects the correct price at checkout.
### How It Works
1. **Default price** — The first price you create applies to all countries
2. **Add country-specific prices** — Select a country from the dropdown and set a custom price
3. **Automatic exclusion** — Countries with specific prices are automatically removed from the default
4. **One price per country** — Each country can only have one price rule
### Example
You create a plan with these prices:
| Price | Countries |
| --------- | ----------------------- |
| €100 EUR | All countries (default) |
| \$120 USD | United States |
| £90 GBP | United Kingdom |
| €85 EUR | Spain |
**At checkout:**
* Customer from **Germany** → €100 EUR (default)
* Customer from **United States** → \$120 USD (country-specific)
* Customer from **Spain** → €85 EUR (country-specific)
When you add a price for United States, US customers no longer see the default €100—they only see \$120 USD.
## Custom Pricing
Override a plan's configured price for a single payment by passing a `price` object. Every other setting—name, tax behavior, enabled payment methods—is still inherited from the plan; only the amount and currency change. Use this for variable-amount one-off charges (donations, top-ups, quotes) without creating a new plan for each price.
Custom pricing is supported for **one-off plans only**. Passing `price` with a recurring plan returns a `400` error.
Provide both `amount` (in [minor units](/guides/payments/currencies)) and `currency` (ISO 4217). A custom price takes precedence over the default **and** any localized country-specific price—the exact amount and currency you send are charged:
```json theme={"system"}
{
"customer": {
"email": "customer@example.com",
"address": {
"country": "US"
}
},
"plan": {
"id": "plan_7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
"price": {
"amount": 4999,
"currency": "USD"
}
}
}
```
Set the price when creating a client session (SDK checkout) or on the [`POST /payments`](/guides/use-cases/charge-returning-customers#api-only-charges) request (API-only). Because the price is sent from your server, the checkout SDK running in the browser cannot change it.
## Create Client Session with Plan
Pass `plan.id` and `customer.address.country` when creating a client session:
```json theme={"system"}
{
"customer": {
"email": "customer@example.com",
"address": {
"country": "US"
}
},
"plan": {
"id": "plan_7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d"
}
}
```
PayNext uses `customer.address.country` to resolve localized pricing.
Amounts use [minor units](/guides/payments/currencies) based on currency. For example, \$10.00 USD = `1000`, ¥1000 JPY = `1000` (JPY has no decimal places).