OpenMeter Product Catalog

Create plan

Changed on

Create a new plan.

post/v3/openmeter/plans

Request

  • Base URL: https://global.api.konghq.com
  • URL: https://global.api.konghq.com/v3/openmeter/plans
  • Auth: one of:
    • HTTP bearer
    • HTTP bearer
    • HTTP bearer
    • HTTP bearer

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.

billing_cadencestring ISO8601 required

The billing cadence for subscriptions using this plan.

pro_rating_enabledboolean

Whether pro-rating is enabled for this plan.

settlement_mode'credit_then_invoice' | 'credit_only'

Settlement mode for the plan. Defaults to credit_then_invoice when omitted.

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"
          },
          "currency": "USD",
          "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.

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' required

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"
          },
          "currency": "USD",
          "billing_cadence": "P1Y",
          "tax_config": {
            "code": {
              "id": "01G65Z755AFWAKHE12NY0CQ9FH"
            }
          },
          "entitlement": {
            "usage_period": "P1Y"
          }
        }
      ]
    }
  ],
  "validation_errors": [
    {
      "field": "addons/pro/ratecards/token/featureKey"
    }
  ]
}

Changes

  • 7aab863a6daaRevision changes
    • breaking

      added to the / response property oneOf list for the response status

    • warning

      added the new key_invalid enum value to the ////// response property for the response status

    • warning

      added the new unique enum value to the ////// response property for the response status

  • 68d43091b84dRevision changes
    • breaking

      the response property ///// became optional for the status

    • warning

      added the new 400.00 enum value to the response property for the response status

    • warning

      added the new 403.00 enum value to the response property for the response status

    • info

      added the new optional request property

    • info

      the request property ///// became optional

    • info

      the response property became required for the status

    • info

      the response's property default value credit_then_invoice was removed for the status