--- title: "Update a plan" method: PUT path: "/api/v1/plans/{planId}" tags: ["Product Catalog"] --- # Update a plan `PUT /api/v1/plans/{planId}` Update plan by id. ## Path parameters - `planId` string, required ## Request body - PlanReplaceUpdate — Resource update operation model. - `name` string, required — Human-readable name for the resource. Between 1 and 256 characters. - `description` string — Optional description of the resource. Maximum 1024 characters. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `alignment` Alignment — Alignment configuration for a plan or subscription. - `billablesMustAlign` boolean — Whether all Billable items and RateCards must align. Alignment means the Price's BillingCadence must align for both duration and anchor time. - `billingCadence` string, duration, required — The default billing cadence for subscriptions using this plan. Defines how often customers are billed using ISO8601 duration format. Examples: "P1M" (monthly), "P3M" (quarterly), "P1Y" (annually). - `proRatingConfig` ProRatingConfig — Configuration for pro-rating behavior. - `enabled` boolean, required — Whether pro-rating is enabled for this plan. - `mode` 'prorate_prices', required — Pro-rating mode options for handling billing period changes. - `settlementMode` 'credit_then_invoice' | 'credit_only' — The settlement mode of a plan. It determines how the billing system generates invoices and credits for the subscriptions using this plan. - credit_then_invoice: credits from the previous billing period are applied first, then the remaining balance is invoiced. This is the default and most common settlement mode. - credit_only: only credits from the previous billing period are generated and applied. No invoices are generated for the subscription. - `phases` PlanPhase[], required — The plan phase or pricing ramp allows changing a plan's rate cards over time as a subscription progresses. A phase switch occurs only at the end of a billing period, ensuring that a single subscription invoice will not include charges from different phase prices. - `key` string, required — A semi-unique identifier for the resource. - `name` string, required — Human-readable name for the resource. Between 1 and 256 characters. - `description` string — Optional description of the resource. Maximum 1024 characters. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `duration` string, duration, nullable, required — The duration of the phase. - `rateCards` RateCard[], required — The rate cards of the plan. - union — A rate card defines the pricing and entitlement of a feature or service. - object — A flat fee rate card defines a one-time purchase or a recurring fee. - `type` 'flat_fee', required — The type of the RateCard. - `key` string, required — A semi-unique identifier for the resource. - `name` string, required — Human-readable name for the resource. Between 1 and 256 characters. - `description` string — Optional description of the resource. Maximum 1024 characters. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `featureKey` string — The feature the customer is entitled to use. - `entitlementTemplate` union — Entitlement templates are used to define the entitlements of a plan. Features are omitted from the entitlement template, as they are defined in the rate card. - object — The entitlement template with a metered entitlement. - … - object — Entitlement template of a static entitlement. - … - object — Entitlement template of a boolean entitlement. - … - `taxConfig` TaxConfig — Set of provider specific tax configs. - `behavior` 'inclusive' | 'exclusive' — Tax behavior. This enum is used to specify whether tax is included in the price or excluded from the price. - `stripe` StripeTaxConfig — The tax config for Stripe. - … - `customInvoicing` CustomInvoicingTaxConfig — Custom invoicing tax config. - … - `taxCodeId` string — Tax code reference. When both `taxCodeId` and `stripe.code` are provided, `taxCodeId` takes precedence: the referenced tax code entity is used and `stripe.code` is ignored. - `billingCadence` string, duration, nullable, required — The billing cadence of the rate card. When null it means it is a one time fee. - `price` FlatPriceWithPaymentTerm, required — Flat price with payment term. - `type` 'flat', required — The type of the price. - `amount` string, required — Numeric represents an arbitrary precision number. - `paymentTerm` 'in_advance' | 'in_arrears' — The payment term of a flat price. One of: in_advance or in_arrears. - `discounts` Discounts — Discount by type on a price - `percentage` DiscountPercentage — Percentage discount. - … - `usage` DiscountUsage — Usage discount. Usage discount means that the first N items are free. From billing perspective this means that any usage on a specific feature is considered 0 until this discount is exhausted. - … - object — A usage-based rate card defines a price based on usage. - `type` 'usage_based', required — The type of the RateCard. - `key` string, required — A semi-unique identifier for the resource. - `name` string, required — Human-readable name for the resource. Between 1 and 256 characters. - `description` string — Optional description of the resource. Maximum 1024 characters. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `featureKey` string — The feature the customer is entitled to use. - `entitlementTemplate` union — Entitlement templates are used to define the entitlements of a plan. Features are omitted from the entitlement template, as they are defined in the rate card. - object — The entitlement template with a metered entitlement. - … - object — Entitlement template of a static entitlement. - … - object — Entitlement template of a boolean entitlement. - … - `taxConfig` TaxConfig — Set of provider specific tax configs. - `behavior` 'inclusive' | 'exclusive' — Tax behavior. This enum is used to specify whether tax is included in the price or excluded from the price. - `stripe` StripeTaxConfig — The tax config for Stripe. - … - `customInvoicing` CustomInvoicingTaxConfig — Custom invoicing tax config. - … - `taxCodeId` string — Tax code reference. When both `taxCodeId` and `stripe.code` are provided, `taxCodeId` takes precedence: the referenced tax code entity is used and `stripe.code` is ignored. - `billingCadence` string, duration, required — The billing cadence of the rate card. - `price` union, required — The price of the usage based rate card. - object — Flat price with payment term. - … - object — Unit price with spend commitments. - … - object — Tiered price with spend commitments. - … - object — Dynamic price with spend commitments. - … - object — Package price with spend commitments. - … - `discounts` Discounts — Discount by type on a price - `percentage` DiscountPercentage — Percentage discount. - … - `usage` DiscountUsage — Usage discount. Usage discount means that the first N items are free. From billing perspective this means that any usage on a specific feature is considered 0 until this discount is exhausted. - … ## Response `200` The request has succeeded. - Plan — Plans provide a template for subscriptions. - `id` string, required — A unique identifier for the resource. - `name` string, required — Human-readable name for the resource. Between 1 and 256 characters. - `description` string — Optional description of the resource. Maximum 1024 characters. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `key` string, required — A semi-unique identifier for the resource. - `alignment` Alignment — Alignment configuration for a plan or subscription. - `billablesMustAlign` boolean — Whether all Billable items and RateCards must align. Alignment means the Price's BillingCadence must align for both duration and anchor time. - `version` integer, required — Version of the plan. Incremented when the plan is updated. - `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. - `billingCadence` string, duration, required — The default billing cadence for subscriptions using this plan. Defines how often customers are billed using ISO8601 duration format. Examples: "P1M" (monthly), "P3M" (quarterly), "P1Y" (annually). - `proRatingConfig` ProRatingConfig — Configuration for pro-rating behavior. - `enabled` boolean, required — Whether pro-rating is enabled for this plan. - `mode` 'prorate_prices', required — Pro-rating mode options for handling billing period changes. - `effectiveFrom` string, date-time — The date and time when the plan becomes effective. When not specified, the plan is a draft. - `effectiveTo` string, date-time — The date and time when the plan is no longer effective. When not specified, the plan is effective indefinitely. - `status` 'draft' | 'active' | 'archived' | 'scheduled', required — The status of a plan. - `settlementMode` 'credit_then_invoice' | 'credit_only' — The settlement mode of a plan. It determines how the billing system generates invoices and credits for the subscriptions using this plan. - credit_then_invoice: credits from the previous billing period are applied first, then the remaining balance is invoiced. This is the default and most common settlement mode. - credit_only: only credits from the previous billing period are generated and applied. No invoices are generated for the subscription. - `phases` PlanPhase[], required — The plan phase or pricing ramp allows changing a plan's rate cards over time as a subscription progresses. A phase switch occurs only at the end of a billing period, ensuring that a single subscription invoice will not include charges from different phase prices. - `key` string, required — A semi-unique identifier for the resource. - `name` string, required — Human-readable name for the resource. Between 1 and 256 characters. - `description` string — Optional description of the resource. Maximum 1024 characters. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `duration` string, duration, nullable, required — The duration of the phase. - `rateCards` RateCard[], required — The rate cards of the plan. - union — A rate card defines the pricing and entitlement of a feature or service. - object — A flat fee rate card defines a one-time purchase or a recurring fee. - `type` 'flat_fee', required — The type of the RateCard. - `key` string, required — A semi-unique identifier for the resource. - `name` string, required — Human-readable name for the resource. Between 1 and 256 characters. - `description` string — Optional description of the resource. Maximum 1024 characters. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `featureKey` string — The feature the customer is entitled to use. - `entitlementTemplate` union — Entitlement templates are used to define the entitlements of a plan. Features are omitted from the entitlement template, as they are defined in the rate card. - object — The entitlement template with a metered entitlement. - … - object — Entitlement template of a static entitlement. - … - object — Entitlement template of a boolean entitlement. - … - `taxConfig` TaxConfig — Set of provider specific tax configs. - `behavior` 'inclusive' | 'exclusive' — Tax behavior. This enum is used to specify whether tax is included in the price or excluded from the price. - `stripe` StripeTaxConfig — The tax config for Stripe. - … - `customInvoicing` CustomInvoicingTaxConfig — Custom invoicing tax config. - … - `taxCodeId` string — Tax code reference. When both `taxCodeId` and `stripe.code` are provided, `taxCodeId` takes precedence: the referenced tax code entity is used and `stripe.code` is ignored. - `billingCadence` string, duration, nullable, required — The billing cadence of the rate card. When null it means it is a one time fee. - `price` FlatPriceWithPaymentTerm, required — Flat price with payment term. - `type` 'flat', required — The type of the price. - `amount` string, required — Numeric represents an arbitrary precision number. - `paymentTerm` 'in_advance' | 'in_arrears' — The payment term of a flat price. One of: in_advance or in_arrears. - `discounts` Discounts — Discount by type on a price - `percentage` DiscountPercentage — Percentage discount. - … - `usage` DiscountUsage — Usage discount. Usage discount means that the first N items are free. From billing perspective this means that any usage on a specific feature is considered 0 until this discount is exhausted. - … - object — A usage-based rate card defines a price based on usage. - `type` 'usage_based', required — The type of the RateCard. - `key` string, required — A semi-unique identifier for the resource. - `name` string, required — Human-readable name for the resource. Between 1 and 256 characters. - `description` string — Optional description of the resource. Maximum 1024 characters. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `featureKey` string — The feature the customer is entitled to use. - `entitlementTemplate` union — Entitlement templates are used to define the entitlements of a plan. Features are omitted from the entitlement template, as they are defined in the rate card. - object — The entitlement template with a metered entitlement. - … - object — Entitlement template of a static entitlement. - … - object — Entitlement template of a boolean entitlement. - … - `taxConfig` TaxConfig — Set of provider specific tax configs. - `behavior` 'inclusive' | 'exclusive' — Tax behavior. This enum is used to specify whether tax is included in the price or excluded from the price. - `stripe` StripeTaxConfig — The tax config for Stripe. - … - `customInvoicing` CustomInvoicingTaxConfig — Custom invoicing tax config. - … - `taxCodeId` string — Tax code reference. When both `taxCodeId` and `stripe.code` are provided, `taxCodeId` takes precedence: the referenced tax code entity is used and `stripe.code` is ignored. - `billingCadence` string, duration, required — The billing cadence of the rate card. - `price` union, required — The price of the usage based rate card. - object — Flat price with payment term. - … - object — Unit price with spend commitments. - … - object — Tiered price with spend commitments. - … - object — Dynamic price with spend commitments. - … - object — Package price with spend commitments. - … - `discounts` Discounts — Discount by type on a price - `percentage` DiscountPercentage — Percentage discount. - … - `usage` DiscountUsage — Usage discount. Usage discount means that the first N items are free. From billing perspective this means that any usage on a specific feature is considered 0 until this discount is exhausted. - … - `validationErrors` ValidationError[], nullable, required — List of validation errors. - `field` string, required — The path to the field. - `code` string, required — The machine readable description of the error. - `message` string, required — The human readable description of the error. - `attributes` Annotations — Set of key-value pairs managed by the system. Cannot be modified by user. ## Other responses - `400` — The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). - `401` — The request has not been applied because it lacks valid authentication credentials for the target resource. - `403` — The server understood the request but refuses to authorize it. - `404` — The origin server did not find a current representation for the target resource or is not willing to disclose that one exists. - `412` — One or more conditions given in the request header fields evaluated to false when tested on the server. - `500` — The server encountered an unexpected condition that prevented it from fulfilling the request. - `503` — The server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay. - `default` — An unexpected error response. --- [API](https://skmtc.net/openmeterio/apis/openmeter-api.md) · [All operations](https://skmtc.net/openmeterio/apis/openmeter-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openmeterio/openmeter-api/versions/927d82ffe647/schema)