> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anny.co/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/developers/guides/json-api-conventions). For authentication, see [Authentication](/developers/guides/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

```text theme={null}
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

```http theme={null}
GET /api/v1/customer-balances?o={org_id}
```

### Filter by Status

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

### Filter by Balanceable

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

### Filter by Date Range

```http theme={null}
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

```http theme={null}
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:

```http theme={null}
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):

```http theme={null}
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:

```http theme={null}
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:

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

| 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](/developers/guides/admin/businesses) for managing business entities.