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

***

## 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](https://docs.anny.co/developers/guides/admin/businesses.md) for managing business entities.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.