Guides

Plans & Pricing

Create and manage subscription plans with multi-currency pricing and billing intervals.

Plans define the products or services you offer to customers along with their pricing, billing frequency, and included features. PimaBill supports multi-currency pricing and flexible billing intervals.

Plan Object

Field	Type	Description
`id`	string	Unique identifier (e.g., `plan_abc123`)
`name`	string	Display name for the plan
`code`	string	Unique code for the plan (e.g., `pro`)
`billingInterval`	string	Billing frequency: `MONTHLY`, `QUARTERLY`, `YEARLY`
`features`	string	List of features included in the plan
`isActive`	boolean	Whether the plan is available for new subscriptions
`createdAt`	string	ISO 8601 creation timestamp

Creating Plans

Basic Plan

curl -X POST http://localhost:4000/api/plans \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_a1b2c3d4..." \
  -d '{
    "name": "Starter",
    "code": "starter",
    "billingInterval": "MONTHLY",
    "features": [
      "5 projects",
      "10 team members",
      "Email support",
      "1 GB storage"
    ]
  }'

import { PimaBillClient } from 'pimabill';

const client = new PimaBillClient({ token: 'sk_live_a1b2c3d4...' });

const starter = await client.plans.create({
  name: 'Starter',
  code: 'starter',
  billingInterval: 'MONTHLY',
  features: [
    '5 projects',
    '10 team members',
    'Email support',
    '1 GB storage'
  ]
});

console.log('Plan ID:', starter.id);

from pimabill import PimaBillClient

client = PimaBillClient(token="sk_live_a1b2c3d4...")

starter = client.plans.create(
    name="Starter",
    code="starter",
    billing_interval="MONTHLY",
    features=[
        "5 projects",
        "10 team members",
        "Email support",
        "1 GB storage"
    ]
)

print(f"Plan ID: {starter.id}")

Adding Prices to a Plan

After creating a plan, add one or more prices for different currencies:

curl -X POST http://localhost:4000/api/plans/plan_abc123/prices \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_a1b2c3d4..." \
  -d '{
    "currency": "UGX",
    "amount": 50000
  }'

// Ugandan Shilling price
await client.plans.addPrice('plan_abc123', { currency: 'UGX', amount: 50000 });

// US Dollar price
await client.plans.addPrice('plan_abc123', { currency: 'USD', amount: 15 });

# Ugandan Shilling price
client.plans.add_price("plan_abc123", currency="UGX", amount=50000)

# US Dollar price
client.plans.add_price("plan_abc123", currency="USD", amount=15)

Multi-Currency Pricing

PimaBill supports 17 currencies. Add multiple prices to a single plan for different markets.

Supported Currencies

Code	Currency	Example Amount
UGX	Ugandan Shilling	180,000
NGN	Nigerian Naira	15,000
KES	Kenyan Shilling	2,500
GHS	Ghanaian Cedi	150
ZAR	South African Rand	350
TZS	Tanzanian Shilling	35,000
RWF	Rwandan Franc	15,000
EGP	Egyptian Pound	500
USD	US Dollar	29
EUR	Euro	25
GBP	British Pound	22

Billing Intervals

Interval	Description	Use Case
`MONTHLY`	Billed every month	Standard recurring billing
`QUARTERLY`	Billed every 3 months	Moderate commitment with slight discount
`YEARLY`	Billed every 12 months	Long-term commitment with significant discount

Updating Plans

Update plan details. Changes apply to new subscriptions; existing subscriptions retain their original terms unless explicitly changed.

curl -X PATCH http://localhost:4000/api/plans/plan_abc123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_a1b2c3d4..." \
  -d '{
    "name": "Starter v2",
    "features": [
      "10 projects",
      "20 team members",
      "Email support",
      "5 GB storage"
    ]
  }'

const updated = await client.plans.update('plan_abc123', {
  name: 'Starter v2',
  features: [
    '10 projects',
    '20 team members',
    'Email support',
    '5 GB storage'
  ]
});

updated = client.plans.update(
    "plan_abc123",
    name="Starter v2",
    features=[
        "10 projects",
        "20 team members",
        "Email support",
        "5 GB storage"
    ]
)

Price changes to a plan do not automatically update existing subscriptions. To change pricing for an existing subscription, update the subscription's plan or create a new plan version.

Listing Plans

Add ?code=starter to get just the plan with that code. Codes are the same in live and the sandbox, while IDs are not, so look plans up by code in your app.

curl -X GET "http://localhost:4000/api/plans?isActive=true" \
  -H "Authorization: Bearer sk_live_a1b2c3d4..."

const plans = await client.plans.list({ isActive: true });

for (const plan of plans) {
  console.log(`${plan.name} (${plan.code}) - ${plan.billingInterval}`);
}

plans = client.plans.list(is_active=True)

for plan in plans:
    print(f"{plan.name} ({plan.code}) - {plan.billing_interval}")

Best Practices

Use descriptive names -- Plan names appear on invoices and customer-facing interfaces. Use clear, descriptive names like "Pro Plan (Monthly)" rather than internal codes.
Version your plans -- When making significant pricing changes, create a new plan version instead of modifying the existing one. Use the code field to track plan versions.
Offer annual discounts -- Annual plans reduce churn and improve cash flow. A 15-20% discount compared to monthly billing is a common approach.
Add multiple currency prices -- For each plan, add prices in all currencies you want to support. This enables automatic currency matching for customers.

Edit this page

One-time Products & Partial Payments

Sell bundles and courses that are paid once and never renew, and let customers pay with a deposit or in instalments.

Subscriptions

Manage the full subscription lifecycle including creation, pausing, cancellation, and plan changes.