---
title: "Fetch customer credit balance"
method: GET
path: "/customers/{customer_id}/credits"
tags: ["Credit"]
---

# Fetch customer credit balance

`GET /customers/{customer_id}/credits`

Returns a paginated list of unexpired, non-zero credit blocks for a customer.

If `include_all_blocks` is set to `true`, all credit blocks (including expired and depleted blocks) will be included in
the response.

Note that `currency` defaults to credits if not specified. To use a real world currency, set `currency` to an ISO 4217 string.

Results can be filtered by the block's `effective_date` using the `effective_date[gte]`, `effective_date[gt]`,
`effective_date[lt]`, and `effective_date[lte]` query parameters. This filters on when the credit block
becomes effective, which may differ from creation time for backdated credits.

## Path parameters

- `customer_id` string, nullable, required

## Query parameters

- `limit` integer — The number of items to fetch. Defaults to 20.
- `cursor` string, nullable — Cursor for pagination. This can be populated by the `next_cursor` value returned from the initial request.
- `currency` string, nullable — The ledger currency or custom pricing unit to use.
- `include_all_blocks` boolean — If set to True, all expired and depleted blocks, as well as active block will be returned.
- `effective_date[gte]` string, date-time, nullable
- `effective_date[gt]` string, date-time, nullable
- `effective_date[lt]` string, date-time, nullable
- `effective_date[lte]` string, date-time, nullable

## Response `200`

OK

- CustomerCreditBalances
  - `data` CustomerCreditBalance[], required
    - `metadata` object, required — User specified key-value pairs for the resource. If not present, this defaults to an empty dictionary. Individual keys can be removed by setting the value to `null`, and the entire metadata mapping can be cleared by setting `metadata` to `null`.
    - `id` string, required
    - `balance` number, required
    - `effective_date` string, date-time, nullable, required
    - `expiry_date` string, date-time, nullable, required
    - `per_unit_cost_basis` string, nullable, required
    - `status` 'active' | 'pending_payment', required
    - `maximum_initial_balance` number, nullable, required
    - `filters` BlockPriceFilter[], required
      - `field` 'item_id', required — The property of the price the block applies to. Only item_id is supported.
      - `operator` 'includes' | 'excludes', required — Should prices that match the filter be included or excluded.
      - `values` string[], required — The IDs or values that match this filter.
    - `credit_block_source` 'allocation' | 'top_up' | 'manual', required — How this credit block was created: `allocation` (a subscription's recurring credit allocation), `top_up` (an automatic balance-threshold top-up), or `manual` (a manual credit ledger increment, including credits voided or expired off another block).
    - `credit_allocation` CreditBlockAllocation — The credit allocation that funded a block. Extends the allocation resource serialized on prices with the catalog-item attribution of the funding price.
      - `currency` string, required
      - `allows_rollover` boolean, required
      - `custom_expiration` CustomExpiration, required
        - `duration` integer, required
        - `duration_unit` 'day' | 'month', required
      - `filters` PriceFilter[]
        - `field` 'price_id' | 'item_id' | 'price_type' | 'currency' | 'pricing_unit_id', required — The property of the price to filter on.
        - `operator` 'includes' | 'excludes', required — Should prices that match the filter be included or excluded.
        - `values` string[], required — The IDs or values that match this filter.
      - `license_type_id` string, nullable
      - `item_id` string, required — The ID of the catalog item this block was allocated from, derived from the allocation's price.
  - `pagination_metadata` PaginationMetadata, required
    - `has_more` boolean, required
    - `next_cursor` string, nullable, required

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `404` — Not Found
- `409` — Conflict
- `413` — Content Too Large
- `429` — Too Many Requests
- `500` — Internal Server Error

## Changes

- **2026-07-01** `2580a0ee8d4c` — 2 info
  - added the optional property `data/items/credit_allocation` to the response with the `200` status
  - added the required property `data/items/credit_block_source` to the response with the `200` status
- **2026-02-12** `c92fb451e13f` — 5 info
  - added the new optional `query` request parameter `effective_date[gt]`
  - added the new optional `query` request parameter `effective_date[gte]`
  - added the new optional `query` request parameter `effective_date[lt]`
  - added the new optional `query` request parameter `effective_date[lte]`
  - …1 more

[Change history](https://skmtc.dev/orbcorp/apis/api-reference/changes/customers/:customer_id/credits/get.md)

---

[API](https://skmtc.dev/orbcorp/apis/api-reference.md) · [All operations](https://skmtc.dev/orbcorp/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/orbcorp/api-reference/revisions/2580a0ee8d4c/schema)