v52

latestOpenAPI 3.0.0raw.githubusercontent.com2026-08-03101355448.4 KB

OpenMeter Customers

Create a new credit grant

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

post/openmeter/customers/{customerId}/credits/grants

Path parameters

customerIdstring required

ULID (Universally Unique Lexicographically Sortable Identifier).

Example:01G65Z755AFWAKHE12NY0CQ9FH

Request body

namestring required

Display name of the resource.

Between 1 and 256 characters.

descriptionstring

Optional description of the resource.

Maximum 1024 characters.

labelsLabels

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

The funding method describes how the grant is funded.

none: No funding workflow applies, for example promotional grants
invoice: The grant is funded by an in-system invoice flow
external: The grant is funded outside the system (e.g., wire transfer, external invoice, or manual reconciliation)

amountstring required

Numeric represents an arbitrary precision number.

priorityinteger

Draw-down priority of the grant. Lower values have higher priority.

effective_atstring date-time

RFC3339 formatted date-time string in UTC.

expires_afterstring ISO8601

ISO 8601 Duration string.

keystring

ExternalResourceKey is a unique string that is used to identify a resource in an external system.

Example request

{
  "labels": {
    "env": "test"
  },
  "currency": "USD",
  "purchase": {
    "currency": "USD"
  },
  "tax_config": {
    "tax_code": {
      "id": "01G65Z755AFWAKHE12NY0CQ9FH"
    }
  },
  "filters": {
    "features": [
      "input_tokens",
      "output_tokens"
    ]
  },
  "effective_at": "2023-01-01T01:01:01.001Z",
  "expires_after": "P1Y",
  "key": "019ae40f-4258-7f15-9491-842f42a7d6ac"
}

Response

CreditGrant created response.

idstring required

ULID (Universally Unique Lexicographically Sortable Identifier).

namestring required

Display name of the resource.

Between 1 and 256 characters.

descriptionstring

Optional description of the resource.

Maximum 1024 characters.

labelsLabels

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_atstring date-time required

RFC3339 formatted date-time string in UTC.

updated_atstring date-time required

RFC3339 formatted date-time string in UTC.

deleted_atstring date-time

RFC3339 formatted date-time string in UTC.

funding_method'none' | 'invoice' | 'external' required

The funding method describes how the grant is funded.

none: No funding workflow applies, for example promotional grants
invoice: The grant is funded by an in-system invoice flow
external: The grant is funded outside the system (e.g., wire transfer, external invoice, or manual reconciliation)

amountstring required

Numeric represents an arbitrary precision number.

priorityinteger

Draw-down priority of the grant. Lower values have higher priority.

effective_atstring date-time

RFC3339 formatted date-time string in UTC.

keystring

ExternalResourceKey is a unique string that is used to identify a resource in an external system.

expires_atstring date-time

RFC3339 formatted date-time string in UTC.

voided_atstring date-time

RFC3339 formatted date-time string in UTC.

status'pending' | 'active' | 'expired' | 'voided' required

Credit grant lifecycle status.

pending: The credit block has been created but is not yet valid. (effective_at is in the future or availability_policy is not met)
active: The credit block is currently valid and eligible for consumption. (effective_at is in the past, expires_at is in the future and availability_policy is met)
expired: The credit block expired with remaining unused balance, expires_at time has passed.
voided: The credit block was voided. Remaining balance is forfeited.

Example response

{
  "id": "01G65Z755AFWAKHE12NY0CQ9FH",
  "labels": {
    "env": "test"
  },
  "created_at": "2023-01-01T01:01:01.001Z",
  "updated_at": "2023-01-01T01:01:01.001Z",
  "deleted_at": "2023-01-01T01:01:01.001Z",
  "currency": "USD",
  "purchase": {
    "currency": "USD"
  },
  "tax_config": {
    "tax_code": {
      "id": "01G65Z755AFWAKHE12NY0CQ9FH"
    }
  },
  "invoice": {
    "id": "01G65Z755AFWAKHE12NY0CQ9FH",
    "line": {
      "id": "01G65Z755AFWAKHE12NY0CQ9FH"
    }
  },
  "filters": {
    "features": [
      "input_tokens",
      "output_tokens"
    ]
  },
  "effective_at": "2023-01-01T01:01:01.001Z",
  "key": "019ae40f-4258-7f15-9491-842f42a7d6ac",
  "expires_at": "2023-01-01T01:01:01.001Z",
  "voided_at": "2023-01-01T01:01:01.001Z"
}