--- title: "Update plan" method: PUT path: "/openmeter/plans/{planId}" tags: ["OpenMeter Product Catalog"] --- # Update plan `PUT /openmeter/plans/{planId}` 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 — [ISO 8601 Duration](https://docs.digi.com/resources/documentation/digidocs/90001488-13/reference/r_iso_8601_duration_format.htm) string. - `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` FeatureReferenceItem — Feature reference. - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier). - `billing_cadence` string, ISO8601 — [ISO 8601 Duration](https://docs.digi.com/resources/documentation/digidocs/90001488-13/reference/r_iso_8601_duration_format.htm) string. - `price` union, required — Price. - 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 — Numeric represents an arbitrary precision number. - 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 — Numeric represents an arbitrary precision number. - 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 — Numeric represents an arbitrary precision number. - `flat_price` BillingPriceFlat — Flat price. - … - `unit_price` BillingPriceUnit — 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). - … - 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 — Numeric represents an arbitrary precision number. - `flat_price` BillingPriceFlat — Flat price. - … - `unit_price` BillingPriceUnit — 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). - … - `payment_term` 'in_advance' | 'in_arrears' — The payment term of a flat price. - `commitments` BillingSpendCommitments — Spend commitments for a rate card. The customer is committed to spend at least the minimum amount and at most the maximum amount. - `minimum_amount` string — Numeric represents an arbitrary precision number. - `maximum_amount` string — Numeric represents an arbitrary precision number. - `discounts` BillingRateCardDiscounts — Discount configuration for a rate card. - `percentage` number — Percentage discount applied to the price (0–100). - `usage` string — Numeric represents an arbitrary precision number. - `tax_config` BillingRateCardTaxConfig — 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` TaxCodeReferenceItem, required — TaxCode reference. - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier). - `entitlement` union — Entitlement template configured on a rate card. The feature is taken from the rate card itself, so it is omitted here. - 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 — [ISO 8601 Duration](https://docs.digi.com/resources/documentation/digidocs/90001488-13/reference/r_iso_8601_duration_format.htm) string. - 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 — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `updated_at` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `deleted_at` string, date-time — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `key` string, required — A key is a unique string that is used to identify a resource. - `version` integer, required — Plans are versioned to allow you to make changes without affecting running subscriptions. - `currency` string, required — Three-letter [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. Custom three-letter currency codes are also supported for convenience. - `billing_cadence` string, ISO8601, required — [ISO 8601 Duration](https://docs.digi.com/resources/documentation/digidocs/90001488-13/reference/r_iso_8601_duration_format.htm) string. - `pro_rating_enabled` boolean — Whether pro-rating is enabled for this plan. - `effective_from` string, date-time — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `effective_to` string, date-time — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `status` 'draft' | 'active' | 'archived' | 'scheduled', required — The status of a plan. - `draft`: The plan has not yet been published and can be edited. - `active`: The plan is published and can be used in subscriptions. - `archived`: The plan is no longer available for use. - `scheduled`: The plan is scheduled to be published at a future date. - `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 — [ISO 8601 Duration](https://docs.digi.com/resources/documentation/digidocs/90001488-13/reference/r_iso_8601_duration_format.htm) string. - `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` FeatureReferenceItem — Feature reference. - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier). - `billing_cadence` string, ISO8601 — [ISO 8601 Duration](https://docs.digi.com/resources/documentation/digidocs/90001488-13/reference/r_iso_8601_duration_format.htm) string. - `price` union, required — Price. - 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 — Numeric represents an arbitrary precision number. - 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 — Numeric represents an arbitrary precision number. - 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 — Numeric represents an arbitrary precision number. - `flat_price` BillingPriceFlat — Flat price. - … - `unit_price` BillingPriceUnit — 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). - … - 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 — Numeric represents an arbitrary precision number. - `flat_price` BillingPriceFlat — Flat price. - … - `unit_price` BillingPriceUnit — 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). - … - `payment_term` 'in_advance' | 'in_arrears' — The payment term of a flat price. - `commitments` BillingSpendCommitments — Spend commitments for a rate card. The customer is committed to spend at least the minimum amount and at most the maximum amount. - `minimum_amount` string — Numeric represents an arbitrary precision number. - `maximum_amount` string — Numeric represents an arbitrary precision number. - `discounts` BillingRateCardDiscounts — Discount configuration for a rate card. - `percentage` number — Percentage discount applied to the price (0–100). - `usage` string — Numeric represents an arbitrary precision number. - `tax_config` BillingRateCardTaxConfig — 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` TaxCodeReferenceItem, required — TaxCode reference. - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier). - `entitlement` union — Entitlement template configured on a rate card. The feature is taken from the rate card itself, so it is omitted here. - 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 — [ISO 8601 Duration](https://docs.digi.com/resources/documentation/digidocs/90001488-13/reference/r_iso_8601_duration_format.htm) string. - 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 billing. 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 ## Changes - **2026-06-11** (v3) `2d8689050773` — 2 info - added the new optional request property `phases/items/rate_cards/items/entitlement` - added the optional property `phases/items/rate_cards/items/entitlement` to the response with the `200` status - **2026-06-09** (v3) `64826b7e8711` — 1 info - added the optional property `settlement_mode` to the response with the `200` status - **2026-05-11** (v3) `9d0042cb3815` — 1 breaking, 6 warning, 2 info - added `#/components/schemas/FeatureReferenceItem` to the `phases/items/rate_cards/items/feature` request property `allOf` list - removed `#/components/schemas/FeatureReference` from the `phases/items/rate_cards/items/feature` request property `allOf` list - removed the request property `phases/items/rate_cards/items/entitlement` - removed the request property `phases/items/rate_cards/items/unit_config` - …5 more [Change history](https://skmtc.dev/openmeterio/apis/openmeter-api/changes/openmeter/plans/:planId/put.md) --- [API](https://skmtc.dev/openmeterio/apis/openmeter-api.md) · [All operations](https://skmtc.dev/openmeterio/apis/openmeter-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/openmeterio/openmeter-api/revisions/3ecbdfd707eb/schema)