--- title: "List credit grants" method: GET path: "/v3/openmeter/customers/{customerId}/credits/grants" tags: ["OpenMeter Customers"] --- # List credit grants `GET /v3/openmeter/customers/{customerId}/credits/grants` ## Request - Base URL: `https://global.api.konghq.com` - URL: `https://global.api.konghq.com/v3/openmeter/customers/{customerId}/credits/grants` - Auth: one of: - HTTP bearer - HTTP bearer - HTTP bearer - HTTP bearer **Pre-release Endpoint** This endpoint is currently in beta and is subject to change. List credit grants. ## Path parameters - `customerId` string, required: ULID (Universally Unique Lexicographically Sortable Identifier). ## Query parameters - `page` object - `size` integer: The number of items to include per page. - `number` integer: The page number. - `filter` ListCreditGrantsParamsFilter: Filter options for listing credit grants. - `status` 'pending' | 'active' | 'expired' | 'voided': Filter credit grants by status. - `currency` string: Filter credit grants by currency. - `key` object: Filter credit grants by key. - `eq` string - `contains` string, required - `ocontains` string, required - `oeq` string, required - `neq` string, required ## Response `200` Page paginated response. - CreditGrantPagePaginatedResponse: Page paginated response. - `data` BillingCreditGrant[], required - `id` string, required: ULID (Universally Unique Lexicographically Sortable Identifier). - `name` string, required: Display name of the resource. Between 1 and 256 characters. - `description` string: Optional description of the resource. Maximum 1024 characters. - `labels` Labels: Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types. Keys must be of length 1-63 characters, and cannot start with "kong", "konnect", "mesh", "kic", or "_". - `created_at` string, date-time, required: An ISO-8601 timestamp representation of entity creation date. - `updated_at` string, date-time, required: An ISO-8601 timestamp representation of entity last update date. - `deleted_at` string, date-time: An ISO-8601 timestamp representation of entity deletion date. - `funding_method` 'none' | 'invoice' | 'external', required: Funding method of the grant. - `currency` union, required: The fiat or custom currency of the granted credits. Funded custom-currency grants must define `purchase.cost_basis` to settle in a fiat currency. - string: Three-letter [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. Custom three-letter currency codes are also supported for convenience. - string: Custom currency code. It should be a unique code but not conflicting with any existing fiat currency codes. - `amount` string, required: Granted credit amount. - `purchase` object: Present when a funding workflow applies (funding_method is not `none`). - `currency` string, required: Fiat currency the purchase is settled in. Must equal the grant `currency` for fiat grants and `cost_basis.fiat_currency` for custom-currency grants. - `per_unit_cost_basis` string: Fiat cost basis per credit unit of a fiat-currency grant. If `per_unit_cost_basis` is 0.50 and credit amount is $100.00, the total charge is $50.00. The value must be greater than 0. If the cost basis is 0, use `funding_method=none` instead. Only applies to fiat grants and cannot be combined with `cost_basis`. Defaults to 1.0 when neither is provided. - `resolved_cost_basis` object: The rate the purchase is settled at in the purchase `currency`. Present once the cost basis is resolved. - `fiat_currency` string, required: The fiat currency the charge amount is converted into for invoicing. - `rate` string, required: Fiat amount per one unit of the custom currency. - `cost_basis_id` string: ID of the custom currency's cost basis resource the rate was taken from. Absent for manual cost bases. - `resolved_at` string, date-time, required: When the rate was resolved. - `amount` string: The purchase amount, calculated from the resolved cost basis and credit `amount`. Present once the cost basis is resolved. - `availability_policy` 'on_creation': Controls when credits become available for consumption. Defaults to `on_creation`. - `settlement_status` 'pending' | 'authorized' | 'settled': Current payment settlement status. - `tax_config` object: Tax configuration for the grant. For `invoice` and `external` funding methods, tax configuration should be provided to ensure correct revenue recognition. When not provided, the default credit grant tax code is applied, if that's not set the global default taxcode is used. - `behavior` 'inclusive' | 'exclusive': Tax behavior. This enum is used to specify whether tax is included in the price or excluded from the price. If not specified, the billing profile is used to determine the tax behavior. If not specified in the billing profile, the provider's default behavior is used. - `code` object: Tax code applied to the invoice line item. - `id` string, required: ULID (Universally Unique Lexicographically Sortable Identifier). - `invoice` object: Available when `funding_method` is `invoice`. - `id` string: Identifier of the invoice associated with the grant. - `line` object: Identifier of the invoice line associated with the grant. - `id` string, required: ULID (Universally Unique Lexicographically Sortable Identifier). - `filters` BillingCreditGrantFilters: Filters for the credit grant. - `features` ResourceKey[]: Limit the credit grant to specific features. If no features are specified, the credit grant can be used for any feature. - `plans` BillingCreditGrantPlanFilter[]: Limit credits to charges from these plans. Entries are alternatives; when features are also specified, both dimensions must match. Omission or an empty list leaves plans unrestricted. - `key` string, required: The plan key in the customer's namespace. - `version` object: Omission matches all versions, including future versions. - `eq` integer: Match this exact version. - `oeq` integer[]: Match one of these versions. - `gte` integer: Match this version and later versions. - `lte` integer: Match this version and earlier versions. - `priority` integer: Draw-down priority of the grant. Lower values have higher priority. - `effective_at` string, date-time: The timestamp when the credit grant becomes effective. Defaults to the current date and time. - `key` string: Idempotency key for the credit grant creation request. Unique per customer: reusing the same key for the same customer returns an HTTP 409 Conflict instead of creating a duplicate grant, which makes create requests safe to retry. The same key may be reused across different customers. - `expires_at` string, date-time: The timestamp when the credit grant expires. Calculated from the grant effective time and `expires_after` if provided. - `voided_at` string, date-time: Timestamp when the grant was voided. - `status` 'pending' | 'active' | 'expired' | 'voided', required: Current lifecycle status of the grant. - `validation_issues` BillingValidationIssue[]: Validation issues found while processing the credit grant. Present only when there are one or more validation findings. An empty list is omitted. - `code` string, required: Machine-readable error code. - `message` string, required: Human-readable description of the error. - `attributes` object: Additional structured context. - `severity` 'critical' | 'warning', required: Severity of the validation issue. - `field` string: JSON path to the field that caused the validation issue, if applicable. - `component` string: Component that reported the validation issue, if applicable. - `meta` PaginatedMeta, required: returns the pagination information - `page` PageMeta, required: Contains pagination query parameters and the total number of objects returned. - `number` number, required - `size` number, required - `total` number, required ## Other responses - `400`: Bad Request - `401`: Unauthorized - `403`: Forbidden - `404`: Not Found ## Changes - **2026-10-15** `7aab863a6daa`: 1 breaking, 2 warning - added `#/components/schemas/InvalidParameterMinimumTime, #/components/schemas/InvalidParameterMaximumTime` to the `invalid_parameters/items/` response property `oneOf` list for the response status `400` - added the new `key_invalid` enum value to the `invalid_parameters/items/oneOf[#/components/schemas/InvalidParameterStandard]/rule` response property for the response status `400` - added the new `unique` enum value to the `invalid_parameters/items/oneOf[#/components/schemas/InvalidParameterStandard]/rule` response property for the response status `400` - **2026-10-05** `1efb48111817`: 1 info - added the optional property `data/items/filters/plans` to the response with the `200` status - **2026-09-25** `68d43091b84d`: 4 warning, 2 info - removed the optional property `data/items/tax_config/tax_code` from the response with the `200` status - added the new `400.00` enum value to the `status` response property for the response status `400` - added the new `403.00` enum value to the `status` response property for the response status `403` - added the new `404.00` enum value to the `status` response property for the response status `404` - …2 more - …earlier changes not shown [Operation history](https://skmtc.dev/kong/apis/konnect-api-go-sdk/changes/v3/openmeter/customers/:customerId/credits/grants/get.md) --- [API](https://skmtc.dev/kong/apis/konnect-api-go-sdk.md) · [All operations](https://skmtc.dev/kong/apis/konnect-api-go-sdk/llms.txt) · [OpenAPI document](https://skmtc.dev/kong/apis/konnect-api-go-sdk/revisions/7aab863a6daa?raw)