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

# List company grants

`GET /billing/credits/grants/company/list`

## Request

- Base URL: `https://api.schematichq.com`
- URL: `https://api.schematichq.com/billing/credits/grants/company/list`
- Auth: API key in header `X-Schematic-Api-Key`

## Query parameters

- `company_id` string, required
- `order` 'created_at' | 'expires_at' | 'quantity' | 'quantity_remaining'
- `dir` 'asc' | 'desc'
- `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_bundle_id` string, nullable: The catalog bundle this grant was issued from, when the company bought one.
    - `credit_icon` string, nullable
    - `credit_id` string, required
    - `credit_name` string, required
    - `currency` 'aed' | 'afn' | 'all' | 'amd' | 'ang' | 'aoa' | 'ars' | 'aud' | 'awg' | 'azn' | 'bam' | 'bbd' | 'bdt' | 'bif' | 'bmd' | 'bnd' | 'bob' | 'brl' | 'bsd' | 'bwp' | 'byn' | 'bzd' | 'cad' | 'cdf' | 'chf' | 'clp' | 'cny' | 'cop' | 'crc' | 'cve' | 'czk' | 'djf' | 'dkk' | 'dop' | 'dzd' | 'egp' | 'etb' | 'eur' | 'fjd' | 'fkp' | 'gbp' | 'gel' | 'gip' | 'gmd' | 'gnf' | 'gtq' | 'gyd' | 'hkd' | 'hnl' | 'htg' | 'huf' | 'idr' | 'ils' | 'inr' | 'isk' | 'jmd' | 'jpy' | 'kes' | 'kgs' | 'khr' | 'kmf' | 'krw' | 'kyd' | 'kzt' | 'lak' | 'lbp' | 'lkr' | 'lrd' | 'lsl' | 'mad' | 'mdl' | 'mga' | 'mkd' | 'mmk' | 'mnt' | 'mop' | 'mur' | 'mvr' | 'mwk' | 'mxn' | 'myr' | 'mzn' | 'nad' | 'ngn' | 'nio' | 'nok' | 'npr' | 'nzd' | 'pab' | 'pen' | 'pgk' | 'php' | 'pkr' | 'pln' | 'pyg' | 'qar' | 'ron' | 'rsd' | 'rub' | 'rwf' | 'sar' | 'sbd' | 'scr' | 'sek' | 'sgd' | 'shp' | 'sle' | 'sos' | 'srd' | 'std' | 'szl' | 'thb' | 'tjs' | 'top' | 'try' | 'ttd' | 'twd' | 'tzs' | 'uah' | 'ugx' | 'usd' | 'uyu' | 'uzs' | 'vnd' | 'vuv' | 'wst' | 'xaf' | 'xcd' | 'xcg' | 'xof' | 'xpf' | 'yer' | 'zar' | 'zmw'
    - `expires_at` string, date-time, nullable
    - `grant_reason` 'adjustment' | 'billing_credit_auto_topup' | 'free' | 'plan' | 'postpaid_forgiven' | 'postpaid_overdraft' | 'postpaid_settlement' | '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
    - `postpaid_charge_amount` integer, nullable: What the postpaid charges costs, in the currency's minor unit.
    - `postpaid_charge_currency` 'aed' | 'afn' | 'all' | 'amd' | 'ang' | 'aoa' | 'ars' | 'aud' | 'awg' | 'azn' | 'bam' | 'bbd' | 'bdt' | 'bif' | 'bmd' | 'bnd' | 'bob' | 'brl' | 'bsd' | 'bwp' | 'byn' | 'bzd' | 'cad' | 'cdf' | 'chf' | 'clp' | 'cny' | 'cop' | 'crc' | 'cve' | 'czk' | 'djf' | 'dkk' | 'dop' | 'dzd' | 'egp' | 'etb' | 'eur' | 'fjd' | 'fkp' | 'gbp' | 'gel' | 'gip' | 'gmd' | 'gnf' | 'gtq' | 'gyd' | 'hkd' | 'hnl' | 'htg' | 'huf' | 'idr' | 'ils' | 'inr' | 'isk' | 'jmd' | 'jpy' | 'kes' | 'kgs' | 'khr' | 'kmf' | 'krw' | 'kyd' | 'kzt' | 'lak' | 'lbp' | 'lkr' | 'lrd' | 'lsl' | 'mad' | 'mdl' | 'mga' | 'mkd' | 'mmk' | 'mnt' | 'mop' | 'mur' | 'mvr' | 'mwk' | 'mxn' | 'myr' | 'mzn' | 'nad' | 'ngn' | 'nio' | 'nok' | 'npr' | 'nzd' | 'pab' | 'pen' | 'pgk' | 'php' | 'pkr' | 'pln' | 'pyg' | 'qar' | 'ron' | 'rsd' | 'rub' | 'rwf' | 'sar' | 'sbd' | 'scr' | 'sek' | 'sgd' | 'shp' | 'sle' | 'sos' | 'srd' | 'std' | 'szl' | 'thb' | 'tjs' | 'top' | 'try' | 'ttd' | 'twd' | 'tzs' | 'uah' | 'ugx' | 'usd' | 'uyu' | 'uzs' | 'vnd' | 'vuv' | 'wst' | 'xaf' | 'xcd' | 'xcg' | 'xof' | 'xpf' | 'yer' | 'zar' | 'zmw'
    - `postpaid_charged_credits` number, double, nullable: Credits consumed past a zero balance in the window still open.
    - `price` BillingPriceResponseData
      - `currency` 'aed' | 'afn' | 'all' | 'amd' | 'ang' | 'aoa' | 'ars' | 'aud' | 'awg' | 'azn' | 'bam' | 'bbd' | 'bdt' | 'bif' | 'bmd' | 'bnd' | 'bob' | 'brl' | 'bsd' | 'bwp' | 'byn' | 'bzd' | 'cad' | 'cdf' | 'chf' | 'clp' | 'cny' | 'cop' | 'crc' | 'cve' | 'czk' | 'djf' | 'dkk' | 'dop' | 'dzd' | 'egp' | 'etb' | 'eur' | 'fjd' | 'fkp' | 'gbp' | 'gel' | 'gip' | 'gmd' | 'gnf' | 'gtq' | 'gyd' | 'hkd' | 'hnl' | 'htg' | 'huf' | 'idr' | 'ils' | 'inr' | 'isk' | 'jmd' | 'jpy' | 'kes' | 'kgs' | 'khr' | 'kmf' | 'krw' | 'kyd' | 'kzt' | 'lak' | 'lbp' | 'lkr' | 'lrd' | 'lsl' | 'mad' | 'mdl' | 'mga' | 'mkd' | 'mmk' | 'mnt' | 'mop' | 'mur' | 'mvr' | 'mwk' | 'mxn' | 'myr' | 'mzn' | 'nad' | 'ngn' | 'nio' | 'nok' | 'npr' | 'nzd' | 'pab' | 'pen' | 'pgk' | 'php' | 'pkr' | 'pln' | 'pyg' | 'qar' | 'ron' | 'rsd' | 'rub' | 'rwf' | 'sar' | 'sbd' | 'scr' | 'sek' | 'sgd' | 'shp' | 'sle' | 'sos' | 'srd' | 'std' | 'szl' | 'thb' | 'tjs' | 'top' | 'try' | 'ttd' | 'twd' | 'tzs' | 'uah' | 'ugx' | 'usd' | 'uyu' | 'uzs' | 'vnd' | 'vuv' | 'wst' | 'xaf' | 'xcd' | 'xcg' | 'xof' | 'xpf' | 'yer' | 'zar' | 'zmw', 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
    - `company_id` string
    - `dir` 'asc' | 'desc'
    - `limit` integer: Page limit (default 100)
    - `offset` integer: Page offset (default 0)
    - `order` 'created_at' | 'expires_at' | 'quantity' | 'quantity_remaining'

## Other responses

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

## Changes

> 230 revisions in range; 1 not diffed.

- **2026-09-17** `b5afdab895bd`: 2 warning
  - added the new `postpaid_forgiven` enum value to the `data/items/grant_reason` response property for the response status `200`
  - added the new `postpaid_settlement` enum value to the `data/items/grant_reason` response property for the response status `200`
- **2026-09-16** `afe97b9908ca`: 1 warning
  - added the new `postpaid_overdraft` enum value to the `data/items/grant_reason` response property for the response status `200`
- **2026-09-11** `5c4619e76dba`: 1 info
  - added the optional property `data/items/credit_bundle_id` to the response with the `200` status
- **2026-09-10** `8615a9997f76`: 3 info
  - added the optional property `data/items/postpaid_charge_amount` to the response with the `200` status
  - added the optional property `data/items/postpaid_charge_currency` to the response with the `200` status
  - added the optional property `data/items/postpaid_charged_credits` to the response with the `200` status
- **2026-08-18** `9057f42cad5d`: 1 breaking
  - the `query` request parameter `company_id` became required

[Operation history](https://skmtc.dev/schematichq/apis/schematic-api/changes/billing/credits/grants/company/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.dev/schematichq/apis/schematic-api/revisions/64cb7e17c236?raw)