Customer Balances

Consolidated billing buckets that group draft invoices across a billing period for automatic or manual issuance. For general conventions, see JSON-API Conventions. For authentication, see Authentication.

Prerequisites

A valid Bearer token with admin access
Organization context (?o={organization_id})
Customer balance feature enabled on the organization’s subscription plan

Overview

A Customer Balance collects draft invoices over a billing period (e.g., one month) and consolidates them into a single master invoice at the end of the period. This reduces invoice noise for frequent bookers. Balances are created automatically when invoices enter the pay-to-balance payment flow. They cannot be created directly via the API.

Balanceable Entity

Each balance belongs to a balanceable — either a Customer or a Business. When the organization enables “group by business” billing, invoices for customers assigned to a business are collected on the business’s balance instead of individual customer balances.

Status Lifecycle

open → issued → paid
  ↓        ↓
  void    void
  ↓
  rolled_over

Status	Description
`open`	Actively collecting invoices. New drafts are appended here.
`issued`	Billing period ended. A master invoice has been generated and optionally auto-charged.
`paid`	The master invoice has been paid (manually or via auto-charge).
`rolled_over`	Balance was below the de minimis threshold; amount rolls into the next period.
`void`	Cancelled. Attached invoices are released.

Listing Balances

GET /api/v1/customer-balances?o={org_id}

Filter by Status

GET /api/v1/customer-balances?o={org_id}&filter[status]=open

Filter by Balanceable

GET /api/v1/customer-balances?o={org_id}&filter[balanceable_type]=businesses&filter[balanceable_id]={business_uuid}

Filter by Date Range

GET /api/v1/customer-balances?o={org_id}&filter[start_date_from]=2026-01-01&filter[start_date_to]=2026-01-31

Reading a Balance

GET /api/v1/customer-balances/{uuid}?o={org_id}&include=balanceable,invoices,master_invoice,payment_setup

Available Includes

Include	Description
`balanceable`	The Customer or Business this balance belongs to
`customer_account`	The associated customer account
`invoices`	Draft invoices attached to this balance
`invoices.items`	Line items on each draft invoice
`invoices.reference`	Booking/order reference for each invoice
`master_invoice`	The consolidated invoice (after issuance)
`master_invoice.items`	Line items on the master invoice
`payment_setup`	Payment method used for auto-charge

Adding Invoices to a Balance

At Creation Time

When creating a manual invoice, pass ?add_to_balance=1 to automatically attach it to the customer’s open balance:

POST /api/v1/invoices?o={org_id}&add_to_balance=1

{
  "data": {
    "type": "invoices",
    "attributes": { ... },
    "relationships": {
      "customer": {
        "data": { "type": "customers", "id": "{customer_id}" }
      }
    }
  }
}

The system resolves the customer’s balanceable (Customer or Business) and attaches the invoice to the current open balance, creating one if none exists.

Moving an Existing Invoice

To move an existing draft invoice to a balance (or transfer between balances):

POST /api/v1/invoices/{uuid}/move-to-balance?o={org_id}

{
  "balanceable_type": "businesses",
  "balanceable_id": "{business_uuid}",
  "issued_at": "2026-06-01"
}

Field	Required	Description
`balanceable_type`	yes	`customers` or `businesses`
`balanceable_id`	yes	UUID of the target entity
`issued_at`	no	Override the balance issue date (must be today or later)

This detaches the invoice from any current balance, recalculates the old balance total, and attaches to the target’s open balance. Locked invoices and consolidated child invoices are rejected (HTTP 400).

Updating a Balance

Status transitions are the primary update operation:

PATCH /api/v1/customer-balances/{uuid}?o={org_id}

{
  "data": {
    "type": "customer-balances",
    "id": "{uuid}",
    "attributes": {
      "status": "void"
    }
  }
}

Allowed Transitions

From	To	Effect
`open`	`void`	Cancels the balance, releases attached invoices
`issued`	`paid`	Marks as paid after manual payment confirmation
`issued`	`void`	Cancels after issuance

Automatic Issuance

Balances with a scheduled issue_at timestamp are automatically processed by a background job. When issued:

All attached draft invoices are finalized
A master invoice is created summing all line items
If a payment_setup is configured, an auto-charge is attempted
A notification is sent to the customer/business

If the balance total is below the organization’s de minimis threshold, the balance is rolled_over into the next period instead.

Sorting

Parameter	Description
`issue_at`	By scheduled issuance date
`total`	By balance amount
`start_date`	By billing period start
`end_date`	By billing period end
`created_at`	By creation date

Key Attributes

Attribute	Type	Description
`total`	number	Sum of attached draft invoice totals (read-only, server-calculated)
`currency`	string	ISO 4217 currency code
`label`	string	Period label (e.g., “May 2026” or “KW 20 2026”)
`status`	string	Current lifecycle status
`start_date`	date	Billing period start
`end_date`	date	Billing period end
`issue_at`	datetime	Scheduled auto-issuance timestamp
`issued_at`	datetime	Actual issuance timestamp (set when issued)

Relationship to Businesses

When an organization enables business-level balance grouping:

Invoices for customers with a business are grouped onto the business’s balance
The balanceable relationship points to the businesses resource instead of customers
Filter with filter[balanceable_type]=businesses to find business balances

See Businesses for managing business entities.

​Prerequisites

​Overview

​Balanceable Entity

​Status Lifecycle

​Listing Balances

​Filter by Status

​Filter by Balanceable

​Filter by Date Range

​Reading a Balance

​Available Includes

​Adding Invoices to a Balance

​At Creation Time

​Moving an Existing Invoice

​Updating a Balance

​Allowed Transitions

​Automatic Issuance

​Sorting

​Key Attributes

​Relationship to Businesses