--- title: "List plans" method: GET path: "/api/v1/plans" tags: ["Product Catalog"] --- # List plans `GET /api/v1/plans` List all plans. ## Query parameters - `includeDeleted` boolean - `id` string[] - `key` string[] - `keyVersion` object - `status` PlanStatus[] - `currency` CurrencyCode[] - `page` integer - `pageSize` integer - `order` 'ASC' | 'DESC' — The order direction. - `orderBy` 'id' | 'key' | 'version' | 'created_at' | 'updated_at' — Order by options for plans. ## Response `200` The request has succeeded. - PlanPaginatedResponse — Paginated response - `totalCount` integer, required — The total number of items. - `page` integer, required — The page index. - `pageSize` integer, required — The maximum number of items per page. - `items` Plan[], required — The items in the current page. - `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. - … - `taxConfig` TaxConfig — Set of provider specific tax configs. - … - `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. - … - `discounts` Discounts — Discount by type on a price - … - 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. - … - `taxConfig` TaxConfig — Set of provider specific tax configs. - … - `billingCadence` string, duration, required — The billing cadence of the rate card. - `price` union, required — The price of the usage based rate card. - … - `discounts` Discounts — Discount by type on a price - … - `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. - `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)