Skip to main content
The Billing API is organised around three objects: Customer, Account, and Bill. These objects support three distinct billing models. A merchant typically operates with one billing model that reflects how their business tracks what customers owe.

​
Billing Models

​
Customer Balance

A balance is held directly on the customer and updated as payments come in. This is the simplest model and suits merchants who track a single running amount owed per customer without needing to break it down further. The customer’s balance field represents the current amount outstanding. A positive balance indicates an amount owed by the customer (a receivable). A negative balance indicates a credit held on behalf of the customer (a payable), most commonly in prepaid or wallet scenarios where the merchant holds value the customer has already funded. It also arises after an overpayment or credit adjustment. When a payment is received, Moment sends an obligation.amount_applied webhook and you reconcile the payment against the customer’s balance. 👉 Quickstart: Customer Balance

​
Account Balance

Balances are tracked across one or more accounts within a customer. Each account carries its own independent balance. This model suits merchants who need to separate what a customer owes across different products, services, or cost centres. The customer record acts as a grouping entity. Balances live on the accounts below it. As with the Customer Balance model, an account’s balance can be positive (amount owed) or negative (credit on the account). When a payment is received against an account, Moment sends an obligation.amount_applied webhook with the account_id of the account that was paid. 👉 Quickstart: Account Balance

​
Bill

Individual bills are raised against a customer or account with a specific amount_due and optional due_date. Each bill has its own lifecycle and payment status, tracked independently. This model suits merchants who issue discrete invoices. When a payment is received against a bill, Moment sends an obligation.amount_applied webhook with the bill_id of the bill that was paid. 👉 Quickstart: Bill Amount Due

​
The Data Model

​
Customer

Customers are the top-level entity. Every billing relationship starts with a customer.
  • A customer can carry a balance (used in the Customer Balance model). Positive values represent amounts owed; negative values represent credits.
  • A customer can have multiple Accounts beneath it.
  • A customer can have Bills raised directly against it.

​
Account

Accounts are sub-entities within a customer used to track balances or bills at a finer level of granularity.
  • An account belongs to exactly one customer.
  • An account can carry a balance (used in the Account Balance model). Positive values represent amounts owed; negative values represent credits.
  • An account can have Bills raised against it.

​
Bill

A bill is a discrete payment obligation with a specific amount due.
  • A bill must belong to either a customer or an account.
  • A bill requires an amount_due and can optionally have a bill_date and due_date.
  • A bill has a status of unpaid or paid.

​
Relationships

  • A Customer can have many Accounts.
  • A Customer can have many Bills raised directly.
  • An Account can have many Bills.