OpenMeter Subscriptions

Change subscription

Changed on

Closes a running subscription and starts a new one according to the specification. Can be used for upgrades, downgrades, and plan changes.

post/v3/openmeter/subscriptions/{subscriptionId}/change

Request

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

Path parameters

subscriptionIdstring required

ULID (Universally Unique Lexicographically Sortable Identifier).

Example:01G65Z755AFWAKHE12NY0CQ9FH

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"
            }
          }
        ]
      }
    ]
  },
  "billing_anchor": "2023-01-01T01:01:01.001Z",
  "timing": "2023-01-01T01:01:01.001Z"
}

Response

The request has succeeded.

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

    • 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

      the request property ////// became optional