Getting Started
Quickstart
Get up and running with PimaBill in under 5 minutes.
This guide walks you through the essential steps to start billing. By the end, you will have registered, added a customer, set up a plan, and started a subscription.
Prerequisites
- A running PimaBill API (
docker compose up; it listens on port 4000) curlinstalled (for REST examples), or one of the PimaBill SDKs
Install an SDK (Optional)
npm install pimabill
yarn add pimabill
pip install pimabill
Step 1: Register
Create your organisation, from the dashboard's sign-up page or the API. Each organisation gets its own isolated database.
curl -X POST http://localhost:4000/api/auth/register \
-H "Content-Type: application/json" \
-d '{
"name": "John Doe",
"email": "admin@acme.com",
"password": "securepassword123",
"companyName": "Acme Corp"
}'
The response signs you in and includes the organisation's first API key:
{
"apiKey": "sk_live_a1b2c3d4...",
"accessToken": "eyJhbGciOiJIUzI1NiIs...",
"refreshToken": "eyJhbGciOiJIUzI1NiIs...",
"role": "OWNER",
"user": { "id": "usr_...", "name": "John Doe", "email": "admin@acme.com" },
"tenant": { "id": "ten_...", "name": "Acme Corp", "slug": "acme-corp" }
}
Store the API key securely. It is only shown in full when it is created.
Step 2: Create More API Keys (Optional)
Give each service its own named key with only the scopes it needs. Account settings like API keys are managed while signed in, with the access token from Step 1.
curl -X POST http://localhost:4000/api/tenants/me/api-keys \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
-d '{
"name": "Production Key",
"scopes": ["customers:read", "customers:write", "plans:read", "plans:write",
"subscriptions:read", "subscriptions:write", "invoices:read", "payments:read"]
}'
import { PimaBillClient } from 'pimabill';
const account = new PimaBillClient({ token: 'eyJhbGciOiJIUzI1NiIs...' }); // the access token
const apiKey = await account.apiKeys.create({
name: 'Production Key',
scopes: ['customers:read', 'customers:write', 'plans:read', 'plans:write',
'subscriptions:read', 'subscriptions:write', 'invoices:read', 'payments:read'],
});
console.log('API Key:', apiKey.key); // Store this securely!
from pimabill import PimaBillClient
account = PimaBillClient(token="eyJhbGciOiJIUzI1NiIs...") # the access token
api_key = account.api_keys.create(
name="Production Key",
scopes=["customers:read", "customers:write", "plans:read", "plans:write",
"subscriptions:read", "subscriptions:write", "invoices:read", "payments:read"],
)
print(f"API Key: {api_key.key}") # Store this securely!
Step 3: Create Your First Customer
From here on, everything uses an API key as the Bearer token.
curl -X POST http://localhost:4000/api/customers \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk_live_a1b2c3d4..." \
-d '{
"externalId": "usr_sarah_01",
"email": "sarah@kampaltech.ug",
"name": "Nakato Sarah",
"country": "UG",
"currency": "UGX"
}'
import { PimaBillClient } from 'pimabill';
const client = new PimaBillClient({
token: 'sk_live_a1b2c3d4...',
baseUrl: 'http://localhost:4000',
});
const customer = await client.customers.create({
externalId: 'usr_sarah_01',
email: 'sarah@kampaltech.ug',
name: 'Nakato Sarah',
country: 'UG',
currency: 'UGX',
});
console.log('Customer ID:', customer.id);
from pimabill import PimaBillClient
client = PimaBillClient(token="sk_live_a1b2c3d4...", base_url="http://localhost:4000")
customer = client.customers.create(
external_id="usr_sarah_01",
email="sarah@kampaltech.ug",
name="Nakato Sarah",
country="UG",
currency="UGX",
)
print(f"Customer ID: {customer.id}")
Step 4: Create a Plan
Define a billing plan with pricing.
curl -X POST http://localhost:4000/api/plans \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk_live_a1b2c3d4..." \
-d '{
"name": "Pro Plan",
"code": "pro",
"billingInterval": "MONTHLY",
"features": ["Unlimited projects", "Priority support", "API access"]
}'
const plan = await client.plans.create({
name: 'Pro Plan',
code: 'pro',
billingInterval: 'MONTHLY',
features: ['Unlimited projects', 'Priority support', 'API access']
});
console.log('Plan ID:', plan.id);
plan = client.plans.create(
name="Pro Plan",
code="pro",
billing_interval="MONTHLY",
features=["Unlimited projects", "Priority support", "API access"]
)
print(f"Plan ID: {plan.id}")
Then add a price for the plan:
curl -X POST http://localhost:4000/api/plans/{plan_id}/prices \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk_live_a1b2c3d4..." \
-d '{"currency": "UGX", "amount": 180000}'
await client.plans.addPrice(plan.id, { currency: 'UGX', amount: 180000 });
client.plans.add_price(
plan.id,
currency="UGX",
amount=180000
)
Step 5: Create a Subscription
Subscribe the customer to the plan.
curl -X POST http://localhost:4000/api/subscriptions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk_live_a1b2c3d4..." \
-d '{
"customerId": "cust_x1y2z3",
"planId": "plan_abc123",
"currency": "UGX"
}'
const subscription = await client.subscriptions.create({
customerId: customer.id,
planId: plan.id,
currency: 'UGX'
});
console.log('Subscription:', subscription.id);
console.log('Status:', subscription.status); // "ACTIVE"
subscription = client.subscriptions.create(
customer_id=customer.id,
plan_id=plan.id,
currency="UGX"
)
print(f"Subscription: {subscription.id}")
print(f"Status: {subscription.status}") # "ACTIVE"
Response:
{
"id": "sub_j3k4l5",
"customerId": "cust_x1y2z3",
"planId": "plan_abc123",
"status": "ACTIVE",
"currency": "UGX",
"currentPeriodStart": "2025-01-15T00:00:00.000Z",
"currentPeriodEnd": "2025-02-15T00:00:00.000Z",
"createdAt": "2025-01-15T10:50:00.000Z"
}
What's Next?
- Build an Integration: connect your app from sandbox to live, step by step
- Authentication -- Learn about JWT tokens, API keys, and scopes
- Payment Providers -- Configure Stripe, Flutterwave, Paystack, Pesapal and more
- Invoices & Payments -- Generate checkout URLs and process payments
- Webhooks -- Set up real-time notifications for billing events
- TypeScript SDK / Python SDK -- Explore full SDK capabilities