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

# List customer entitlement balances with advanced filtering

> Retrieve customer entitlement balances with comprehensive filtering, sorting, and pagination.

Filter by:
- Customer: customer, customer__in (filter by specific customer IDs).
- Entitlement: entitlement, entitlement__in (filter by specific entitlement IDs).
- Contract: contract_id, contract_id__in (filter by contract IDs - useful for contract-specific entitlements).
- Quantities: quantity, quantity_used with range filters (gt, gte, lt, lte, neq).
- Dates: created_at, active_from with range filters for time-based filtering.
- Status: Use quantity__gt=0 to show only active balances, or quantity_used__lt=quantity to show available balances.

Enrichment options (populate parameter):
- customer: Include customer name and email details.
- contract: Include contract name for entitlements granted by contracts.
- product: Include product name for product-specific entitlements.
- invoice: Include invoice number for invoice-generated entitlements.
- Multiple: Use comma-separated values like 'customer,contract,product,invoice' for full enrichment.

Pagination & sorting:
- limit: page size (1-100, default 50).
- cursor: pass 'next' from previous response to paginate.
- sort_key: field to sort by (id, created_at, quantity, quantity_used, active_from, expiry_at).
- sort_type: 'asc' or 'desc' (default 'asc').
- search: text search across entitlement names and descriptions.

Common use cases:
- Contract entitlements: Use contract_id filter to get all entitlements for a specific contract.
- Customer overview: Use customer filter with populate=contract,product for complete customer entitlement view.
- Low balance alerts: Use quantity__gt=0 and quantity_used__gte with percentage calculations.
- Expiring entitlements: Use expiry_at__lt with future date to find soon-to-expire entitlements.



## OpenAPI

````yaml /openAPI/openapi-20240301.json get /entitlements/customers_balances
openapi: 3.1.0
info:
  title: zenskar
  version: 2.0.0
servers:
  - url: https://api.zenskar.com
security:
  - ApiTokenAuth: []
    OrganisationAuth: []
paths:
  /entitlements/customers_balances:
    get:
      tags:
        - Entitlements
      summary: List customer entitlement balances with advanced filtering
      description: >-
        Retrieve customer entitlement balances with comprehensive filtering,
        sorting, and pagination.


        Filter by:

        - Customer: customer, customer__in (filter by specific customer IDs).

        - Entitlement: entitlement, entitlement__in (filter by specific
        entitlement IDs).

        - Contract: contract_id, contract_id__in (filter by contract IDs -
        useful for contract-specific entitlements).

        - Quantities: quantity, quantity_used with range filters (gt, gte, lt,
        lte, neq).

        - Dates: created_at, active_from with range filters for time-based
        filtering.

        - Status: Use quantity__gt=0 to show only active balances, or
        quantity_used__lt=quantity to show available balances.


        Enrichment options (populate parameter):

        - customer: Include customer name and email details.

        - contract: Include contract name for entitlements granted by contracts.

        - product: Include product name for product-specific entitlements.

        - invoice: Include invoice number for invoice-generated entitlements.

        - Multiple: Use comma-separated values like
        'customer,contract,product,invoice' for full enrichment.


        Pagination & sorting:

        - limit: page size (1-100, default 50).

        - cursor: pass 'next' from previous response to paginate.

        - sort_key: field to sort by (id, created_at, quantity, quantity_used,
        active_from, expiry_at).

        - sort_type: 'asc' or 'desc' (default 'asc').

        - search: text search across entitlement names and descriptions.


        Common use cases:

        - Contract entitlements: Use contract_id filter to get all entitlements
        for a specific contract.

        - Customer overview: Use customer filter with populate=contract,product
        for complete customer entitlement view.

        - Low balance alerts: Use quantity__gt=0 and quantity_used__gte with
        percentage calculations.

        - Expiring entitlements: Use expiry_at__lt with future date to find
        soon-to-expire entitlements.
      operationId: List-customer-entitlement-balances-with-advanced-filtering
      parameters:
        - name: cursor
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              The cursor indicating a unique set of results - this should be
              auto generated and you get it from the `next` and `previous`
              fields of the response
            examples:
              - V2VsbCBhcmV1IGN1cmlvdxM=
            title: Cursor
          description: >-
            The cursor indicating a unique set of results - this should be auto
            generated and you get it from the `next` and `previous` fields of
            the response
        - name: limit
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: The number of results to return - defaults to 10
            examples:
              - 10
            title: Limit
          description: The number of results to return - defaults to 10
        - name: sort_key
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Field to sort results by
            examples:
              - id
              - created_at
              - quantity
              - quantity_used
              - active_from
              - expiry_at
            title: Sort Key
          description: Field to sort results by
        - name: sort_type
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Sort direction (asc or desc)
            examples:
              - asc
              - desc
            title: Sort Type
          description: Sort direction (asc or desc)
        - name: search
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Search
        - name: populate
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Comma-separated list of fields to populate with related data
            examples:
              - customer
              - contract
              - product
              - invoice
              - customer,contract,product,invoice
            title: Populate
          description: Comma-separated list of fields to populate with related data
        - name: id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: uuid
              - type: 'null'
            title: Id
        - name: id__in
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Id  In
        - name: id__isnull
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            title: Id  Isnull
        - name: entitlement
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: uuid
              - type: 'null'
            title: Entitlement
        - name: entitlement__in
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Entitlement  In
        - name: entitlement__isnull
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            title: Entitlement  Isnull
        - name: customer
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: uuid
              - type: 'null'
            title: Customer
        - name: customer__in
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Customer  In
        - name: customer__isnull
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            title: Customer  Isnull
        - name: contract_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: uuid
              - type: 'null'
            title: Contract Id
        - name: contract_id__in
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Contract Id  In
        - name: contract_id__isnull
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            title: Contract Id  Isnull
        - name: created_at
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            title: Created At
        - name: created_at__neq
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            title: Created At  Neq
        - name: created_at__gt
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            title: Created At  Gt
        - name: created_at__gte
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            title: Created At  Gte
        - name: created_at__lt
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            title: Created At  Lt
        - name: created_at__lte
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            title: Created At  Lte
        - name: created_at__isnull
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            title: Created At  Isnull
        - name: created_at__in
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Created At  In
        - name: active_from
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            title: Active From
        - name: active_from__neq
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            title: Active From  Neq
        - name: active_from__gt
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            title: Active From  Gt
        - name: active_from__gte
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            title: Active From  Gte
        - name: active_from__lt
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            title: Active From  Lt
        - name: active_from__lte
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            title: Active From  Lte
        - name: active_from__isnull
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            title: Active From  Isnull
        - name: active_from__in
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Active From  In
        - name: quantity
          in: query
          required: false
          schema:
            anyOf:
              - type: number
              - type: 'null'
            title: Quantity
        - name: quantity__neq
          in: query
          required: false
          schema:
            anyOf:
              - type: number
              - type: 'null'
            title: Quantity  Neq
        - name: quantity__gt
          in: query
          required: false
          schema:
            anyOf:
              - type: number
              - type: 'null'
            title: Quantity  Gt
        - name: quantity__gte
          in: query
          required: false
          schema:
            anyOf:
              - type: number
              - type: 'null'
            title: Quantity  Gte
        - name: quantity__lt
          in: query
          required: false
          schema:
            anyOf:
              - type: number
              - type: 'null'
            title: Quantity  Lt
        - name: quantity__lte
          in: query
          required: false
          schema:
            anyOf:
              - type: number
              - type: 'null'
            title: Quantity  Lte
        - name: quantity__isnull
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            title: Quantity  Isnull
        - name: quantity__in
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Quantity  In
        - name: quantity_used
          in: query
          required: false
          schema:
            anyOf:
              - type: number
              - type: 'null'
            title: Quantity Used
        - name: quantity_used__neq
          in: query
          required: false
          schema:
            anyOf:
              - type: number
              - type: 'null'
            title: Quantity Used  Neq
        - name: quantity_used__gt
          in: query
          required: false
          schema:
            anyOf:
              - type: number
              - type: 'null'
            title: Quantity Used  Gt
        - name: quantity_used__gte
          in: query
          required: false
          schema:
            anyOf:
              - type: number
              - type: 'null'
            title: Quantity Used  Gte
        - name: quantity_used__lt
          in: query
          required: false
          schema:
            anyOf:
              - type: number
              - type: 'null'
            title: Quantity Used  Lt
        - name: quantity_used__lte
          in: query
          required: false
          schema:
            anyOf:
              - type: number
              - type: 'null'
            title: Quantity Used  Lte
        - name: quantity_used__isnull
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            title: Quantity Used  Isnull
        - name: quantity_used__in
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Quantity Used  In
      responses:
        '200':
          description: Successfully retrieved customer entitlement balances
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/PaginatedResults_EntitlementCustomerResponseSchema_
              example:
                results:
                  - id: 123e4567-e89b-12d3-a456-426614174000
                    name: API Calls
                    units: calls
                    type: Quantity
                    entitlement: 456e7890-e12b-34c5-d678-901234567890
                    customer:
                      id: 789e0123-e45f-67g8-h901-234567890123
                      name: Acme Corp
                      email: billing@acme.com
                    quantity: 10000
                    quantity_used: 2500
                    quantity_remaining: 7500
                    active_from: '2024-01-01T00:00:00Z'
                    expiry_at: '2024-12-31T23:59:59Z'
                    created_at: '2024-01-01T10:30:00Z'
                    contract_id: contract-uuid-123
                    contract:
                      id: contract-uuid-123
                      name: Enterprise Plan 2024
                    product:
                      id: product-uuid-456
                      name: API Access Product
                    invoice:
                      id: invoice-uuid-789
                      name: INV-2024-001
                    event: Invoice
                    invoice_id: invoice-uuid-789
                  - id: 234e5678-e90b-12d3-a456-426614174001
                    name: Storage
                    units: GB
                    type: Quantity
                    entitlement: 567e8901-e23f-45g6-h789-012345678901
                    customer:
                      id: 890e1234-e56f-78g9-h012-345678901234
                      name: Tech Solutions Inc
                      email: accounts@techsolutions.com
                    quantity: 100
                    quantity_used: 45.2
                    quantity_remaining: 54.8
                    active_from: '2024-01-15T00:00:00Z'
                    expiry_at: '2024-02-14T23:59:59Z'
                    created_at: '2024-01-15T14:20:00Z'
                    contract_id: contract-uuid-456
                    event: Manual
                next: cursor_to_next_page
                total: 150
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              examples:
                invalid_sort_key:
                  summary: Invalid sort parameters
                  value:
                    error_code: INVALID_SORT_KEY
                    message: 'Invalid key: abc not available for sorting.'
        '422':
          description: Unprocessable Entity - invalid query parameters
          content:
            application/json:
              example:
                status_code: 10422
                message: Contract ID should be a valid UUID
        '500':
          description: Internal server error
          content:
            application/json:
              example:
                error_code: INTERNAL_SERVER_ERROR
                message: Failed to retrieve customer entitlement balances
components:
  schemas:
    PaginatedResults_EntitlementCustomerResponseSchema_:
      properties:
        next:
          anyOf:
            - type: string
            - type: 'null'
          title: Next
          description: The cursor for the next page of results
          examples:
            - V2VsbCBhcmV1IGN1cmlvdxM=
        previous:
          anyOf:
            - type: string
            - type: 'null'
          title: Previous
          description: The cursor for the previous page of results
          examples:
            - GmBsbCBhcmV1IGN1cmlvdxM=
        total_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Count
          description: The total count of rows
        results:
          items:
            $ref: '#/components/schemas/EntitlementCustomerResponseSchema'
          type: array
          title: Results
          description: The results for the current page
      type: object
      required:
        - results
      title: PaginatedResults[EntitlementCustomerResponseSchema]
    EntitlementCustomerResponseSchema:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Entitlement Customer Row Id
        entitlement:
          type: string
          format: uuid
          title: Entitlement
          description: Entitlement ID
        name:
          type: string
          title: Name
          description: Entitlement Name
        type:
          anyOf:
            - $ref: '#/components/schemas/EntitlementType'
            - type: 'null'
          description: Entitlement Type
        source_type:
          anyOf:
            - $ref: '#/components/schemas/SourceType'
            - type: 'null'
          description: Entitlement source type
        source_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Source Id
          description: Entitlement source id
        units:
          anyOf:
            - type: string
            - type: 'null'
          title: Units
          description: Entitlement units
        customer:
          anyOf:
            - type: string
              format: uuid
            - $ref: '#/components/schemas/app__entitlements__schema__DetailsObject'
          title: Customer
          description: Customer ID
        contract:
          anyOf:
            - $ref: '#/components/schemas/app__entitlements__schema__DetailsObject'
            - type: 'null'
          description: Contract Details
        product:
          anyOf:
            - $ref: '#/components/schemas/app__entitlements__schema__DetailsObject'
            - type: 'null'
          description: Product Details
        invoice:
          anyOf:
            - $ref: '#/components/schemas/app__entitlements__schema__DetailsObject'
            - type: 'null'
          description: Invoice Details
        active_from:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Active From
          description: Entitlement Active From
        expiry_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Expiry At
          description: Entitlement Expiry Time
        quantity:
          anyOf:
            - type: number
            - type: 'null'
          title: Quantity
          description: Entitlement Units assigned
        quantity_used:
          anyOf:
            - type: number
            - type: 'null'
          title: Quantity Used
          description: Entitlement Units Consumed
        quantity_remaining:
          anyOf:
            - type: number
            - type: 'null'
          title: Quantity Remaining
          description: Entitlement Units Remaining
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created At
          description: created time
        contract_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Contract Id
          description: Contract ID
        event:
          anyOf:
            - type: string
            - type: 'null'
          title: Event
          description: Event
        invoice_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Invoice Id
          description: Source ID
        status:
          anyOf:
            - $ref: '#/components/schemas/EntitlementCustomerStatus'
            - type: 'null'
          description: Entitlement status
      type: object
      required:
        - id
        - entitlement
        - name
        - units
        - customer
      title: EntitlementCustomerResponseSchema
      description: Create Entitlement Customer Request Schema
    EntitlementType:
      type: string
      enum:
        - Feature
        - Quantity
        - Credits
      title: EntitlementType
    SourceType:
      type: string
      enum:
        - Grant
        - Billable
        - Rollover
        - Adjustment
      title: SourceType
      description: Source type for entitlement grants
    app__entitlements__schema__DetailsObject:
      properties:
        id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Id
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
      type: object
      title: DetailsObject
    EntitlementCustomerStatus:
      type: string
      enum:
        - draft
        - active
        - expired
        - voided
      title: EntitlementCustomerStatus
      description: Status of Entitlement Customer record
  securitySchemes:
    ApiTokenAuth:
      type: apiKey
      in: header
      name: x-api-key
      x-default: <your-api-key>
    OrganisationAuth:
      type: apiKey
      in: header
      name: organisation
      x-default: <your-organisation-id>

````