novabilling-docs

API Reference

Complete API documentation for NovaBilling — 107 endpoints across 18 controllers.

API Reference

The full interactive API reference is hosted alongside the NovaBilling API server.

Open API Reference -- Browse all endpoints, try requests, and view response schemas in the interactive documentation.

Base URL

http://localhost:3000/api

Webhooks are received at:

http://localhost:3000/api/webhooks/{provider}

Authentication

All API endpoints require authentication. NovaBilling uses two authentication methods:

MethodHeaderUsed For
JWT BearerAuthorization: Bearer <jwt_token>Tenant management (/auth/*, /tenants/*)
API KeyAuthorization: Bearer sk_live_...Data operations (/customers/*, /plans/*, etc.)

See Authentication for details on obtaining tokens and API keys.

Response Format

All successful responses return JSON. List endpoints include pagination metadata:

{
  "data": [...],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 20,
    "totalPages": 8
  }
}

Rate Limiting

All endpoints are rate-limited to 100 requests per minute per tenant. Exceeding this returns a 429 Too Many Requests response.

Auth

Public endpoints for tenant registration, login, and password management.

MethodEndpointDescription
POST/auth/registerRegister a new tenant — provisions isolated database, generates API key, returns JWT tokens
POST/auth/loginLogin with email and password — returns access and refresh tokens
POST/auth/refreshExchange a refresh token for a new access/refresh token pair
POST/auth/forgot-passwordRequest a password reset email (always returns success to prevent enumeration)
POST/auth/reset-passwordSet a new password using the reset token received via email

Register

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

Login

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

Tenants

Manage your tenant profile, API keys, SMTP settings, and usage statistics. Authenticated via JWT.

MethodEndpointDescription
GET/tenants/meGet current tenant info
PATCH/tenants/meUpdate tenant profile and settings
GET/tenants/me/usageGet tenant usage statistics
POST/tenants/me/api-keysGenerate a new API key
GET/tenants/me/api-keysList all API keys
DELETE/tenants/me/api-keys/:idRevoke an API key
POST/tenants/me/smtp/testTest SMTP configuration with a test email

Customers

CRUD operations for customers plus relationship queries for their subscriptions, invoices, and payments.

MethodEndpointDescription
GET/customersList customers (paginated, searchable)
GET/customers/:idGet customer by ID
POST/customersCreate a new customer
PATCH/customers/:idUpdate a customer
DELETE/customers/:idDelete a customer (fails if active subscriptions exist)
GET/customers/:id/subscriptionsList customer's subscriptions
GET/customers/:id/invoicesList customer's invoices
GET/customers/:id/paymentsList customer's payments

Create Customer

curl -X POST http://localhost:3000/api/customers \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "cust_123",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "country": "US",
    "currency": "USD"
  }'

Plans

Manage billing plans with pricing, features, and billing configuration.

MethodEndpointDescription
GET/plansList all plans
GET/plans/:idGet plan by ID
POST/plansCreate a new plan
PATCH/plans/:idUpdate a plan
DELETE/plans/:idDelete a plan
POST/plans/:id/pricesAdd a price to a plan
PATCH/plans/:id/prices/:priceIdUpdate a plan price
DELETE/plans/:id/prices/:priceIdDelete a plan price

Create Plan

curl -X POST http://localhost:3000/api/plans \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro Plan",
    "code": "pro",
    "description": "For growing teams",
    "billingInterval": "MONTHLY",
    "features": ["Unlimited users", "Priority support"],
    "prices": [{ "currency": "USD", "amount": 49.99 }]
  }'

Subscriptions

Create and manage customer subscriptions with support for cancellation, pausing, resuming, and mid-cycle plan changes with proration.

MethodEndpointDescription
GET/subscriptionsList subscriptions (filterable by status, planId)
GET/subscriptions/:idGet subscription by ID
POST/subscriptionsCreate a new subscription
PATCH/subscriptions/:idUpdate subscription metadata
POST/subscriptions/:id/cancelCancel (immediate or end-of-period)
POST/subscriptions/:id/pausePause a subscription
POST/subscriptions/:id/resumeResume a paused subscription
POST/subscriptions/:id/change-planChange plan (with proration)

Cancel Subscription

# Immediate cancellation (issues pro-rated credit note)
curl -X POST http://localhost:3000/api/subscriptions/:id/cancel \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "cancelAt": "now" }'

# Cancel at period end
curl -X POST http://localhost:3000/api/subscriptions/:id/cancel \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "cancelAt": "period_end" }'

Invoices

Full invoice lifecycle: create, finalize, void, mark paid, generate checkout URLs, send emails, and download PDFs.

MethodEndpointDescription
GET/invoicesList invoices (filterable by status)
GET/invoices/:idGet invoice by ID
POST/invoicesCreate a new invoice
POST/invoices/:id/finalizeFinalize a draft invoice
POST/invoices/:id/voidVoid an invoice
POST/invoices/:id/mark-paidManually mark invoice as paid
POST/invoices/:id/checkoutGenerate a payment checkout URL
POST/invoices/:id/send-emailSend invoice to customer via email
GET/invoices/:id/pdfDownload invoice as PDF

Payments

View payment history and process refunds.

MethodEndpointDescription
GET/paymentsList payments (filterable by status, provider)
GET/payments/:idGet payment by ID
POST/payments/:id/refundRefund a payment (full or partial)

Refund Payment

curl -X POST http://localhost:3000/api/payments/:id/refund \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "amount": 25.00, "reason": "Customer request" }'

Payment Providers

Configure and manage payment provider integrations (Stripe, Paystack, Flutterwave, M-Pesa).

MethodEndpointDescription
GET/payment-providersList configured providers
GET/payment-providers/:idGet provider by ID
POST/payment-providersConfigure a new provider
PATCH/payment-providers/:idUpdate provider settings
DELETE/payment-providers/:idRemove a provider
POST/payment-providers/:id/testTest provider connection

Billable Metrics

Define event-based usage metrics for usage-based billing.

MethodEndpointDescription
GET/billable-metricsList all billable metrics
GET/billable-metrics/:idGet metric by ID
POST/billable-metricsCreate a billable metric
PATCH/billable-metrics/:idUpdate a billable metric
DELETE/billable-metrics/:idDelete a billable metric

Aggregation Types: COUNT, SUM, MAX, UNIQUE_COUNT, LATEST, WEIGHTED_SUM

Create Billable Metric

curl -X POST http://localhost:3000/api/billable-metrics \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Calls",
    "code": "api_calls",
    "aggregationType": "COUNT",
    "recurring": false,
    "filters": [
      { "key": "region", "values": ["us-east", "us-west", "eu"] }
    ]
  }'

Usage Events

Ingest usage events for metered billing. Supports single and batch ingestion with idempotency.

MethodEndpointDescription
POST/eventsIngest a single usage event
POST/events/batchIngest a batch of usage events
GET/events/:idGet event by ID
GET/events/subscription/:subscriptionIdList events for a subscription

Ingest Event

curl -X POST http://localhost:3000/api/events \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "txn_unique_123",
    "subscriptionId": "sub_abc",
    "code": "api_calls",
    "timestamp": "2026-02-12T10:00:00Z",
    "properties": { "region": "us-east", "bytes": 1024 }
  }'

Charges

Define pricing models attached to plans and billable metrics.

MethodEndpointDescription
GET/chargesList all charges
GET/charges/:idGet charge by ID
GET/charges/plan/:planIdList charges for a specific plan
POST/chargesCreate a charge
PATCH/charges/:idUpdate a charge
DELETE/charges/:idDelete a charge

Charge Models: STANDARD, GRADUATED, VOLUME, PACKAGE, PERCENTAGE

Create Graduated Charge

curl -X POST http://localhost:3000/api/charges \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "planId": "plan_abc",
    "billableMetricId": "bm_api_calls",
    "chargeModel": "GRADUATED",
    "billingTiming": "IN_ARREARS",
    "graduatedRanges": [
      { "fromValue": 0, "toValue": 1000, "perUnitAmount": 0, "flatAmount": 0 },
      { "fromValue": 1001, "toValue": 10000, "perUnitAmount": 0.01, "flatAmount": 0 },
      { "fromValue": 10001, "perUnitAmount": 0.005, "flatAmount": 0 }
    ]
  }'

Coupons

Create and manage discount coupons that can be applied to customers or subscriptions.

MethodEndpointDescription
GET/couponsList coupons (filterable by isActive)
GET/coupons/:idGet coupon by ID
POST/couponsCreate a coupon
PATCH/coupons/:idUpdate a coupon
DELETE/coupons/:idDelete a coupon
POST/coupons/applyApply coupon to a customer
DELETE/coupons/applied/:idRemove an applied coupon

Add-Ons

One-time or recurring add-on charges that can be applied to customer subscriptions.

MethodEndpointDescription
GET/add-onsList add-ons
GET/add-ons/:idGet add-on by ID
POST/add-onsCreate an add-on
PATCH/add-ons/:idUpdate an add-on
DELETE/add-ons/:idDelete an add-on
POST/add-ons/applyApply add-on to a customer
GET/add-ons/applied/listList applied add-ons
DELETE/add-ons/applied/:idRemove an applied add-on

Credit Notes

Issue credit notes against invoices for refunds, adjustments, or order changes.

MethodEndpointDescription
GET/credit-notesList credit notes (filterable by customerId, invoiceId, status)
GET/credit-notes/:idGet credit note by ID
POST/credit-notesCreate a credit note
PATCH/credit-notes/:idUpdate a draft credit note
POST/credit-notes/:id/finalizeFinalize a credit note
POST/credit-notes/:id/voidVoid a credit note

Reasons: DUPLICATE, PRODUCT_UNSATISFACTORY, ORDER_CHANGE, OTHER

Wallets / Prepaid Credits

Manage customer prepaid credit wallets with top-ups, voiding, and automatic invoice deduction.

MethodEndpointDescription
POST/walletsCreate a wallet for a customer
GET/walletsList wallets (filterable by customerId, status)
GET/wallets/:idGet wallet by ID
PATCH/wallets/:idUpdate wallet (name, expiration)
DELETE/wallets/:idTerminate a wallet (voids remaining credits)
POST/wallets/transactionsTop up or void credits
GET/wallets/:id/transactionsList wallet transactions

Create Wallet

curl -X POST http://localhost:3000/api/wallets \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_abc",
    "name": "Main Wallet",
    "currency": "USD",
    "rateAmount": 1.0,
    "paidCredits": 100,
    "grantedCredits": 10,
    "expirationAt": "2027-01-01T00:00:00Z"
  }'

Top Up Credits

curl -X POST http://localhost:3000/api/wallets/transactions \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "walletId": "wallet_abc",
    "paidCredits": 50,
    "grantedCredits": 5
  }'

Analytics

Revenue, subscription, customer, and payment analytics with optional date range filtering.

MethodEndpointDescription
GET/analytics/revenueRevenue analytics (totalRevenue, MRR)
GET/analytics/subscriptionsSubscription breakdown (active, canceled, etc.)
GET/analytics/customersCustomer analytics (total, new, churned)
GET/analytics/paymentsPayment analytics (success rate, volume)

All analytics endpoints accept optional dateFrom and dateTo query parameters for date-range filtering.

Customer Portal

Public-facing endpoints for customer self-service billing (authenticated via API key).

MethodEndpointDescription
GET/portal/customers/:externalId/billingCustomer billing overview
GET/portal/customers/:externalId/subscriptionsList customer subscriptions
GET/portal/customers/:externalId/invoicesList customer invoices
POST/portal/customers/:externalId/invoices/:invoiceId/checkoutCreate checkout for an invoice
GET/portal/customers/:externalId/paymentsList customer payments

Webhooks (Inbound)

Endpoints that receive payment provider webhook notifications. These are public and use provider-specific signature verification.

MethodEndpointDescription
POST/webhooks/stripeStripe webhook receiver
POST/webhooks/paystackPaystack webhook receiver
POST/webhooks/flutterwaveFlutterwave webhook receiver
POST/webhooks/mpesaM-Pesa webhook receiver

OpenAPI Spec

The raw OpenAPI 3.0 specification is available at:

GET http://localhost:3000/api/openapi.json

Webhooks

Set up real-time webhook notifications for billing events.

Copyright © 2026