--- title: "Get subscription" method: GET path: "/api/v1/subscriptions/{subscriptionId}" tags: ["Subscriptions"] --- # Get subscription `GET /api/v1/subscriptions/{subscriptionId}` ## Path parameters - `subscriptionId` string, required ## Query parameters - `at` string, date-time ## Response `200` The request has succeeded. - SubscriptionExpanded — Expanded subscription - `activeFrom` string, date-time, required — The cadence start of the resource. - `activeTo` string, date-time — The cadence end of the resource. - `alignment` SubscriptionAlignment — Alignment details enriched with the current billing period. - `billablesMustAlign` boolean — Whether all Billable items and RateCards must align. Alignment means the Price's BillingCadence must align for both duration and anchor time. - `currentAlignedBillingPeriod` Period — A period with a start and end time. - `from` string, date-time, required — Period start time. - `to` string, date-time, required — Period end time. - `annotations` Annotations — Set of key-value pairs managed by the system. Cannot be modified by user. - `billingAnchor` string, date-time, required — The normalizedbilling anchor of the subscription. - `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). - `costBasisMode` 'dynamic' | 'pinned', required — Controls how custom-currency cost bases are selected for the subscription. - `costBasisPins` SubscriptionCostBasisPin[], required — Cost bases pinned to custom-currency pairs for this subscription. - `costBasisId` string, required — The pinned cost basis resource ID. - `customCurrencyId` string, required — The managed custom currency ID. - `invoiceCurrency` 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. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `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. - `customerId` string, required — The customer ID of the subscription. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `description` string — Optional description of the resource. Maximum 1024 characters. - `id` string, required — A unique identifier for the resource. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `name` string, required — Human-readable name for the resource. Between 1 and 256 characters. - `phases` SubscriptionPhaseExpanded[], required — The phases of the subscription. - `activeFrom` string, date-time, required — The time from which the phase is active. - `activeTo` string, date-time — The until which the Phase is active. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `description` string — Optional description of the resource. Maximum 1024 characters. - `discounts` Discounts — Discount by type on a price - `percentage` DiscountPercentage — Percentage discount. - `percentage` number, double, required — Numeric representation of a percentage 50% is represented as 50 - `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. - `quantity` string, required — Numeric represents an arbitrary precision number. - `id` string, required — A unique identifier for the resource. - `itemTimelines` object, required — Includes all versions of the items on each key, including all edits, scheduled changes, etc... - `items` SubscriptionItem[], required — The items of the phase. The structure is flattened to better conform to the Plan API. The timelines are flattened according to the following rules: - for the current phase, the `items` contains only the active item for each key - for past phases, the `items` contains only the last item for each key - for future phases, the `items` contains only the first version of the item for each key - `activeFrom` string, date-time, required — The cadence start of the resource. - `activeTo` string, date-time — The cadence end of the resource. - `billingCadence` string, duration, nullable, required — The billing cadence of the rate card. When null, the rate card is a one-time purchase. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `currency` string — Fiat or managed custom currency code. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `description` string — Optional description of the resource. Maximum 1024 characters. - `discounts` Discounts — Discount by type on a price - `percentage` DiscountPercentage — Percentage discount. - `percentage` number, double, required — Numeric representation of a percentage 50% is represented as 50 - `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. - `quantity` string, required — Numeric represents an arbitrary precision number. - `featureKey` string — The feature's key (if present). - `id` string, required — A unique identifier for the resource. - `included` SubscriptionItemIncluded — Included contents like Entitlement, or the Feature. - `entitlement` 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 — Metered entitlements are useful for many different use cases, from setting up usage based access to implementing complex credit systems. Access is determined based on feature usage using a balance calculation (the "usage allowance" provided by the issued grants is "burnt down" by the usage). - `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. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `currentUsagePeriod` Period, required — A period with a start and end time. - … - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `featureId` string, required — The feature the subject is entitled to use. - `featureKey` string, required — The feature the subject is entitled to use. - `id` string, required — Readonly unique ULID identifier. - `isSoftLimit` boolean — If softLimit=true the subject can use the feature even if the entitlement is exhausted, hasAccess will always be true. - `isUnlimited` boolean — Deprecated, ignored by the backend. Please use isSoftLimit instead; this field will be removed in the future. - `issueAfterReset` number, double — You can grant usage automatically alongside the entitlement, the example scenario would be creating a starting balance. If an amount is specified here, a grant will be created alongside the entitlement with the specified amount. That grant will have it's rollover settings configured in a way that after each reset operation, the balance will return the original amount specified here. Manually creating such a grant would mean having the "amount", "minRolloverAmount", and "maxRolloverAmount" fields all be the same. - `issueAfterResetPriority` integer — Defines the grant priority for the default grant. - `lastReset` string, date-time, required — The time the last reset happened. - `measureUsageFrom` string, date-time, required — The time from which usage is measured. If not specified on creation, defaults to entitlement creation time. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `preserveOverageAtReset` boolean — If true, the overage is preserved at reset. If false, the usage is reset to 0. - `subjectKey` string, required — The identifier key unique to the subject. NOTE: Subjects are being deprecated, please use the new customer APIs. - `type` 'metered', required - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `usagePeriod` RecurringPeriod, required — Recurring period with an interval and an anchor. - … - object — A static entitlement. - `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. - `config` string, json, required — The JSON parsable config of the entitlement. This value is also returned when checking entitlement access and it is useful for configuring fine-grained access settings to the feature, implemented in your own system. Has to be an object. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `currentUsagePeriod` Period — A period with a start and end time. - … - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `featureId` string, required — The feature the subject is entitled to use. - `featureKey` string, required — The feature the subject is entitled to use. - `id` string, required — Readonly unique ULID identifier. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `subjectKey` string, required — The identifier key unique to the subject. NOTE: Subjects are being deprecated, please use the new customer APIs. - `type` 'static', required - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `usagePeriod` RecurringPeriod — Recurring period with an interval and an anchor. - … - object — Entitlement template of a boolean entitlement. - `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. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `currentUsagePeriod` Period — A period with a start and end time. - … - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `featureId` string, required — The feature the subject is entitled to use. - `featureKey` string, required — The feature the subject is entitled to use. - `id` string, required — Readonly unique ULID identifier. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `subjectKey` string, required — The identifier key unique to the subject. NOTE: Subjects are being deprecated, please use the new customer APIs. - `type` 'boolean', required - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `usagePeriod` RecurringPeriod — Recurring period with an interval and an anchor. - … - `feature` Feature, required — Represents a feature that can be enabled or disabled for a plan. Used both for product catalog and entitlements. - `advancedMeterGroupByFilters` object — Optional advanced meter group by filters. You can use this to filter for values of the meter groupBy fields. - `archivedAt` string, date-time — Timestamp of when the resource was archived. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `id` string, required — Readonly unique ULID identifier. - `key` string, required — A key is a unique string that is used to identify a resource. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `meterGroupByFilters` object — Optional meter group by filters. Useful if the meter scope is broader than what feature tracks. Example scenario would be a meter tracking all token use with groupBy fields for the model, then the feature could filter for model=gpt-4. ⚠️ __Deprecated__: Use advancedMeterGroupByFilters instead - `meterSlug` string — A key is a unique string that is used to identify a resource. - `name` string, required - `unitCost` union — Per-unit cost configuration for a feature. Either a fixed manual amount or a dynamic LLM cost lookup. - object — A fixed per-unit cost amount. - … - object — LLM cost lookup configuration. Maps meter group-by dimensions to LLM cost database fields. - … - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `key` string, required — The identifier of the RateCard. SubscriptionItem/RateCard can be identified, it has a reference: 1. If a Feature is associated with the SubscriptionItem, it is identified by the Feature 1.1 It can be an ID reference, for an exact version of the Feature (Features can change across versions) 1.2 It can be a Key reference, which always refers to the latest (active or inactive) version of a Feature 2. If a Feature is not associated with the SubscriptionItem, it is referenced by the Price We say "referenced by the Price" regardless of how a price itself is referenced, it colloquially makes sense to say "paying the same price for the same thing". In practice this should be derived from what's printed on the invoice line-item. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `name` string, required — Human-readable name for the resource. Between 1 and 256 characters. - `price` union, required — The price of the usage based rate card. - object — Flat price with payment term. - `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. - `type` 'flat', required — The type of the price. - object — Unit price with spend commitments. - `amount` string, required — Numeric represents an arbitrary precision number. - `maximumAmount` string — Numeric represents an arbitrary precision number. - `minimumAmount` string — Numeric represents an arbitrary precision number. - `type` 'unit', required — The type of the price. - object — Tiered price with spend commitments. - `maximumAmount` string — Numeric represents an arbitrary precision number. - `minimumAmount` string — Numeric represents an arbitrary precision number. - `mode` 'volume' | 'graduated', required — The mode of the tiered price. - `tiers` PriceTier[], required — The tiers of the tiered price. At least one price component is required in each tier. - `flatPrice` FlatPrice, required — Flat price. - … - `unitPrice` UnitPrice, required — Unit price. - … - `upToAmount` string — Numeric represents an arbitrary precision number. - `type` 'tiered', required — The type of the price. One of: flat, unit, or tiered. - object — Dynamic price with spend commitments. - `maximumAmount` string — Numeric represents an arbitrary precision number. - `minimumAmount` string — Numeric represents an arbitrary precision number. - `multiplier` string — Numeric represents an arbitrary precision number. - `type` 'dynamic', required — The type of the price. - object — Package price with spend commitments. - `amount` string, required — Numeric represents an arbitrary precision number. - `maximumAmount` string — Numeric represents an arbitrary precision number. - `minimumAmount` string — Numeric represents an arbitrary precision number. - `quantityPerPackage` string, required — Numeric represents an arbitrary precision number. - `type` 'package', required — The type of the price. - `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. - `customInvoicing` CustomInvoicingTaxConfig — Custom invoicing tax config. - `code` string, required — Tax code. The tax code should be interpreted by the custom invoicing provider. - `stripe` StripeTaxConfig — The tax config for Stripe. - `code` string, required — Product tax code. See: https://docs.stripe.com/tax/tax-codes - `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. - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `key` string, required — A locally unique identifier for the resource. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `name` string, required — Human-readable name for the resource. Between 1 and 256 characters. - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `plan` PlanReference — References an exact plan. - `id` string, required — The plan ID. - `key` string, required — The plan key. - `version` integer, required — The plan version. - `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', 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. - `status` 'active' | 'inactive' | 'canceled' | 'scheduled', required — Subscription status. - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. ## 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.dev/openmeter/apis/openmeter-cloud-api.md) · [All operations](https://skmtc.dev/openmeter/apis/openmeter-cloud-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/openmeter/openmeter-cloud-api/revisions/c9c0ec9cffe9/schema)