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

# Report license balances

> Reports a batch of license balance readings. Each reading names its license by `code` and is identified by (code, customer, moment): the first reading for a slot is recorded, re-sending an unchanged reading is a no-op, and a changed reading records a new version that supersedes the previous one. The payload length must equal the total. Validation applies across the whole batch — if any reading is rejected, none are recorded.



## OpenAPI

````yaml /api-reference/openapi.yaml post /v1/licenses/report-balances
openapi: 3.1.0
info:
  title: API Reference
  version: '1.0'
  description: Aira API Reference
  x-logo:
    url: https://static.useaira.com/images/airalogo.svg
    backgroundColor: '#FFFFFF'
    altText: Aira Logo
servers:
  - url: https://api.useaira.com
    description: API base URL
security:
  - ApiKey: []
paths:
  /v1/licenses/report-balances:
    post:
      tags:
        - Licenses
      summary: Report license balances
      description: >-
        Reports a batch of license balance readings. Each reading names its
        license by `code` and is identified by (code, customer, moment): the
        first reading for a slot is recorded, re-sending an unchanged reading is
        a no-op, and a changed reading records a new version that supersedes the
        previous one. The payload length must equal the total. Validation
        applies across the whole batch — if any reading is rejected, none are
        recorded.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                balances:
                  description: >-
                    An array of balance readings. Each names its license by code
                    and carries the customer, moment, total, and payload.
                  type: array
                  items:
                    type: object
                    description: >-
                      One balance reading: the state of a license for a customer
                      at a moment.
                    properties:
                      code:
                        type: string
                        pattern: ^[a-zA-Z0-9_-]+$
                        description: Code of the license this reading belongs to.
                      customerExternalId:
                        type: string
                        pattern: ^[a-zA-Z0-9_-]+$
                        description: External identifier of the customer.
                      occurredAt:
                        type: string
                        format: date-time
                        description: >-
                          ISO 8601 timestamp of the moment this reading
                          describes.
                      total:
                        type: number
                        minimum: 0
                        multipleOf: 1
                        description: How many, at that moment.
                      payload:
                        type: array
                        description: >-
                          Itemized breakdown behind the total. Its length must
                          equal the total.
                        items:
                          type: object
                          description: >-
                            One unit behind the total, such as an active user.
                            Any extra keys are kept as-is.
                          properties:
                            id:
                              type: string
                              minLength: 1
                              description: Identifier of the unit.
                            name:
                              type: string
                              description: Human-readable label for the unit.
                          required:
                            - id
                          additionalProperties:
                            anyOf:
                              - type: string
                              - type: number
                              - type: boolean
                    required:
                      - code
                      - customerExternalId
                      - occurredAt
                      - total
                      - payload
                    additionalProperties: false
                  minItems: 1
                  maxItems: 10000
              required:
                - balances
              additionalProperties: false
        required: true
        description: An object containing an array of license balance readings to report.
      responses:
        '204':
          description: The request was successfully processed.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
        '400':
          description: >-
            Invalid request; when any reading fails validation none are
            recorded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable error message explaining why the report
                      failed.
                  code:
                    type: string
                    description: Error code identifying the type of failure.
                  details:
                    type: array
                    description: List of failed readings and their specific errors.
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          description: The license code of the failed reading.
                        customerExternalId:
                          type: string
                        occurredAt:
                          type: string
                        errors:
                          type: array
                          items:
                            type: object
                            properties:
                              code:
                                type: string
                                enum:
                                  - license_code_not_found
                                  - license_balance_payload_total_mismatch
                                  - future_license_balance_moment
                                  - duplicated_license_balance_key
                              message:
                                type: string
                            required:
                              - code
                              - message
                      additionalProperties: true
                required:
                  - message
                  - code
                additionalProperties: false
components:
  securitySchemes:
    ApiKey:
      type: apiKey
      description: API Key Authentication.
      name: X-API-KEY
      in: header

````