Skip to main content
Use this page to identify which billing model fits your integration. Each scenario maps to one of the three supported models. See Core Concepts for a full explanation of how the models differ.

​
Rolling Statement Balance

Scenario: A customer has a monthly statement balance that reflects their current outstanding amount. The balance is updated at each billing cycle to capture new charges, adjustments, or credits. A positive balance represents an amount owed by the customer; a negative balance represents a credit on the account. Model: Customer Balance. Set or update the balance on the customer each cycle. Examples: Prepaid and postpaid utilities, mobile airtime top-up, loyalty wallet balance. 👉 Quickstart: Customer Balance

​
Multi-Service or Multi-Product Balance

Scenario: A customer is billed for multiple services that need to be tracked and settled independently. Each service has its own outstanding balance, and a customer may pay one without paying all. Balances can be positive (amount owed) or negative (credit on that account). Model: Account Balance. Create one account per service or product under the customer. Each account carries its own balance. Examples: Telecoms providers billing data, voice, and device repayments separately. Insurance companies tracking multiple policy premiums under one policyholder. 👉 Quickstart: Account Balance

​
Prepaid or Wallet Balance

Scenario: The merchant holds an active balance on behalf of the customer, typically funded through top-ups. The balance decreases as the customer consumes the service and increases when they add funds. Because the merchant owes the customer the remaining value, the balance is represented as a negative number (a credit). Model: Customer Balance or Account Balance. Set the balance to a negative value to represent the credit held. Update it as the customer tops up or consumes value. Examples: Gaming credits, prepaid airtime and data, prepaid utility balances, stored-value loyalty wallets. 👉 Quickstart: Customer Balance

​
Discrete Invoice Billing

Scenario: A specific invoice is raised for a customer with a fixed amount due and a payment deadline. Each invoice is tracked independently with its own payment status. Model: Bill. Raise a bill with amount_due and due_date against the customer. Examples: Municipality rates and taxes, professional services invoices, ad-hoc charge collection. 👉 Quickstart: Bill Amount Due

​
Multi-Service Invoice Billing

Scenario: A customer receives separate invoices per service each cycle. Each invoice has its own amount and due date and needs to be tracked independently, but services still need to roll up to a single customer for reporting. Model: Bill, with accounts used to group services. Raise bills against each account rather than directly on the customer. Examples: Municipal billing for water, electricity, and refuse as separate line items. Government agencies issuing bills per department or service type. 👉 Quickstart: Bill Amount Due