--- title: "Edit subscription" method: POST path: "/v3/openmeter/subscriptions/{subscriptionId}/edit" tags: ["OpenMeter Subscriptions"] --- # Edit subscription `POST /v3/openmeter/subscriptions/{subscriptionId}/edit` 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. ## Path parameters - `subscriptionId` string, required — ULID (Universally Unique Lexicographically Sortable Identifier). ## Request body - BillingSubscriptionEdit — Request for editing a running subscription. Applies an ordered batch of customizations to the subscription's phases and items. A later customization observes the state produced by earlier ones. - `customizations` BillingSubscriptionEditOperation[], required — The ordered batch of customizations to apply to the running subscription. - union — A single customization to apply to a running subscription. The `type` field discriminates which operation is performed. - object — Add a new rate card to a phase. Adding an item to the current phase closes the active version of the same item key and appends a new version. - `type` 'add_item', required — Discriminator for the add-item operation. - `phase_key` string, required — The key of the phase to add the item to. - `rate_card` object, required — The rate card describing what the customer gets and pays for the new item. - `name` string, required — Display name of the resource. Between 1 and 256 characters. - `description` string — Optional description of the resource. Maximum 1024 characters. - `labels` Labels — 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 "_". - `key` string, required — A key is a unique string that is used to identify a resource. - `feature` object — The feature associated with the rate card. - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier). - `currency` union — Overrides the containing plan or add-on currency for this rate card. When omitted, the containing resource currency applies. - string — Three-letter [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. Custom three-letter currency codes are also supported for convenience. - string — Custom currency code. It should be a unique code but not conflicting with any existing fiat currency codes. - `billing_cadence` string, ISO8601 — The billing cadence of the rate card. When null, the charge is one-time (non-recurring). Only valid for flat prices. - `price` union, required — The price of the rate card. - object — Free price. - … - object — Flat price. - … - object — Unit price. Charges a fixed rate per billing unit. When UnitConfig is present on the object, billing units are the converted quantities (e.g. GB instead of bytes). - … - object — Graduated tiered price. Each tier's rate applies only to the usage within that tier. Pricing can change as cumulative usage crosses tier boundaries. When UnitConfig is present on the containing resource, tier boundaries (up_to_amount) are expressed in converted billing units. - … - object — Volume tiered price. The maximum quantity within a period determines the per-unit price for all units in that period. When UnitConfig is present on the containing resource, tier boundaries (up_to_amount) are expressed in converted billing units. - … - `unit_config` object — Unit conversion configuration for the rate card. Synthesized on read for plans authored with v1 dynamic or package prices: dynamic prices map to a unit price with a multiply unit config, and package prices map to a unit price with a divide unit config. Accepted on create and update only when the UnitConfig feature is enabled on the deployment; otherwise rejected. - `operation` 'divide' | 'multiply', required — The arithmetic operation to apply to the raw metered quantity. - `conversion_factor` string, required — The factor used in the conversion operation. - For `divide`: `converted = raw / conversionFactor`. - For `multiply`: `converted = raw × conversionFactor`. Must be a positive non-zero value. - `rounding` 'ceiling' | 'floor' | 'half_up' | 'none' — The rounding mode applied to the converted quantity for invoicing. Defaults to none (no rounding). Entitlement checks always use the precise (unrounded) value. - `precision` integer — The number of decimal places to retain after rounding. Only meaningful when rounding is not "none". Defaults to 0 (round to whole numbers). - `display_unit` string — A human-readable label for the converted unit shown on invoices and in the customer portal (e.g., "GB", "hours", "M tokens"). Optional. When omitted, no unit label is rendered. - `payment_term` 'in_advance' | 'in_arrears' — The payment term of the rate card. In advance payment term can only be used for flat prices. - `commitments` object — Spend commitments for this rate card. Only applicable to usage-based prices (unit, graduated, volume). - `minimum_amount` string — The customer is committed to spend at least the amount. - `maximum_amount` string — The customer is limited to spend at most the amount. - `discounts` object — The discounts of the rate card. - `percentage` number — Percentage discount applied to the price (0–100). - `usage` string — Number of usage units granted free before billing starts. Only applies to usage-based lines (not flat fees). Usage is treated as zero until this amount is exhausted. - `tax_config` object — The tax config of the rate card. - `behavior` 'inclusive' | 'exclusive' — Tax behavior. This enum is used to specify whether tax is included in the price or excluded from the price. If not specified, the billing profile is used to determine the tax behavior. If not specified in the billing profile, the provider's default behavior is used. - `code` object — Tax code applied to the invoice line item. - … - `entitlement` union — The entitlement template granted to subscribers of a plan or addon containing this rate card. Requires `feature` to be set. - object — The entitlement template of a metered entitlement. - … - object — The entitlement template of a static entitlement. - … - object — The entitlement template of a boolean entitlement. - … - object — Remove a rate card from a phase. - `type` 'remove_item', required — Discriminator for the remove-item operation. - `phase_key` string, required — The key of the phase to remove the item from. - `item_key` string, required — The key of the item to remove. - object — Add a new phase to the subscription. The phase is created without items; use add-item operations to populate it. - `type` 'add_phase', required — Discriminator for the add-phase operation. - `phase` object, required — The phase to add. - `key` string, required — A locally unique identifier for the phase. - `name` string, required — The name of the phase. - `description` string — An optional description of the phase. - `start_after` string, ISO8601, nullable, required — The ISO-8601 interval after the subscription start at which the phase begins. When null, the phase starts immediately after the subscription starts. - `duration` string, ISO8601 — The intended ISO-8601 duration of the phase. Required unless the phase will be the last phase of the subscription. - object — Remove a phase from the subscription. - `type` 'remove_phase', required — Discriminator for the remove-phase operation. - `phase_key` string, required — The key of the phase to remove. - `shift` 'next' | 'prev', required — The direction to shift surrounding phases to fill the removed phase's span. - object — Extend the duration of a phase, shifting later phases by the same amount. - `type` 'stretch_phase', required — Discriminator for the stretch-phase operation. - `phase_key` string, required — The key of the phase to stretch. - `extend_by` string, ISO8601, required — The ISO-8601 duration to extend the phase by. - object — Discard any scheduled edits on the current phase, reverting it to its previously persisted state. - `type` 'unschedule_edit', required — Discriminator for the unschedule-edit operation. - `timing` union — When the requested changes should take effect. Defaults to immediate. - 'immediate' | 'next_billing_cycle' — Subscription edit timing. When immediate, the requested changes take effect immediately. When next_billing_cycle, the requested changes take effect at the next billing cycle. - string, date-time — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. ## Response `200` Subscription updated response. - BillingSubscription — Subscription. - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier). - `labels` Labels — 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_at` string, date-time, required — An ISO-8601 timestamp representation of entity creation date. - `updated_at` string, date-time, required — An ISO-8601 timestamp representation of entity last update date. - `deleted_at` string, date-time — An ISO-8601 timestamp representation of entity deletion date. - `name` string, required — Display name of the subscription. Defaults to the plan name when the subscription is created from a plan. - `description` string — Optional description of the subscription. - `active_from` string, date-time, required — An ISO-8601 timestamp representation of when the subscription became (or will become) active. - `active_to` string, date-time — An ISO-8601 timestamp representation of when the subscription stops being active. Open-ended when not set. - `customer_id` string, required — The customer ID of the subscription. - `plan_id` string — The plan ID of the subscription. Set if subscription is created from a plan. - `plan` object — The plan the subscription was created from, if any. Includes the plan key and version so clients can resolve the exact plan revision. - `id` string, required — The plan ID (exact revision). - `key` string, required — The plan key. References the plan across versions. - `version` integer, required — The plan version. - `invoice_currency` string, 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. - `cost_basis_pins` BillingSubscriptionCostBasisPin[], required — Cost bases pinned to custom-currency pairs for this subscription. - `custom_currency_id` string, required — The managed custom currency ID. - `invoice_currency` string, required — The fiat currency in which the subscription is invoiced. - `cost_basis_id` string, required — The pinned cost basis resource ID. - `billing_cadence` string, 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). - `pro_rating_config` object — The pro-rating configuration of the subscription. - `enabled` boolean, required — Whether pro-rating is enabled. - `mode` 'no_proration' | 'prorate_prices', required — How pro-rating is calculated when enabled. - `billing_anchor` string, 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. - `current_period` object — The current aligned billing period. Present only when the subscription is active and aligned. - `from` string, date-time, required — The start of the period. The period is inclusive at the start. - `to` string, date-time, required — The end of the period. The period is exclusive at the end. - `phases` BillingSubscriptionPhase[], required — The phases of the subscription in chronological order. A phase groups the rate cards that are in effect for a segment of the subscription's lifetime. - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier). - `name` string, required — Display name of the resource. Between 1 and 256 characters. - `description` string — Optional description of the resource. Maximum 1024 characters. - `labels` Labels — 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_at` string, date-time, required — An ISO-8601 timestamp representation of entity creation date. - `updated_at` string, date-time, required — An ISO-8601 timestamp representation of entity last update date. - `deleted_at` string, date-time — An ISO-8601 timestamp representation of entity deletion date. - `key` string, required — A key is a unique string that is used to identify a resource. - `active_from` string, date-time, required — An ISO-8601 timestamp representation of when the phase becomes active. - `active_to` string, date-time — An ISO-8601 timestamp representation of when the phase stops being active. Open-ended for the last phase. - `items` BillingSubscriptionItem[], required — The rate cards in effect for this phase, resolved to the version active at the queried time (the currently active version for the current phase, the first version for future phases, and the last version for past phases). - `id` string, required — The unique identifier of the subscription item instance. - `active_from` string, date-time, required — An ISO-8601 timestamp representation of when this item version becomes active. - `active_to` string, date-time — An ISO-8601 timestamp representation of when this item version stops being active. - `rate_card` object, required — The rate card describing what the customer gets and pays for this item. - `name` string, required — Display name of the resource. Between 1 and 256 characters. - `description` string — Optional description of the resource. Maximum 1024 characters. - `labels` Labels — 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 "_". - `key` string, required — A key is a unique string that is used to identify a resource. - `feature` object — The feature associated with the rate card. - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier). - `currency` union — Overrides the containing plan or add-on currency for this rate card. When omitted, the containing resource currency applies. - string — Three-letter [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. Custom three-letter currency codes are also supported for convenience. - string — Custom currency code. It should be a unique code but not conflicting with any existing fiat currency codes. - `billing_cadence` string, ISO8601 — The billing cadence of the rate card. When null, the charge is one-time (non-recurring). Only valid for flat prices. - `price` union, required — The price of the rate card. - object — Free price. - `type` 'free', required — The type of the price. - object — Flat price. - `type` 'flat', required — The type of the price. - `amount` string, required — The amount of the flat price. - object — Unit price. Charges a fixed rate per billing unit. When UnitConfig is present on the object, billing units are the converted quantities (e.g. GB instead of bytes). - `type` 'unit', required — The type of the price. - `amount` string, required — The amount of the unit price. - object — Graduated tiered price. Each tier's rate applies only to the usage within that tier. Pricing can change as cumulative usage crosses tier boundaries. When UnitConfig is present on the containing resource, tier boundaries (up_to_amount) are expressed in converted billing units. - `type` 'graduated', required — The type of the price. - `tiers` BillingPriceTier[], required — The tiers of the graduated price. At least one tier is required. - … - object — Volume tiered price. The maximum quantity within a period determines the per-unit price for all units in that period. When UnitConfig is present on the containing resource, tier boundaries (up_to_amount) are expressed in converted billing units. - `type` 'volume', required — The type of the price. - `tiers` BillingPriceTier[], required — The tiers of the volume price. At least one tier is required. - … - `unit_config` object — Unit conversion configuration for the rate card. Synthesized on read for plans authored with v1 dynamic or package prices: dynamic prices map to a unit price with a multiply unit config, and package prices map to a unit price with a divide unit config. Accepted on create and update only when the UnitConfig feature is enabled on the deployment; otherwise rejected. - `operation` 'divide' | 'multiply', required — The arithmetic operation to apply to the raw metered quantity. - `conversion_factor` string, required — The factor used in the conversion operation. - For `divide`: `converted = raw / conversionFactor`. - For `multiply`: `converted = raw × conversionFactor`. Must be a positive non-zero value. - `rounding` 'ceiling' | 'floor' | 'half_up' | 'none' — The rounding mode applied to the converted quantity for invoicing. Defaults to none (no rounding). Entitlement checks always use the precise (unrounded) value. - `precision` integer — The number of decimal places to retain after rounding. Only meaningful when rounding is not "none". Defaults to 0 (round to whole numbers). - `display_unit` string — A human-readable label for the converted unit shown on invoices and in the customer portal (e.g., "GB", "hours", "M tokens"). Optional. When omitted, no unit label is rendered. - `payment_term` 'in_advance' | 'in_arrears' — The payment term of the rate card. In advance payment term can only be used for flat prices. - `commitments` object — Spend commitments for this rate card. Only applicable to usage-based prices (unit, graduated, volume). - `minimum_amount` string — The customer is committed to spend at least the amount. - `maximum_amount` string — The customer is limited to spend at most the amount. - `discounts` object — The discounts of the rate card. - `percentage` number — Percentage discount applied to the price (0–100). - `usage` string — Number of usage units granted free before billing starts. Only applies to usage-based lines (not flat fees). Usage is treated as zero until this amount is exhausted. - `tax_config` object — The tax config of the rate card. - `behavior` 'inclusive' | 'exclusive' — Tax behavior. This enum is used to specify whether tax is included in the price or excluded from the price. If not specified, the billing profile is used to determine the tax behavior. If not specified in the billing profile, the provider's default behavior is used. - `code` object — Tax code applied to the invoice line item. - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier). - `entitlement` union — The entitlement template granted to subscribers of a plan or addon containing this rate card. Requires `feature` to be set. - object — The entitlement template of a metered entitlement. - `type` 'metered', required — The type of the entitlement template. - `is_soft_limit` boolean — If soft limit is true, the subject can use the feature even if the entitlement is exhausted; access remains granted. - `limit` number, double — The amount of usage granted each usage period, in the feature's unit. Usage is counted against this allowance and the balance resets every usage period. When `is_soft_limit` is true the subject keeps access after the limit is reached; otherwise access is denied once the allowance is exhausted. - `usage_period` string, ISO8601 — The reset interval of the metered entitlement in ISO8601 format. Defaults to the billing cadence of the rate card. - object — The entitlement template of a static entitlement. - `type` 'static', required — The type of the entitlement template. - `config` unknown, required - object — The entitlement template of a boolean entitlement. - `type` 'boolean', required — The type of the entitlement template. ## Other responses - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `409` — Conflict ## Changes - **2026-09-25** `68d43091b84d` — 1 breaking, 4 warning, 1 info - the response property `phases/items/items/items/rate_card/tax_config/code` became optional for the status `200` - added the new `400.00` enum value to the `status` response property for the response status `400` - added the new `403.00` enum value to the `status` response property for the response status `403` - added the new `404.00` enum value to the `status` response property for the response status `404` - …2 more - **2026-09-18** `f324fb7610e4` — 1 info - endpoint added [Change history](https://skmtc.dev/kong/apis/konnect-api-go-sdk/changes/v3/openmeter/subscriptions/:subscriptionId/edit/post.md) --- [API](https://skmtc.dev/kong/apis/konnect-api-go-sdk.md) · [All operations](https://skmtc.dev/kong/apis/konnect-api-go-sdk/llms.txt) · [OpenAPI document](https://skmtc.dev/kong/apis/konnect-api-go-sdk/revisions/de79e1192f11?raw)