Plans & Pricing

Anatomy of a Plan

Plans define what you’re selling and how much it costs. Each plan has:

Name & Description - What appears to customers
Interval - Billing frequency (monthly, yearly, etc.)
Prices - Amount in one or more currencies
Features - What’s included (for display)

Create a Plan

curl -X POST https://api.recurso.dev/v1/plans \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro Plan",
    "code": "pro-monthly-inr",
    "interval_unit": "month",
    "interval_count": 1,
    "amount": 499900,
    "currency": "INR",
    "hsn_code": "998314"
  }'

const plan = await recurso.plans.create({
  name: 'Pro Plan',
  code: 'pro-monthly-inr',
  interval_unit: 'month',
  interval_count: 1,
  amount: 499900,        // minor units: ₹4,999.00
  currency: 'INR',
  hsn_code: '998314',    // optional; falls back to the tenant SAC
});

from recurso.api.plans import create_plan
from recurso.models import CreatePlanRequest, CreatePlanRequestIntervalUnit

plan = create_plan.sync(
    client=client,
    body=CreatePlanRequest(
        name="Pro Plan",
        code="pro-monthly-inr",
        interval_unit=CreatePlanRequestIntervalUnit.MONTH,
        interval_count=1,
        amount=499900,  # minor units: ₹4,999.00
        currency="INR",
        hsn_code="998314",  # optional; falls back to the tenant SAC
    ),
)

plan, _ := client.Plans.Create(ctx, &recurso.PlanCreateParams{
  Name:         "Pro Plan",
  Code:         "pro-monthly-inr",
  IntervalUnit: "month",
  IntervalCount: 1,
  Amount:       499900, // minor units: ₹4,999.00
  Currency:     "INR",
  HSNCode:      "998314", // optional; falls back to the tenant SAC
})

string

required

Unique per tenant (e.g. pro-monthly-inr). Encode the currency in the code when you sell the same plan in several currencies.

integer

required

Minor units of currency — 499900 is ₹4,999.00.

string

Optional HSN/SAC for GST — each invoice line for this plan is taxed at this code’s rate; empty falls back to the tenant SAC.

Pricing Models

A plan always carries a flat recurring price (amount + currency). Everything else — seats, tiers, metered usage — composes on top of it.

Flat rate
Per-seat
Tiered / metered
Hybrid

One fixed price per period. This is the plan itself:

curl -X POST https://api.recurso.dev/v1/plans \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Starter",
    "code": "starter-monthly",
    "interval_unit": "month",
    "interval_count": 1,
    "amount": 99900,
    "currency": "INR"
  }'

amount is in minor units — 99900 is ₹999.00.

Two ways to bill seats:Add-ons — attach a per-seat plan to the subscription with a quantity. The add-on bills as its own line (price × quantity) from the next recurring invoice:

curl -X POST https://api.recurso.dev/v1/subscriptions/{sub_id}/addons \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "plan_id": "plan_seat", "quantity": 10 }'

Seat metering — define a billable metric with max(seats) aggregation and report seat counts as usage events. The period bills the high-water mark; no proration bookkeeping needed. See usage-based billing.

Usage pricing lives in plan charges, not on the plan price. Attach charges that reference billable metrics, one of seven charge models:

curl -X PUT https://api.recurso.dev/v1/plans/{plan_id}/charges \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{
    "metric_code": "api_calls",
    "charge_model": "graduated",
    "amounts": { "INR": { "tiers": [
      { "up_to": 100000, "unit_amount": "0" },
      { "up_to": 1000000, "unit_amount": "0.05" },
      { "up_to": null, "unit_amount": "0.0035" }
    ] } }
  }]'

The PUT is a full replacement — charges absent from the request are removed. Models: per_unit, graduated, volume, package — compared side by side here.

A plan holding both a flat price and charges is hybrid: the flat fee bills in advance (as always), usage bills in arrears on the same renewal invoice at period close — each as its own tax-resolved line.

Pro Plan (advance)                 ₹4,999.00
API calls — 45,000 × usage         ₹1,750.00
IGST (18%)                         ₹1,214.82
─────────────────────────────────────────────
Total                              ₹7,963.82

Plan Intervals

Interval	Value	Example
Daily	`day`	Metered services
Weekly	`week`	Short-term access
Monthly	`month`	Most common
Yearly	`year`	Discounted annual

For custom intervals, use interval_count:

{
  interval_unit: 'month',
  interval_count: 3,  // quarterly billing
}

Trials

Trials are set per subscription, not on the plan — pass trial_days when creating the subscription and it starts in trialing, converting to active (and generating its first invoice) when the trial ends:

curl -X POST https://api.recurso.dev/v1/subscriptions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "customer_id": "cust_abc", "plan_id": "plan_pro", "trial_days": 14 }'

Trial-ending reminder emails go out automatically before expiry — see Subscriptions → Free Trials.

List Plans

Retrieve plans with search and pagination:

curl -G https://api.recurso.dev/v1/plans \
  -H "Authorization: Bearer $API_KEY" \
  -d search=pro \
  -d limit=10 \
  -d offset=0

const plans = await recurso.plans.list({ search: 'pro', limit: 10 });

from recurso.api.plans import list_plans

result = list_plans.sync(client=client, q="pro", limit=10)
plans = result.data

plans, _ := client.Plans.List(ctx, &recurso.PlanListParams{
  Q:     "pro",
  Limit: 10,
})

Filter Parameters

Parameter	Type	Description
`search`	`string`	Match against plan name and code
`limit`	`integer`	Results per page (default 20, max 100)
`offset`	`integer`	Results to skip for pagination

Multi-Currency Pricing

A plan’s flat price is one currency — sell the same tier in several currencies with per-currency plan codes, and let the smart router pick the gateway per currency:

pro-monthly-inr   ₹4,999.00   → Razorpay
pro-monthly-usd   $59.00      → Stripe
pro-monthly-eur   €55.00      → Stripe

Usage charges are different: a single charge carries a per-currency amounts map, so one metered plan can rate in whatever currency the subscription bills in:

"amounts": {
  "INR": { "tiers": [ { "up_to": null, "unit_amount": "0.30" } ] },
  "USD": { "tiers": [ { "up_to": null, "unit_amount": "0.004" } ] }
}

See the Multi-Currency guide for FX-normalized reporting.

Archive a Plan

Archived plans can’t be used for new subscriptions but existing subscriptions continue unaffected:

await recurso.plans.archive('3e7a9c52-1b4d-4f8e-a6c3-2d5b8e9f0a14');
// restore later with: recurso.plans.update(id, { active: true })

curl -X PUT https://api.recurso.dev/v1/plans/3e7a9c52-1b4d-4f8e-a6c3-2d5b8e9f0a14 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

Archiving is also available in the dashboard (Plans → ⋯ → Archive). See Update a Plan.

Archiving is not reversible. If you need the same plan again, create a new one. Existing subscribers on the archived plan continue billing normally — only new sign-ups are blocked.

Plan Versioning Strategy

When you need to change pricing, you have two options:

Approach	When to Use
Create a new plan	You want existing subscribers to keep their current rate. New customers get the new price.
Update the existing plan	You want the price change to apply to all subscribers at their next renewal.

The recommended approach is to create a new plan for each pricing change. This gives you a clear audit trail and avoids unexpected charge changes for existing customers.

// v1 — original pricing
const v1 = await recurso.plans.create({
  name: 'Pro Plan',
  code: 'pro-monthly-v1',
  interval_unit: 'month',
  interval_count: 1,
  amount: 499900,
  currency: 'INR',
});

// v2 — price increase (archive v1 from the dashboard)
const v2 = await recurso.plans.create({
  name: 'Pro Plan',
  code: 'pro-monthly-v2',
  interval_unit: 'month',
  interval_count: 1,
  amount: 599900,
  currency: 'INR',
});
// Existing v1 subscribers keep paying ₹4,999
// New subscribers sign up at ₹5,999

Best Practices

Version Plans

Create new plans instead of modifying prices. Existing subscribers keep their rates.

Multi-Currency

One plan code per currency (pro-monthly-inr / -usd); the smart router picks the right gateway per currency.

Clear Names

Use descriptive names customers will recognize on their credit card statements.

Entitlements

Attach feature grants to plans and gate access with the entitlements check endpoint.

Get Started

Migrate to Recurso

Core Concepts

Usage & Monetization

Money & Books

Tax & Compliance

Recover & Retain

Customer Portal

Platform & Integrations

Deploy & Operate

Reference

Anatomy of a Plan

Create a Plan

Pricing Models

Plan Intervals

Trials

List Plans

Filter Parameters

Multi-Currency Pricing

Archive a Plan

Plan Versioning Strategy

Best Practices

Version Plans

Multi-Currency

Clear Names

Entitlements

​Anatomy of a Plan

​Create a Plan

​Pricing Models

​Plan Intervals

​Trials

​List Plans

​Filter Parameters

​Multi-Currency Pricing

​Archive a Plan

​Plan Versioning Strategy

​Best Practices

Version Plans

Multi-Currency

Clear Names

Entitlements

Anatomy of a Plan

Create a Plan

Pricing Models

Plan Intervals

Trials

List Plans

Filter Parameters

Multi-Currency Pricing

Archive a Plan

Plan Versioning Strategy

Best Practices