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

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

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"
}

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

Automatic Issuance

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

1. All attached draft invoices are finalized
2. A master invoice is created summing all line items
3. If a payment_setup is configured, an auto-charge is attempted
4. 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

Key Attributes

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.