--- title: "Create subscription" method: POST path: "/api/v1/subscriptions" tags: ["Subscriptions"] --- # Create subscription `POST /api/v1/subscriptions` ## Request body - union — Create a subscription. - PlanSubscriptionCreate — Create subscription based on plan. - `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. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `plan` PlanReferenceInput, required — References an exact plan defaulting to the current active version. - `key` string, required — The plan key. - `version` integer — The plan version. - `startingPhase` string — The key of the phase to start the subscription in. If not provided, the subscription will start in the first phase of the plan. - `name` string — The name of the Subscription. If not provided the plan name is used. - `description` string — Description for the Subscription. - `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. - `timing` union — Subscription edit timing defined when the changes should take effect. If the provided configuration is not supported by the subscription, an error will be returned. - 'immediate' | 'next_billing_cycle' — Subscription edit timing. When immediate, the requested changes take effect immediately. When nextBillingCycle, 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. - `customerId` string — The ID of the customer. Provide either the key or ID. Has presedence over the key. - `customerKey` string — The key of the customer. Provide either the key or ID. - `billingAnchor` string, date-time — The billing anchor of the subscription. The provided date will be normalized according to the billing cadence to the nearest recurrence before start time. If not provided, the subscription start time will be used. - CustomSubscriptionCreate — Create a custom subscription. - `customPlan` CustomPlanInput, required — The template for omitting properties. - `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. - `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. - `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. - … - object — A usage-based rate card defines a price based on usage. - … - `timing` union — Subscription edit timing defined when the changes should take effect. If the provided configuration is not supported by the subscription, an error will be returned. - 'immediate' | 'next_billing_cycle' — Subscription edit timing. When immediate, the requested changes take effect immediately. When nextBillingCycle, 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. - `customerId` string — The ID of the customer. Provide either the key or ID. Has presedence over the key. - `customerKey` string — The key of the customer. Provide either the key or ID. - `billingAnchor` string, date-time — The billing anchor of the subscription. The provided date will be normalized according to the billing cadence to the nearest recurrence before start time. If not provided, the subscription start time will be used. ## Response `201` The request has succeeded and a new resource has been created as a result. - Subscription — Subscription is an exact subscription instance. - `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. - `activeFrom` string, date-time, required — The cadence start of the resource. - `activeTo` string, date-time — The cadence end of the resource. - `annotations` Annotations — Set of key-value pairs managed by the system. Cannot be modified by user. - `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. - `status` 'active' | 'inactive' | 'canceled' | 'scheduled', required — Subscription status. - `customerId` string, required — The customer ID of the subscription. - `plan` PlanReference — References an exact plan. - `id` string, required — The plan ID. - `key` string, required — The plan key. - `version` integer, required — The plan version. - `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 billing cadence for the subscriptions. 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. - `billingAnchor` string, date-time, required — The normalizedbilling anchor of the subscription. - `settlementMode` 'credit_then_invoice' | 'credit_only', required — 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. ## 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). Variants with ErrorExtensions specific to subscriptions. - `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. - `409` — The request could not be completed due to a conflict with the current state of the target resource. Variants with ErrorExtensions specific to subscriptions. - `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)