> ## 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.

# List customer balances

> List customer balances in the current organization scope.

Balances consolidate draft invoices for a billing period. The `balanceable` is either a Customer or a Business (when the organization groups billing by business).




## OpenAPI

````yaml /developers/openapi/admin.openapi.json get /api/v1/customer-balances
openapi: 3.1.0
info:
  title: admin-api
  version: '1.0'
  description: >-
    The Admin API gives you **full programmatic access** to your anny
    organization. It is built for **server-side integrations** — backend
    services, automation scripts, and custom tooling that act on behalf of your
    team.


    ---


    ## When to use the Admin API


    Use the Admin API when you need to **drive workflows from your own
    systems**:


    - **Sync membership data** — create or update customers, assign them to
    communities, reflect subscription status from an external CRM

    - **Create bookings programmatically** — build back-office tools or automate
    repeat reservations without going through the customer checkout

    - **Issue and forward invoices** — generate invoices, send them to
    customers, or push them to your accounting system

    - **React to real-time events** — pair the API with
    [Webhooks](/developers/guides/admin/webhooks) to trigger side effects
    whenever a booking is created, cancelled, or checked in

    - **Drive display panels** — push live occupancy and schedule data to
    digital signage or lobby displays


    Combined with [webhook subscriptions](/developers/guides/admin/webhooks),
    you can build fully automated, event-driven workflows without polling.


    ---


    ## Authentication


    Generate a long-lived API token directly in the admin dashboard under
    **Organization Settings → API**. All requests require it in the
    `Authorization` header:


    ```

    Authorization: Bearer {access_token}

    ```


    Every endpoint is **organization-scoped**. Pass your organization ID as a
    query parameter on every request:


    ```

    ?o={organization_id}

    ```


    See the [Authentication guide](/developers/guides/authentication) for token
    scopes and the full OAuth2 flow.


    ---


    ## Admin API vs Customer API


    | | Admin API | Customer API |

    |---|---|---|

    | **Use case** | Server-side automation, backend tooling | End-user apps,
    booking widgets |

    | **Auth** | Required — API token or OAuth2 | Optional — many endpoints work
    without a token |

    | **Identifiers** | Immutable UUIDs and integer IDs | Slugs, booking
    numbers, order numbers |

    | **Access** | Full read/write | Public and customer-owned data only |


    → [Go to the Customer API](/developers/api-reference/customer)


    ---


    ## Resource Identifiers


    The Admin API uses **immutable IDs** — UUIDs for most entities, integers for
    legacy ones. These are safe to store in external systems and never change,
    even if an organization renames a resource.


    ---


    ## Starting Points


    | Guide | What it covers |

    |---|---|

    | [Getting Started](/developers) | First steps and quickstart |

    | [JSON:API Conventions](/developers/guides/json-api-conventions) | Request
    and response format |

    | [Authentication](/developers/guides/authentication) | API tokens, OAuth2,
    scopes |

    | [Availability & Booking Search](/developers/guides/availability) | Search
    open slots and timeslots |

    | [Admin Booking Creation](/developers/guides/admin/booking-creation) |
    Create bookings from the back office |

    | [Admin Booking Lifecycle](/developers/guides/admin/booking-lifecycle) |
    Status changes, check-in, cancellations |

    | [Invoices](/developers/guides/admin/invoices) | Create, send, and manage
    invoices |

    | [Customer Management](/developers/guides/admin/customer-management) |
    Create and manage customer records |

    | [Booking Calendars](/developers/guides/admin/calendar-events) | Custom
    calendar events |

    | [Timeslot Management](/developers/guides/admin/timeslot-management) |
    Manage timeslot CRUD, recurrence, allocations, and rescheduling |

    | [Broadcast Campaigns](/developers/guides/admin/broadcasting) | Email and
    push campaigns |

    | [Exports](/developers/guides/admin/exports) | Export bookings and customer
    data |

    | [Webhooks & Events](/developers/guides/admin/webhooks) | Subscribe to
    real-time events |


    ---


    ## Base URLs


    | Environment | URL |

    |---|---|

    | Production | `https://b.anny.co` |

    | Gov-Cloud | `https://b.anny.eu` |
  contact:
    name: anny GmbH
    url: https://anny.co
    email: support@anny.co
servers:
  - url: https://b.anny.co
    description: Production
  - url: https://b.anny.eu
    description: Gov-Cloud
security:
  - Bearer: []
tags:
  - name: Add-On Groups
  - name: Add-Ons
  - name: Booking Add-Ons
  - name: Booking Bundles
  - name: Booking Passes
  - name: Booking Quota Grants
  - name: Booking Quotas
  - name: Booking Rules
  - name: Bookings
  - name: Broadcast Campaigns
  - name: Broadcasts
  - name: Calendars
  - name: Cancellation Policies
  - name: Communities
  - name: External Links
  - name: Community Invites
  - name: Custom Fields
  - name: Custom Forms
  - name: Customers
  - name: Businesses
  - name: Display Panels
  - name: Displays
  - name: Document Templates
  - name: Exports
  - name: External Calendars
  - name: Files
  - name: Images
  - name: Invoices
  - name: Items
  - name: Legal Document Links
  - name: Legal Documents
  - name: Model Identifiers
  - name: Orders
  - name: Organizations
  - name: Payment Setups
  - name: Payments
  - name: Plan Subscriptions
  - name: Price Modifiers
  - name: Properties
  - name: Queues
  - name: Resource Categories
  - name: Resource Groups
  - name: Resource Properties
  - name: Resources
  - name: Scans
  - name: Schedule Groups
  - name: Schedules
  - name: Service Add-Ons
  - name: Service Groups
  - name: Services
  - name: Sub-Resources
  - name: Test-Results
  - name: Test Results
  - name: Tests
  - name: Timeslot Allocations
  - name: Timeslot Series
  - name: Timeslots
  - name: User Invites
  - name: Users
  - name: Customer Balances
  - name: Vouchers
  - name: Webhooks
paths:
  /api/v1/customer-balances:
    get:
      tags:
        - Customer Balances
      summary: List customer balances
      description: >
        List customer balances in the current organization scope.


        Balances consolidate draft invoices for a billing period. The
        `balanceable` is either a Customer or a Business (when the organization
        groups billing by business).
      operationId: list-customer-balances
      parameters:
        - schema:
            type: string
          in: header
          name: Authorization
          description: Bearer Token
          required: true
        - schema:
            type: string
          in: query
          name: o
          description: Organization ID
        - schema:
            type: string
          in: query
          name: include
          description: >-
            Comma-separated. Allowed: balanceable, customer_account, invoices,
            invoices.items, invoices.reference, master_invoice,
            master_invoice.items, payment_setup
        - schema:
            type: string
          in: query
          name: sort
          description: 'Allowed: issue_at, total, start_date, end_date, created_at'
        - schema:
            type: string
          in: query
          name: filter[status]
          description: 'Allowed values: open, issued, paid, rolled_over, void'
        - schema:
            type: string
          in: query
          name: filter[balanceable_type]
          description: 'Polymorphic type filter. Values: customers, businesses'
        - schema:
            type: string
          in: query
          name: filter[balanceable_id]
          description: UUID of the balanceable entity
        - schema:
            type: string
          in: query
          name: filter[currency]
          description: ISO 4217 currency code
        - schema:
            type: string
            format: date
          in: query
          name: filter[start_date_from]
        - schema:
            type: string
            format: date
          in: query
          name: filter[start_date_to]
        - schema:
            type: integer
          in: query
          name: page[number]
        - schema:
            type: integer
          in: query
          name: page[size]
      responses:
        '200':
          description: OK
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/customer-balances.v1'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
        - Bearer: []
components:
  schemas:
    customer-balances.v1:
      $schema: https://json-schema.org/draft/2020-12/schema
      x-version: 1.0.0
      title: Customer Balance
      type: object
      description: Consolidated billing bucket for a customer across a billing period.
      x-tags:
        - Models
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          default: customer-balances
        attributes:
          type: object
          properties:
            total:
              type: number
              description: Sum of attached draft invoice totals.
            currency:
              type: string
              description: ISO 4217 currency code.
            label:
              type: string
              description: Period label (for example "Apr 2026" or "KW 14 2026").
            status:
              type: string
              enum:
                - open
                - issued
                - paid
                - rolled_over
                - void
            start_date:
              type: string
              format: date
            end_date:
              type: string
              format: date
            issue_at:
              type:
                - string
                - 'null'
              format: date-time
              description: Scheduled issue timestamp for processing job.
            issued_at:
              type:
                - string
                - 'null'
              format: date-time
              description: Actual issuance timestamp of consolidated invoice.
            created_at:
              type: string
              format: date-time
            updated_at:
              type: string
              format: date-time
        links:
          $ref: '#/components/schemas/links.v1'
        relationships:
          type: object
          properties:
            balanceable:
              type: object
              description: >-
                Billable subject — either a Customer or a Business (when the
                organization groups invoices by business).
              properties:
                data:
                  type:
                    - object
                    - 'null'
                  properties:
                    type:
                      type: string
                    id:
                      type: string
                links:
                  $ref: '#/components/schemas/links.v1'
            customer_account:
              type: object
              properties:
                data:
                  type:
                    - object
                    - 'null'
                  properties:
                    type:
                      type: string
                    id:
                      type: string
                links:
                  $ref: '#/components/schemas/links.v1'
            invoices:
              type: object
              description: Draft invoices currently attached to this balance.
              properties:
                data:
                  type: array
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                      id:
                        type: string
                links:
                  $ref: '#/components/schemas/links.v1'
            master_invoice:
              type: object
              description: Consolidated invoice created when the balance is issued.
              properties:
                data:
                  type:
                    - object
                    - 'null'
                  properties:
                    type:
                      type: string
                    id:
                      type: string
                links:
                  $ref: '#/components/schemas/links.v1'
            payment_setup:
              type: object
              description: Preferred payment setup used for auto-charge attempts.
              properties:
                data:
                  type:
                    - object
                    - 'null'
                  properties:
                    type:
                      type: string
                    id:
                      type: string
                links:
                  $ref: '#/components/schemas/links.v1'
    links.v1:
      $schema: https://json-schema.org/draft/2020-12/schema
      x-version: 1.1.0
      title: ResourceLinks
      x-tags:
        - Models
      type: object
      description: JSON:API self-link object
      properties:
        self:
          type: string
          format: uri
  securitySchemes:
    Bearer:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.anny.co/oauth/authorize
          tokenUrl: https://auth.anny.co/oauth/token
          refreshUrl: https://auth.anny.co/oauth/token/refresh
          scopes: {}

````