Plans are the foundation for recurring business models in Paisr. A plan acts as a reusable pricing template that defines the currency and general details of an offering. The actual billing logic — unit price, billing interval, and optional trial period — is delegated to one or more Price Options attached to the plan.
This modular approach lets you manage multiple pricing tiers, promotional structures, or regional strategies all under a single plan. For example, a single Professional plan can have a monthly option at $25/month and an annual option at $200/year.
Plan Types
| Type | Description |
|---|---|
standard | Fixed-price recurring billing. Each invoice is generated for a predetermined amount at each interval. |
metered | Usage-based billing. Invoice amounts vary based on usage reported during the billing period. See Metering. |
Creating a Plan
Navigate to Billing → Plans and click Create Plan, or use the Plans API.
curl -X POST "https://api.live.paisr.tech/v2/plans" \
-H "Authorization: Bearer <token>" \
-H "User-Agent: MyApp/1.0" \
-H "Content-Type: application/json" \
-d '{
"title": "Professional",
"summary": "Full access to all Professional features.",
"currency": "SRD",
"options": [
{ "description": "Monthly", "unit_price": 25.00, "billing_interval": 30 },
{ "description": "Annual", "unit_price": 200.00, "billing_interval": 365 }
]
}'You can define up to 10 price options when creating a plan. More can be added later.
A plan's currency cannot be changed once it is attached to an active subscription.
Updating a Plan
You can update the plan's title, summary, and currency at any time (currency changes apply only to new subscriptions):
curl -X PUT "https://api.live.paisr.tech/v2/plans/{plan_id}" \
-H "Authorization: Bearer <token>" \
-H "User-Agent: MyApp/1.0" \
-H "Content-Type: application/json" \
-d '{
"title": "Professional Plus",
"summary": "Full access including priority support."
}'Price Options
Price options define the billing logic for each pricing tier within a plan. Each option has:
| Field | Description | Constraints |
|---|---|---|
description | Label for this tier, e.g. Monthly or Annual | — |
unit_price | Amount charged per billing interval | Minimum 0.01 |
billing_interval | Length of the billing cycle in days | 1–365 |
attributes | Custom key-value pairs for tier-specific metadata | Max 16 properties |
Adding Options
Add new price options to an existing plan at any time:
curl -X POST "https://api.live.paisr.tech/v2/plans/{plan_id}/options" \
-H "Authorization: Bearer <token>" \
-H "User-Agent: MyApp/1.0" \
-H "Content-Type: application/json" \
-d '{
"options": [
{ "description": "Quarterly", "unit_price": 65.00, "billing_interval": 90 }
]
}'Updating Options
Update a price option's unit price, billing interval, or attributes. Changes take effect at the next billing interval — current-period invoices are not affected.
curl -X PUT "https://api.live.paisr.tech/v2/plans/{plan_id}/options/{option_id}" \
-H "Authorization: Bearer <token>" \
-H "User-Agent: MyApp/1.0" \
-H "Content-Type: application/json" \
-d '{
"unit_price": 22.00,
"billing_interval": 30
}'Billing interval changes on a price option are not inherited by existing active subscriptions. Only subscriptions created after the change will use the new interval.
Toggling Options
Deactivate an option to hide it from new subscriptions without affecting existing subscribers. You can reactivate it at any time.
curl -X PATCH "https://api.live.paisr.tech/v2/plans/{plan_id}/options/{option_id}" \
-H "Authorization: Bearer <token>" \
-H "User-Agent: MyApp/1.0"Removing Options
A price option can only be removed if it has no active subscribers. Use toggle to deactivate it first if needed.
curl -X DELETE "https://api.live.paisr.tech/v2/plans/{plan_id}/options/{option_id}" \
-H "Authorization: Bearer <token>" \
-H "User-Agent: MyApp/1.0"Deleting a Plan
A plan can only be deleted if it has no active subscribers. Options with active or cancelled subscriptions cannot be deleted.
curl -X DELETE "https://api.live.paisr.tech/v2/plans/{plan_id}" \
-H "Authorization: Bearer <token>" \
-H "User-Agent: MyApp/1.0"