OpenMeter Subscriptions

Create subscription

Changed on
post/v3/openmeter/subscriptions

Request

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

Request body

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

settlement_mode'credit_then_invoice' | 'credit_only'

Settlement mode for billing.

Values:

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

The key of the phase to start the subscription in. If not provided, the subscription starts in the first phase of the plan.

Only applies when creating from a published plan; custom plans define their own phases inline.

billing_anchorstring date-time

A billing anchor is the fixed point in time that determines the subscription's recurring billing cycle. It affects when charges occur and how prorations are calculated. Common anchors:

  • Calendar month (1st of each month): 2025-01-01T00:00:00Z
  • Subscription anniversary (day customer signed up)
  • Custom date (customer-specified day)

If not provided, the subscription will be created with the subscription's creation time as the billing anchor.

cost_basis_mode'dynamic' | 'pinned'

Controls how custom-currency cost bases are selected for the subscription.

Example request

{
  "labels": {
    "env": "test"
  },
  "customer": {
    "id": "01G65Z755AFWAKHE12NY0CQ9FH",
    "key": "019ae40f-4258-7f15-9491-842f42a7d6ac"
  },
  "plan": {
    "id": "01G65Z755AFWAKHE12NY0CQ9FH",
    "key": "resource_key"
  },
  "custom_plan": {
    "labels": {
      "env": "test"
    },
    "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"
            }
          }
        ]
      }
    ]
  },
  "timing": "2023-01-01T01:01:01.001Z",
  "billing_anchor": "2023-01-01T01:01:01.001Z"
}

Response

Subscription created response.

idstring required

ULID (Universally Unique Lexicographically Sortable Identifier).

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.

namestring required

Display name of the subscription. Defaults to the plan name when the subscription is created from a plan.

descriptionstring

Optional description of the subscription.

active_fromstring date-time required

An ISO-8601 timestamp representation of when the subscription became (or will become) active.

active_tostring date-time

An ISO-8601 timestamp representation of when the subscription stops being active. Open-ended when not set.

customer_idstring required

The customer ID of the subscription.

plan_idstring

The plan ID of the subscription. Set if subscription is created from a plan.

invoice_currencystring required

The fiat currency in which the subscription is invoiced.

cost_basis_mode'dynamic' | 'pinned' required

Controls whether custom-currency cost bases are resolved dynamically or pinned when their currency pair is introduced to the subscription.

billing_cadencestring ISO8601 required

The billing cadence of the subscription in ISO-8601 duration format. Defines how often the customer is billed. Examples: P1M (monthly), P3M (quarterly), P1Y (annually).

billing_anchorstring date-time required

A billing anchor is the fixed point in time that determines the subscription's recurring billing cycle. It affects when charges occur and how prorations are calculated. Common anchors:

  • Calendar month (1st of each month): 2025-01-01T00:00:00Z
  • Subscription anniversary (day customer signed up)
  • Custom date (customer-specified day)
status'active' | 'inactive' | 'canceled' | 'scheduled' required

The status of the subscription.

settlement_mode'credit_then_invoice' | 'credit_only'

Settlement mode for billing.

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",
  "active_from": "2023-01-01T01:01:01.001Z",
  "active_to": "2023-01-01T01:01:01.001Z",
  "customer_id": "01G65Z755AFWAKHE12NY0CQ9FH",
  "plan_id": "01G65Z755AFWAKHE12NY0CQ9FH",
  "plan": {
    "id": "01G65Z755AFWAKHE12NY0CQ9FH",
    "key": "resource_key"
  },
  "invoice_currency": "USD",
  "cost_basis_pins": [
    {
      "custom_currency_id": "01G65Z755AFWAKHE12NY0CQ9FH",
      "invoice_currency": "USD",
      "cost_basis_id": "01G65Z755AFWAKHE12NY0CQ9FH"
    }
  ],
  "billing_cadence": "P1Y",
  "billing_anchor": "2023-01-01T01:01:01.001Z",
  "current_period": {
    "from": "2023-01-01T01:01:01.001Z",
    "to": "2023-01-01T01:01:01.001Z"
  },
  "phases": [
    {
      "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",
      "active_from": "2023-01-01T01:01:01.001Z",
      "active_to": "2023-01-01T01:01:01.001Z",
      "items": [
        {
          "id": "01G65Z755AFWAKHE12NY0CQ9FH",
          "active_from": "2023-01-01T01:01:01.001Z",
          "active_to": "2023-01-01T01:01:01.001Z",
          "rate_card": {
            "labels": {
              "env": "test"
            },
            "key": "resource_key",
            "feature": {
              "id": "01G65Z755AFWAKHE12NY0CQ9FH"
            },
            "currency": "USD",
            "billing_cadence": "P1Y",
            "tax_config": {
              "code": {
                "id": "01G65Z755AFWAKHE12NY0CQ9FH"
              }
            },
            "entitlement": {
              "usage_period": "P1Y"
            }
          }
        }
      ]
    }
  ]
}

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

    • warning

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

    • warning

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

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      the request property ////// became optional