List customer entitlement balances with advanced filtering

curl --request GET \
  --url https://api.zenskar.com/entitlements/customers_balances \
  --header 'organisation: <api-key>' \
  --header 'x-api-key: <api-key>'

{
  "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
}

Entitlements

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.

GET

entitlements

customers_balances

List customer entitlement balances with advanced filtering

curl --request GET \
  --url https://api.zenskar.com/entitlements/customers_balances \
  --header 'organisation: <api-key>' \
  --header 'x-api-key: <api-key>'

{
  "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
}

Authorizations

x-api-key

string

header

default:<your-api-key>

required

organisation

string

header

default:<your-organisation-id>

required

Query Parameters

cursor

string | null

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

Example:

"V2VsbCBhcmV1IGN1cmlvdxM="

limit

integer | null

The number of results to return - defaults to 10

Example:

10

sort_key

string | null

Field to sort results by

Example:

"id"

sort_type

string | null

Sort direction (asc or desc)

Example:

"asc"

string | null

populate

string | null

Comma-separated list of fields to populate with related data

Example:

"customer"

string<uuid> | null

id__in

string | null

id__isnull

boolean | null

entitlement

string<uuid> | null

entitlement__in

string | null

entitlement__isnull

boolean | null

customer

string<uuid> | null

customer__in

string | null

customer__isnull

boolean | null

contract_id

string<uuid> | null

contract_id__in

string | null

contract_id__isnull

boolean | null

created_at

string<date-time> | null

created_at__neq

string<date-time> | null

created_at__gt

string<date-time> | null

created_at__gte

string<date-time> | null

created_at__lt

string<date-time> | null

created_at__lte

string<date-time> | null

created_at__isnull

boolean | null

created_at__in

string | null

active_from

string<date-time> | null

active_from__neq

string<date-time> | null

active_from__gt

string<date-time> | null

active_from__gte

string<date-time> | null

active_from__lt

string<date-time> | null

active_from__lte

string<date-time> | null

active_from__isnull

boolean | null

active_from__in

string | null

quantity

number | null

quantity__neq

number | null

quantity__gt

number | null

quantity__gte

number | null

quantity__lt

number | null

quantity__lte

number | null

quantity__isnull

boolean | null

quantity__in

string | null

quantity_used

number | null

quantity_used__neq

number | null

quantity_used__gt

number | null

quantity_used__gte

number | null

quantity_used__lt

number | null

quantity_used__lte

number | null

quantity_used__isnull

boolean | null

quantity_used__in

string | null

Response

Successfully retrieved customer entitlement balances

results

EntitlementCustomerResponseSchema · object[]

required

The results for the current page

Show child attributes

string | null

The cursor for the next page of results

Example:

"V2VsbCBhcmV1IGN1cmlvdxM="

string | null

The cursor for the previous page of results

Example:

"GmBsbCBhcmV1IGN1cmlvdxM="

total_count

integer | null

The total count of rows

Create entitlement Get entitlement