---
title: "List grants for credit"
method: GET
path: "/billing/credits/grants/list"
tags: ["credits"]
---

# List grants for credit

`GET /billing/credits/grants/list`

## Query parameters

- `credit_id` string
- `ids` string[]
- `limit` integer — Page limit (default 100)
- `offset` integer — Page offset (default 0)

## Response `200`

OK

- object
  - `data` BillingCreditGrantResponseData[], required
    - `company_id` string, required
    - `company_license_id` string, nullable — The license instance this grant was issued for. Set only when a per-license plan grant issued it; null on a plan's own grant.
    - `company_name` string, required
    - `created_at` string, date-time, required
    - `credit_icon` string, nullable
    - `credit_id` string, required
    - `credit_name` string, required
    - `currency` string, nullable
    - `expires_at` string, date-time, nullable
    - `grant_reason` 'adjustment' | 'billing_credit_auto_topup' | 'free' | 'plan' | 'purchased' | 'rollover', required
    - `id` string, required
    - `license_name` string, nullable — Name of the license this grant was issued for, when it came from a per-license plan grant.
    - `plan_id` string, nullable
    - `plan_name` string, nullable
    - `price` BillingPriceResponseData
      - `currency` string, required
      - `external_price_id` string, required
      - `id` string, required
      - `interval` 'day' | 'month' | 'one-time' | 'year', required
      - `interval_count` integer, required
      - `nickname` string, nullable
      - `price` integer, required
      - `price_decimal` string, nullable
      - `provider_type` 'metronome' | 'orb' | 'schematic' | 'stripe', required
      - `scheme` 'per_unit' | 'tiered', required
    - `quantity` number, double, required
    - `quantity_remaining` number, double, required
    - `quantity_used` number, double, required
    - `renewal_enabled` boolean, required
    - `renewal_period` 'daily' | 'every_6_months' | 'monthly' | 'quarterly' | 'weekly' | 'yearly'
    - `reserved` number, double, nullable
    - `settled` number, double, nullable
    - `source_grant_id` string, nullable — For rollover grants, the ID of the source grant that this grant rolled from.
    - `source_label` string, required
    - `transfers` CreditTransferResponseData[]
      - `amount` number, double, required
      - `created_at` string, date-time, required
      - `direction` string, required
      - `id` string, required
      - `reason` string, required
      - `related_grant_id` string, required
    - `updated_at` string, date-time, required
    - `valid_from` string, date-time, nullable
    - `zeroed_out_date` string, date-time, nullable
    - `zeroed_out_reason` 'customer_archived' | 'expired' | 'integration_uninstalled' | 'license_retired' | 'manual' | 'plan_change' | 'plan_period_reset' | 'reconciled'
  - `params` object, required — Input parameters
    - `credit_id` string
    - `ids` string[]
    - `limit` integer — Page limit (default 100)
    - `offset` integer — Page offset (default 0)

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not found
- `500` — Server error

## Changes

- **2026-08-11** `12e9d0ac19a9` — 2 info
  - added the optional property `data/items/company_license_id` to the response with the `200` status
  - added the optional property `data/items/license_name` to the response with the `200` status
- **2026-07-27** `e83d3358bab3` — 1 warning
  - added the new `license_retired` enum value to the `data/items/zeroed_out_reason/allOf[#/components/schemas/BillingCreditGrantZeroedOutReason]/` response property for the response status `200`
- **2026-07-15** `3baa54bf8b3f` — 2 warning
  - for the `query` request parameter `limit`, the max was set to `250.00`
  - for the `query` request parameter `limit`, the min was set to `0.00`
- **2026-07-09** `8da6172fc3e9` — 2 warning
  - added the new `every_6_months` enum value to the `data/items/renewal_period/allOf[#/components/schemas/BillingPlanCreditGrantResetCadence]/` response property for the response status `200`
  - added the new `quarterly` enum value to the `data/items/renewal_period/allOf[#/components/schemas/BillingPlanCreditGrantResetCadence]/` response property for the response status `200`
- **2026-07-06** `e6b85f57df53` — 1 warning
  - added the new `customer_archived` enum value to the `data/items/zeroed_out_reason/allOf[#/components/schemas/BillingCreditGrantZeroedOutReason]/` response property for the response status `200`

[Full history](https://skmtc.dev/schematichq/apis/schematic-api/changes/billing/credits/grants/list/get.md)

---

[API](https://skmtc.dev/schematichq/apis/schematic-api.md) · [All operations](https://skmtc.dev/schematichq/apis/schematic-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/schematichq/schematic-api/revisions/0b238e148fa1/schema)