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"
}

Changes

Changed in 9 of the 63 revisions of this API.182030

Aug 25, 2026v3bd7fb102768422See the full diff
- ▲
  removed from the //// request property anyOf list
  request-property-any-of-removed
- ▲
  added to the //// response property oneOf list for the response status
  response-property-one-of-added
- ○
  added to the //// request property oneOf list
  request-property-one-of-added
- ○
  removed from the //// response property anyOf list for the response status
  response-property-any-of-removed
Jul 30, 2026v3b4f5102c436d213See the full diff
- ▲
  the //// request property type changed from string to no type
  request-property-type-changed
- ▲
  the //// response's property type changed from string to no type for status
  response-property-type-changed
- ●
  removed from the //// request property allOf list
  request-property-all-of-removed
- ○
  added to the //// request property anyOf list
  request-property-any-of-added
- ○
  removed from the //// response property allOf list for the response status
  response-property-all-of-removed
- ○
  added to the //// response property anyOf list for the response status
  response-property-any-of-added
Jun 30, 2026v316808fbfb5781See the full diff
- ○
  added the optional property to the response with the status
  response-optional-property-added
Jun 29, 2026v3cf64127756eb2See the full diff
- ○
  added the new optional request property
  new-optional-request-property
- ○
  added the optional property to the response with the status
  response-optional-property-added
Jun 29, 2026v3e7e11dd3f78f1See the full diff
- ○
  added the new optional request property
  new-optional-request-property
Jun 28, 2026v3af0122bba0901See the full diff
- ○
  added the non-success response with the status
  response-non-success-status-added
May 26, 2026v366c58f2493158104See the full diff
- ▲
  added to the request property allOf list
  request-property-all-of-added
- ▲
  added to the request property allOf list
  request-property-all-of-added
- ▲
  added to the request property allOf list
  request-property-all-of-added
- ▲
  the request property type changed from object to no type
  request-property-type-changed
- ▲
  the response's property type changed from object to no type for status
  response-property-type-changed
- ▲
  the response's property type changed from object to no type for status
  response-property-type-changed
- ▲
  removed the required property / from the response with the status
  response-required-property-removed
- ▲
  removed the required property / from the response with the status
  response-required-property-removed
- ●
  removed from the request property allOf list
  request-property-all-of-removed
- ●
  removed from the request property allOf list
  request-property-all-of-removed
- ●
  removed the request property /
  request-property-removed
- ●
  removed the request property /
  request-property-removed
- ●
  removed the request property /
  request-property-removed
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ○
  added to the response property allOf list for the response status
  response-property-all-of-added
- ○
  added to the response property allOf list for the response status
  response-property-all-of-added
- ○
  added to the // response property allOf list for the response status
  response-property-all-of-added
- ○
  removed from the // response property allOf list for the response status
  response-property-all-of-removed
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
May 20, 2026v355836d0ad2f52See the full diff
- ○
  added the new optional request property
  new-optional-request-property
- ○
  added the optional property to the response with the status
  response-optional-property-added
May 11, 2026v39d0042cb38156914See the full diff
- ▲
  added the new required request property /
  new-required-request-property
- ▲
  added to the request property allOf list
  request-property-all-of-added
- ▲
  added to the request property allOf list
  request-property-all-of-added
- ▲
  the request property type changed from no type to object
  request-property-type-changed
- ▲
  the response's property type changed from no type to object for status
  response-property-type-changed
- ▲
  the response's property type changed from no type to object for status
  response-property-type-changed
- ●
  removed from the request property allOf list
  request-property-all-of-removed
- ●
  removed from the request property allOf list
  request-property-all-of-removed
- ●
  removed from the request property allOf list
  request-property-all-of-removed
- ●
  removed the request property
  request-property-removed
- ●
  removed the request property
  request-property-removed
- ●
  removed the request property
  request-property-removed
- ●
  removed the optional property from the response with the status
  response-optional-property-removed
- ●
  removed the optional property from the response with the status
  response-optional-property-removed
- ●
  removed the optional property from the response with the status
  response-optional-property-removed
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  removed the non-success response with the status
  response-non-success-status-removed
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added to the // response property allOf list for the response status
  response-property-all-of-added
- ○
  removed from the response property allOf list for the response status
  response-property-all-of-removed
- ○
  removed from the response property allOf list for the response status
  response-property-all-of-removed
- ○
  removed from the // response property allOf list for the response status
  response-property-all-of-removed
- ○
  added the required property / to the response with the status
  response-required-property-added
- ○
  added the required property / to the response with the status
  response-required-property-added
This revision also has 112 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history