Sign in
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"
  }
}

Changes

Changed in 3 of the 75 revisions of this API.8

  • a2e95e9f6c803See the full diff
    • ○

      added the new optional request property settlement_mode

      new-optional-request-property

    • ○

      added the optional property current/settlement_mode to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property next/settlement_mode to the response with the 200 status

      response-optional-property-added

    This revision also has 23 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 86981188d9114See the full diff
    • ○

      the response property current/created_at became required for the status 200

      response-property-became-required

    • ○

      the response property current/updated_at became required for the status 200

      response-property-became-required

    • ○

      the response property next/created_at became required for the status 200

      response-property-became-required

    • ○

      the response property next/updated_at became required for the status 200

      response-property-became-required

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • d5eb242b4c931See the full diff
    • ○

      endpoint added

      endpoint-added

    This revision also has 6 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog