Getting Started

Quickstart

Get up and running with NovaBilling in under 5 minutes.

Quickstart

This guide walks you through the essential steps to start billing. By the end, you will have registered a tenant, created an API key, added a customer, set up a plan, and started a subscription.

Prerequisites

A valid email address for tenant registration
curl installed (for REST examples), or one of the NovaBilling SDKs

Install an SDK (Optional)

npm install novabilling

yarn add novabilling

pip install novabilling

Step 1: Register a Tenant

Create your tenant account. Each tenant receives an isolated database.

curl -X POST http://localhost:3000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "admin@acme.com",
    "password": "securepassword123",
    "companyName": "Acme Corp"
  }'

import { NovaBillingClient } from 'novabilling';

const client = new NovaBillingClient();

const session = await client.auth.register({
  name: 'John Doe',
  email: 'admin@acme.com',
  password: 'securepassword123',
  companyName: 'Acme Corp'
});

from novabilling import NovaBilling

client = NovaBilling()

session = client.auth.register(
    name="John Doe",
    email="admin@acme.com",
    password="securepassword123",
    company_name="Acme Corp"
)

Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}

Authenticate to receive JWT tokens for tenant management.

curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@acme.com",
    "password": "securepassword123"
  }'

const session = await client.auth.login({
  email: 'admin@acme.com',
  password: 'securepassword123'
});

session = client.auth.login(
    email="admin@acme.com",
    password="securepassword123"
)

Step 3: Create an API Key

API keys are used for all data operations (customers, plans, subscriptions, etc.).

curl -X POST http://localhost:3000/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"]
  }'

const apiKey = await client.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!

api_key = client.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!

Store your API key securely. It is displayed only once at creation time and cannot be retrieved later.

Step 4: Create Your First Customer

From this point on, all data operations use the API key as the Bearer token.

curl -X POST http://localhost:3000/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"
  }'

const apiClient = new NovaBillingClient({
  token: 'sk_live_a1b2c3d4...'
});

const customer = await apiClient.customers.create({
  externalId: 'usr_sarah_01',
  email: 'sarah@kampaltech.ug',
  name: 'Nakato Sarah',
  country: 'UG',
  currency: 'UGX'
});

console.log('Customer ID:', customer.id);

api_client = NovaBilling(token="sk_live_a1b2c3d4...")

customer = api_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 5: Create a Plan

Define a billing plan with pricing.

curl -X POST http://localhost:3000/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 apiClient.plans.create({
  name: 'Pro Plan',
  code: 'pro',
  billingInterval: 'MONTHLY',
  features: ['Unlimited projects', 'Priority support', 'API access']
});

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

plan = api_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:3000/api/plans/{plan_id}/prices \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_a1b2c3d4..." \
  -d '{"currency": "UGX", "amount": 180000}'

await apiClient.plans.addPrice(plan.id, {
  currency: 'UGX',
  amount: 180000
});

api_client.plans.add_price(
    plan.id,
    currency="UGX",
    amount=180000
)

Step 6: Create a Subscription

Subscribe the customer to the plan.

curl -X POST http://localhost:3000/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 apiClient.subscriptions.create({
  customerId: customer.id,
  planId: plan.id,
  currency: 'UGX'
});

console.log('Subscription:', subscription.id);
console.log('Status:', subscription.status); // "ACTIVE"

subscription = api_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?

Authentication -- Learn about JWT tokens, API keys, and scopes
Payment Providers -- Configure Stripe, Flutterwave, Paystack, or M-Pesa
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

Edit this pageorReport an issue

Introduction

Learn what NovaBilling is, its core architecture, and how it can power your billing infrastructure.

Authentication

Understand NovaBilling's dual authentication model with JWT tokens for tenant management and API keys for data operations.