---
title: "Create a new credit grant"
method: POST
path: "/v3/openmeter/customers/{customerId}/credits/grants"
tags: ["OpenMeter Customers"]
---

# Create a new credit grant

`POST /v3/openmeter/customers/{customerId}/credits/grants`

**Pre-release Endpoint**
This endpoint is currently in beta and is subject to change.

Create a new credit grant. A credit grant represents an allocation of prepaid
credits to a customer.

## Path parameters

- `customerId` string, required — ULID (Universally Unique Lexicographically Sortable Identifier).

## Request body

- CreateCreditGrantRequest — CreditGrant create request.
  - `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 "_".
  - `funding_method` 'none' | 'invoice' | 'external', required — Funding method of the grant.
  - `currency` string, required — Fiat or custom currency code.
  - `amount` string, required — Granted credit amount.
  - `purchase` object — Present when a funding workflow applies (funding_method is not `none`).
    - `currency` string, required — Currency of the purchase amount.
    - `per_unit_cost_basis` string — Cost basis per credit unit used to calculate the purchase amount. 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. Defaults to 1.0.
    - `availability_policy` 'on_creation' — Controls when credits become available for consumption. Defaults to `on_creation`.
  - `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 applied to the invoice line item.
    - `tax_code` object — Tax code applied to the invoice line item.
      - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier).
  - `filters` CreateCreditGrantFilters — 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.
  - `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.
  - `expires_after` string, ISO8601 — The duration after which the credit grant expires. Defaults to never expiring.
  - `key` string — Idempotency key for the credit grant creation request. When provided, reusing the same key returns an HTTP 409 Conflict instead of creating a duplicate grant, which makes create requests safe to retry.

## Response `201`

CreditGrant created response.

- BillingCreditGrant — A credit grant allocates credits to a customer. Credits are drawn down against charges according to the settlement mode configured on the rate card.
  - `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` string, required — Fiat or custom currency code.
  - `amount` string, required — Granted credit amount.
  - `purchase` object — Present when a funding workflow applies (funding_method is not `none`).
    - `currency` string, required — Currency of the purchase amount.
    - `per_unit_cost_basis` string — Cost basis per credit unit used to calculate the purchase amount. 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. Defaults to 1.0.
    - `amount` string, required — The purchase amount. Calculated from `per_unit_cost_basis` and credit `amount`.
    - `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 applied to the invoice line item.
    - `tax_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.
  - `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. When provided, reusing the same key returns an HTTP 409 Conflict instead of creating a duplicate grant, which makes create requests safe to retry.
  - `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.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `409` — Conflict

---

[API](https://skmtc.net/kong/apis/konnect-api-go-sdk.md) · [All operations](https://skmtc.net/kong/apis/konnect-api-go-sdk/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kong/konnect-api-go-sdk/versions/f920f418f552/schema)