--- title: "Update plan" method: PUT path: "/v3/openmeter/plans/{planId}" tags: ["OpenMeter Product Catalog"] --- # Update plan `PUT /v3/openmeter/plans/{planId}` **Pre-release Endpoint** This endpoint is currently in beta and is subject to change. Update a plan by id. ## Path parameters - `planId` string, required — ULID (Universally Unique Lexicographically Sortable Identifier). ## Request body - UpsertPlanRequest — Plan upsert request. - `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 "_". - `pro_rating_enabled` boolean — Whether pro-rating is enabled for this plan. - `phases` BillingPlanPhase[], required — The plan phases define the pricing ramp for a subscription. A phase switch occurs only at the end of a billing period. At least one phase is required. - `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. - `duration` string, ISO8601 — The duration of the phase. When not specified, the phase runs indefinitely. Only the last phase may omit the duration. - `rate_cards` BillingRateCard[], required — The rate cards of the plan. - `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). - `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 rate card, 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 rate card, 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. - `up_to_amount` string — Up to and including this quantity will be contained in the tier. If undefined, the tier is open-ended (the last tier). - `flat_price` object — The flat price component of the tier. Charged once when the tier is entered. - … - `unit_price` object — The unit price component of the tier. Charged per billing unit within the tier. - … - 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 rate card, 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. - `up_to_amount` string — Up to and including this quantity will be contained in the tier. If undefined, the tier is open-ended (the last tier). - `flat_price` object — The flat price component of the tier. Charged once when the tier is entered. - … - `unit_price` object — The unit price component of the tier. Charged per billing unit within the tier. - … - `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. - `code` TaxCodeReference, required — TaxCode reference. - `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. ## Response `200` Plan upsert response. - BillingPlan — Plans provide a template for subscriptions. - `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 semi-unique string that is used to identify the plan. It is used to reference the latest `active` version of the plan and is unique with the version number. - `version` integer, required — Plans are versioned to allow you to make changes without affecting running subscriptions. - `currency` string, required — The currency code of the plan. - `billing_cadence` string, ISO8601, required — The billing cadence for subscriptions using this plan. - `pro_rating_enabled` boolean — Whether pro-rating is enabled for this plan. - `effective_from` string, date-time — The date and time when the plan becomes `active`. When not specified, the plan is in `draft` status. - `effective_to` string, date-time — A scheduled date and time when the plan becomes `archived`. When not specified, the plan is in `active` status indefinitely. - `status` 'draft' | 'active' | 'archived' | 'scheduled', required — The status of the plan. Computed based on the effective start and end dates: - `draft`: `effective_from` is not set. - `scheduled`: `now < effective_from`. - `active`: `effective_from <= now` and (`effective_to` is not set or `now < effective_to`). - `archived`: `effective_to <= now`. - `phases` BillingPlanPhase[], required — The plan phases define the pricing ramp for a subscription. A phase switch occurs only at the end of a billing period. At least one phase is required. - `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. - `duration` string, ISO8601 — The duration of the phase. When not specified, the phase runs indefinitely. Only the last phase may omit the duration. - `rate_cards` BillingRateCard[], required — The rate cards of the plan. - `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). - `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 rate card, 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 rate card, 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. - `up_to_amount` string — Up to and including this quantity will be contained in the tier. If undefined, the tier is open-ended (the last tier). - `flat_price` object — The flat price component of the tier. Charged once when the tier is entered. - … - `unit_price` object — The unit price component of the tier. Charged per billing unit within the tier. - … - 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 rate card, 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. - `up_to_amount` string — Up to and including this quantity will be contained in the tier. If undefined, the tier is open-ended (the last tier). - `flat_price` object — The flat price component of the tier. Charged once when the tier is entered. - … - `unit_price` object — The unit price component of the tier. Charged per billing unit within the tier. - … - `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. - `code` TaxCodeReference, required — TaxCode reference. - `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. - `settlement_mode` 'credit_then_invoice' | 'credit_only' — Settlement mode for plan. Values: - `credit_then_invoice`: Credits are applied first, then any remainder is invoiced. - `credit_only`: Usage is settled exclusively against credits. - `validation_errors` ProductCatalogValidationError[] — List of validation errors in `draft` state that prevent the plan from being published. - `code` string, required — Machine-readable error code. - `message` string, required — Human-readable description of the error. - `attributes` object — Additional structured context. - `field` string, required — The path to the field. ## Other responses - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `410` — Gone --- [API](https://skmtc.net/kong/apis/konnect-api-go-sdk.md) · [All operations](https://skmtc.net/kong/apis/konnect-api-go-sdk/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kong/konnect-api-go-sdk/versions/0261aef4b1e2/schema)