Sign in
OpenMeter Subscriptions

Edit subscription

Edits a running subscription by applying an ordered batch of customizations (adding or removing items, adding, removing, or stretching phases, or unscheduling a pending edit). The changes may take effect immediately or at the next billing cycle. Subscriptions that have add-ons cannot be edited.

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

Path parameters

subscriptionIdstring required

ULID (Universally Unique Lexicographically Sortable Identifier).

Example:01G65Z755AFWAKHE12NY0CQ9FH

Request body

Example request

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

Response

Subscription updated 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

Changed in 2 of the 83 revisions of this API.142

  • 68d43091b84d141See the full diff
    • ▲

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

      response-property-became-optional

    • ●

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

      response-property-enum-value-added

    • ●

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

      response-property-enum-value-added

    • ●

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

      response-property-enum-value-added

    • ●

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

      response-property-enum-value-added

    • ○

      the request property //////// became optional

      request-property-became-optional

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

  • f324fb7610e41See the full diff
    • ○

      endpoint added

      endpoint-added

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