v61

latestOpenAPI 3.1.0Apache 2.0raw.githubusercontent.com2026-08-018131,3812.6 MB

OpenMeter Product Catalog

Create plan

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

Create a new plan.

post/v3/openmeter/plans

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 "_".

keystring required

A key is a semi-unique string that is used to identify the plan. It is used to reference the latest active version of the plan and is unique with the version number.

currencystring required

The currency code of the plan.

billing_cadencestring ISO8601 required

The billing cadence for subscriptions using this plan.

pro_rating_enabledboolean

Whether pro-rating is enabled for this plan.

Example request

{
  "labels": {
    "env": "test"
  },
  "key": "resource_key",
  "currency": "USD",
  "billing_cadence": "P1Y",
  "phases": [
    {
      "labels": {
        "env": "test"
      },
      "key": "resource_key",
      "duration": "P1Y",
      "rate_cards": [
        {
          "labels": {
            "env": "test"
          },
          "key": "resource_key",
          "feature": {
            "id": "01G65Z755AFWAKHE12NY0CQ9FH"
          },
          "billing_cadence": "P1Y",
          "tax_config": {
            "code": {
              "id": "01G65Z755AFWAKHE12NY0CQ9FH"
            }
          },
          "entitlement": {
            "usage_period": "P1Y"
          }
        }
      ]
    }
  ]
}

Response

Plan 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

An ISO-8601 timestamp representation of entity creation date.

updated_atstring date-time required

An ISO-8601 timestamp representation of entity last update date.

deleted_atstring date-time

An ISO-8601 timestamp representation of entity deletion date.

keystring required

A key is a semi-unique string that is used to identify the plan. It is used to reference the latest active version of the plan and is unique with the version number.

versioninteger required

Plans are versioned to allow you to make changes without affecting running subscriptions.

currencystring required

The currency code of the plan.

billing_cadencestring ISO8601 required

The billing cadence for subscriptions using this plan.

pro_rating_enabledboolean

Whether pro-rating is enabled for this plan.

effective_fromstring date-time

The date and time when the plan becomes active. When not specified, the plan is in draft status.

effective_tostring date-time

A scheduled date and time when the plan becomes archived. When not specified, the plan is in active status indefinitely.

status'draft' | 'active' | 'archived' | 'scheduled' required

The status of the plan. Computed based on the effective start and end dates:

draft: effective_from is not set.
scheduled: now < effective_from.
active: effective_from <= now and (effective_to is not set or now < effective_to).
archived: effective_to <= now.

settlement_mode'credit_then_invoice' | 'credit_only'

Settlement mode for plan.

Values:

credit_then_invoice: Credits are applied first, then any remainder is invoiced.
credit_only: Usage is settled exclusively against credits.

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",
  "key": "resource_key",
  "currency": "USD",
  "billing_cadence": "P1Y",
  "effective_from": "2023-01-01T01:01:01.001Z",
  "effective_to": "2023-01-01T01:01:01.001Z",
  "phases": [
    {
      "labels": {
        "env": "test"
      },
      "key": "resource_key",
      "duration": "P1Y",
      "rate_cards": [
        {
          "labels": {
            "env": "test"
          },
          "key": "resource_key",
          "feature": {
            "id": "01G65Z755AFWAKHE12NY0CQ9FH"
          },
          "billing_cadence": "P1Y",
          "tax_config": {
            "code": {
              "id": "01G65Z755AFWAKHE12NY0CQ9FH"
            }
          },
          "entitlement": {
            "usage_period": "P1Y"
          }
        }
      ]
    }
  ],
  "validation_errors": [
    {
      "field": "addons/pro/ratecards/token/featureKey"
    }
  ]
}