Sign in

v61

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

Change subscription

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

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

Example request

{
  "labels": {
    "env": "test"
  },
  "customer": {
    "id": "01G65Z755AFWAKHE12NY0CQ9FH",
    "key": "019ae40f-4258-7f15-9491-842f42a7d6ac"
  },
  "plan": {
    "id": "01G65Z755AFWAKHE12NY0CQ9FH",
    "key": "resource_key"
  },
  "billing_anchor": "2023-01-01T01:01:01.001Z",
  "timing": "2023-01-01T01:01:01.001Z"
}

Response

The request has succeeded.

Example response

{
  "current": {
    "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",
    "customer_id": "01G65Z755AFWAKHE12NY0CQ9FH",
    "plan_id": "01G65Z755AFWAKHE12NY0CQ9FH",
    "billing_anchor": "2023-01-01T01:01:01.001Z"
  },
  "next": {
    "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",
    "customer_id": "01G65Z755AFWAKHE12NY0CQ9FH",
    "plan_id": "01G65Z755AFWAKHE12NY0CQ9FH",
    "billing_anchor": "2023-01-01T01:01:01.001Z"
  }
}