--- title: "Get subscription (V2)" method: GET path: "/subscriptions/{id}/v2" tags: ["Subscriptions"] --- # Get subscription (V2) `GET /subscriptions/{id}/v2` Use when you need a subscription with related data (line items, prices, plan). Supports expand for detailed payloads without extra round-trips. ## Path parameters - `id` string, required ## Query parameters - `expand` string ## Response `200` OK - DtoSubscriptionResponseV2 - `active_pause_id` string — ActivePauseID references the current active pause configuration This will be null if no pause is active or scheduled - `billing_anchor` string — BillingAnchor is the reference point that aligns future billing cycle dates. It sets the day of week for week intervals, the day of month for month and year intervals, and the month of year for year intervals. The timestamp is in UTC format. - `billing_cadence` 'RECURRING' | 'ONETIME' - `billing_cycle` 'anniversary' | 'calendar' - `billing_period` 'MONTHLY' | 'ANNUAL' | 'WEEKLY' | 'DAILY' | 'QUARTERLY' | 'HALF_YEARLY' - `billing_period_count` integer — BillingPeriodCount is the total number units of the billing period. - `cancel_at` string — CancelAt is the date the subscription will be canceled - `cancel_at_period_end` boolean — CancelAtPeriodEnd is whether the subscription was canceled at the end of the current period - `cancelled_at` string — CanceledAt is the date the subscription was canceled - `collection_method` string — CollectionMethod determines how invoices are collected - `commitment_amount` string — CommitmentAmount is the minimum amount a customer commits to paying for a billing period - `commitment_duration` 'MONTHLY' | 'ANNUAL' | 'WEEKLY' | 'DAILY' | 'QUARTERLY' | 'HALF_YEARLY' - `coupon_associations` DtoCouponAssociationResponse[] — CouponAssociations are included when "coupon_associations" is in expand parameter - `coupon` GithubComFlexpriceFlexpriceInternalDomainCouponCoupon - `amount_off` string - `cadence` 'once' | 'repeated' | 'forever' - `created_at` string - `created_by` string - `currency` string - `duration_in_periods` integer - `environment_id` string - `id` string - `max_redemptions` integer - `metadata` object - `name` string - `percentage_off` string - `redeem_after` string - `redeem_before` string - `rules` object - `status` 'published' | 'deleted' | 'archived' - `tenant_id` string - `total_redemptions` integer - `type` 'fixed' | 'percentage' - `updated_at` string - `updated_by` string - `coupon_id` string - `created_at` string - `created_by` string - `end_date` string — Optional - `environment_id` string - `id` string - `metadata` object - `start_date` string - `status` 'published' | 'deleted' | 'archived' - `subscription_id` string — Mandatory - `subscription_line_item_id` string — Optional - `subscription_phase_id` string — Optional - `tenant_id` string - `updated_at` string - `updated_by` string - `created_at` string - `created_by` string - `credit_grants` DtoCreditGrantResponse[] — CreditGrants are included when "credit_grants" is in expand parameter - `cadence` 'ONETIME' | 'RECURRING' - `conversion_rate` string — amount in the currency = number of credits * conversion_rate ex if conversion_rate is 1, then 1 USD = 1 credit ex if conversion_rate is 2, then 1 USD = 0.5 credits ex if conversion_rate is 0.5, then 1 USD = 2 credits - `created_at` string - `created_by` string - `credit_grant_anchor` string - `credits` string - `end_date` string - `environment_id` string - `expiration_duration` integer - `expiration_duration_unit` 'DAY' | 'WEEK' | 'MONTH' | 'YEAR' - `expiration_type` 'NEVER' | 'DURATION' | 'BILLING_CYCLE' - `id` string - `metadata` TypesMetadata - `name` string - `period` 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'ANNUAL' | 'QUARTERLY' | 'HALF_YEARLY' - `period_count` integer - `plan_id` string - `priority` integer - `scope` 'PLAN' | 'SUBSCRIPTION' - `start_date` string - `status` 'published' | 'deleted' | 'archived' - `subscription_id` string - `tenant_id` string - `topup_conversion_rate` string — topup_conversion_rate is the conversion rate for the topup to the currency ex if topup_conversion_rate is 1, then 1 USD = 1 credit ex if topup_conversion_rate is 2, then 1 USD = 0.5 credits ex if topup_conversion_rate is 0.5, then 1 USD = 2 credits - `updated_at` string - `updated_by` string - `currency` string — Currency is the currency of the subscription in lowercase 3 digit ISO codes - `current_period_end` string — CurrentPeriodEnd is the end of the current period that the subscription has been invoiced for. At the end of this period, a new invoice will be created. - `current_period_start` string — CurrentPeriodStart is the end of the current period that the subscription has been invoiced for. At the end of this period, a new invoice will be created. - `customer` DtoCustomerResponse — Customer response object containing all customer information - `address_city` string — AddressCity is the city of the customer's address - `address_country` string — AddressCountry is the country of the customer's address (ISO 3166-1 alpha-2) - `address_line1` string — AddressLine1 is the first line of the customer's address - `address_line2` string — AddressLine2 is the second line of the customer's address - `address_postal_code` string — AddressPostalCode is the postal code of the customer's address - `address_state` string — AddressState is the state of the customer's address - `created_at` string - `created_by` string - `email` string — Email is the email of the customer - `environment_id` string — EnvironmentID is the environment identifier for the customer - `external_id` string — ExternalID is the external identifier for the customer - `id` string — ID is the unique identifier for the customer - `integrations` DtoEntityIntegrationMappingResponse[] - `created_at` string - `created_by` string - `entity_id` string - `entity_type` 'customer' | 'plan' | 'invoice' | 'subscription' | 'payment' | 'credit_note' | 'addon' | 'item' | 'item_price' | 'price' - `environment_id` string - `id` string - `provider_entity_id` string - `provider_type` string - `status` 'published' | 'deleted' | 'archived' - `tenant_id` string - `updated_at` string - `updated_by` string - `metadata` object — Metadata - `name` string — Name is the name of the customer - `parent_customer` DtoCustomerResponse — recursive - `parent_customer_id` string — Deprecated: Customer parent hierarchy is deprecated in favor of subscription-level hierarchy. Retained for backward compatibility; no hierarchy rules are enforced at the service layer. ParentCustomerID is the parent customer identifier for the customer. - `status` 'published' | 'deleted' | 'archived' - `tenant_id` string - `updated_at` string - `updated_by` string - `customer_id` string — CustomerID is the identifier for the customer in our system - `customer_timezone` string - `enable_true_up` boolean - `end_date` string — EndDate is the end date of the subscription - `environment_id` string — EnvironmentID is the environment identifier for the subscription - `gateway_payment_method_id` string — GatewayPaymentMethodID is the gateway payment method ID for this subscription - `id` string — ID is the unique identifier for the subscription - `invoicing_customer_id` string — InvoicingCustomerID is the customer ID to use for invoicing This can differ from the subscription customer (e.g., parent company invoicing for child company) - `line_items` DtoSubscriptionLineItemResponse[] — LineItems is expanded only if "subscription_line_items" is in expand parameter Each line item can optionally include expanded price data - `billing_period` 'MONTHLY' | 'ANNUAL' | 'WEEKLY' | 'DAILY' | 'QUARTERLY' | 'HALF_YEARLY' - `billing_period_count` integer — from price at create; default 1 - `commitment_amount` string — Commitment fields - `commitment_duration` 'MONTHLY' | 'ANNUAL' | 'WEEKLY' | 'DAILY' | 'QUARTERLY' | 'HALF_YEARLY' - `commitment_overage_factor` string - `commitment_quantity` string - `commitment_true_up_enabled` boolean - `commitment_type` 'amount' | 'quantity' - `commitment_windowed` boolean - `created_at` string - `created_by` string - `currency` string - `customer_id` string - `display_name` string - `end_date` string - `entity_id` string - `entity_type` 'plan' | 'addon' | 'subscription' - `environment_id` string - `id` string - `invoice_cadence` 'ARREAR' | 'ADVANCE' - `metadata` object - `meter_display_name` string - `meter_id` string - `plan_display_name` string - `price` DtoPriceResponse - `addon` DtoAddonResponse - `created_at` string - `created_by` string - `description` string - `entitlements` DtoEntitlementResponse[] - `addon` DtoAddonResponse — recursive - `created_at` string - `created_by` string - `display_order` integer - `end_date` string - `entity_id` string - `entity_type` 'PLAN' | 'SUBSCRIPTION' | 'ADDON' - `environment_id` string - `feature` DtoFeatureResponse - `alert_settings` TypesAlertSettings - … - `created_at` string - `created_by` string - `description` string - `environment_id` string - `group` DtoGroupResponse - … - `group_id` string - `id` string - `lookup_key` string - `metadata` TypesMetadata - `meter` DtoMeterResponse - … - `meter_id` string - `name` string - `reporting_unit` TypesReportingUnit - … - `status` 'published' | 'deleted' | 'archived' - `tenant_id` string - `type` 'metered' | 'boolean' | 'static' - `unit_plural` string - `unit_singular` string - `updated_at` string - `updated_by` string - `feature_id` string - `feature_type` 'metered' | 'boolean' | 'static' - `id` string - `is_enabled` boolean - `is_soft_limit` boolean - `parent_entitlement_id` string - `plan` DtoPlanResponse - `created_at` string - `created_by` string - `credit_grants` DtoCreditGrantResponse[] - … - `description` string - `display_order` integer - `entitlements` DtoEntitlementResponse[] - `environment_id` string - `id` string - `lookup_key` string - `metadata` TypesMetadata - `name` string - `prices` DtoPriceResponse[] — TODO: Add inline addons - `status` 'published' | 'deleted' | 'archived' - `tenant_id` string - `updated_at` string - `updated_by` string - `plan_id` string — TODO: Remove this once we have a proper entitlement entity type - `start_date` string - `static_value` string - `status` 'published' | 'deleted' | 'archived' - `tenant_id` string - `updated_at` string - `updated_by` string - `usage_limit` integer - `usage_reset_period` 'MONTHLY' | 'ANNUAL' | 'WEEKLY' | 'DAILY' | 'QUARTERLY' | 'HALF_YEARLY' | 'NEVER' - `environment_id` string - `id` string - `lookup_key` string - `metadata` object - `name` string - `prices` DtoPriceResponse[] — Optional expanded fields - `status` 'published' | 'deleted' | 'archived' - `tenant_id` string - `type` 'onetime' | 'multiple_instance' - `updated_at` string - `updated_by` string - `amount` string — Amount stored in main currency units (e.g., dollars, not cents) For USD: 12.50 means $12.50 - `billing_cadence` 'RECURRING' | 'ONETIME' - `billing_model` 'FLAT_FEE' | 'PACKAGE' | 'TIERED' - `billing_period` 'MONTHLY' | 'ANNUAL' | 'WEEKLY' | 'DAILY' | 'QUARTERLY' | 'HALF_YEARLY' - `billing_period_count` integer — BillingPeriodCount is the count of the billing period ex 1, 3, 6, 12 - `conversion_rate` string — ConversionRate is the conversion rate of the price unit to the fiat currency - `created_at` string - `created_by` string - `currency` string — Currency 3 digit ISO currency code in lowercase ex usd, eur, gbp - `description` string — Description of the price - `display_amount` string — DisplayAmount is the formatted amount with currency symbol For USD: $12.50 - `display_name` string — DisplayName is the name of the price - `display_price_unit_amount` string — DisplayPriceUnitAmount is the formatted amount of the price unit - `end_date` string — EndDate is the end date of the price - `entity_id` string — EntityID holds the value of the "entity_id" field. - `entity_type` 'PLAN' | 'SUBSCRIPTION' | 'ADDON' | 'PRICE' | 'COSTSHEET' - `environment_id` string — EnvironmentID is the environment identifier for the price - `group` DtoGroupResponse - `created_at` string - `entity_ids` string[] - `entity_type` string - `id` string - `lookup_key` string - `metadata` object - `name` string - `status` string - `updated_at` string - `group_id` string — GroupID references the group this price belongs to - `id` string — ID uuid identifier for the price - `invoice_cadence` 'ARREAR' | 'ADVANCE' - `lookup_key` string — LookupKey used for looking up the price in the database - `metadata` PriceJSONBMetadata - `meter` DtoMeterResponse - `aggregation` MeterAggregation - `bucket_size` 'MONTH' | 'MINUTE' | '15MIN' | '30MIN' | 'HOUR' | '3HOUR' | '6HOUR' | '12HOUR' | 'DAY' | 'WEEK' | 'MONTH' - `expression` string — Expression is an optional CEL expression to compute per-event quantity from event.properties. When set, it replaces Field-based extraction. Property names are used directly (e.g., token * duration * pixel). - `field` string — Field is the key in $event.properties on which the aggregation is to be applied For ex if the aggregation type is sum for API usage, the field could be "duration_ms" Ignored when Expression is set. - `group_by` string — GroupBy is the property name in event.properties to group by before aggregating. Currently only supported for MAX aggregation with bucket_size. When set, aggregation is applied per unique value of this property within each bucket, then the per-group results are summed to produce the bucket total. - `multiplier` string — Multiplier is the multiplier for the aggregation For ex if the aggregation type is sum_with_multiplier for API usage, the multiplier could be 1000 to scale up by a factor of 1000. If not provided, it will be null. - `type` 'COUNT' | 'SUM' | 'AVG' | 'COUNT_UNIQUE' | 'LATEST' | 'SUM_WITH_MULTIPLIER' | 'MAX' | 'WEIGHTED_SUM' - `created_at` string - `event_name` string - `filters` MeterFilter[] - `key` string — Key is the key for the filter from $event.properties Currently we support only first level keys in the properties and not nested keys - `values` string[] — Values are the possible values for the filter to be considered for the meter For ex "model_name" could have values "o1-mini", "gpt-4o" etc - `id` string - `name` string - `reset_usage` 'BILLING_PERIOD' | 'NEVER' - `status` string - `tenant_id` string - `updated_at` string - `meter_id` string — MeterID is the id of the meter for usage based pricing - `min_quantity` string, nullable — MinQuantity is the minimum quantity of the price - `parent_price_id` string — ParentPriceID references the root price (always set for price lineage tracking) - `plan` DtoPlanResponse - `created_at` string - `created_by` string - `credit_grants` DtoCreditGrantResponse[] - `cadence` 'ONETIME' | 'RECURRING' - `conversion_rate` string — amount in the currency = number of credits * conversion_rate ex if conversion_rate is 1, then 1 USD = 1 credit ex if conversion_rate is 2, then 1 USD = 0.5 credits ex if conversion_rate is 0.5, then 1 USD = 2 credits - `created_at` string - `created_by` string - `credit_grant_anchor` string - `credits` string - `end_date` string - `environment_id` string - `expiration_duration` integer - `expiration_duration_unit` 'DAY' | 'WEEK' | 'MONTH' | 'YEAR' - `expiration_type` 'NEVER' | 'DURATION' | 'BILLING_CYCLE' - `id` string - `metadata` TypesMetadata - `name` string - `period` 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'ANNUAL' | 'QUARTERLY' | 'HALF_YEARLY' - `period_count` integer - `plan_id` string - `priority` integer - `scope` 'PLAN' | 'SUBSCRIPTION' - `start_date` string - `status` 'published' | 'deleted' | 'archived' - `subscription_id` string - `tenant_id` string - `topup_conversion_rate` string — topup_conversion_rate is the conversion rate for the topup to the currency ex if topup_conversion_rate is 1, then 1 USD = 1 credit ex if topup_conversion_rate is 2, then 1 USD = 0.5 credits ex if topup_conversion_rate is 0.5, then 1 USD = 2 credits - `updated_at` string - `updated_by` string - `description` string - `display_order` integer - `entitlements` DtoEntitlementResponse[] - `addon` DtoAddonResponse - `created_at` string - `created_by` string - `description` string - `entitlements` DtoEntitlementResponse[] - `environment_id` string - `id` string - `lookup_key` string - `metadata` object - `name` string - `prices` DtoPriceResponse[] — Optional expanded fields - `status` 'published' | 'deleted' | 'archived' - `tenant_id` string - `type` 'onetime' | 'multiple_instance' - `updated_at` string - `updated_by` string - `created_at` string - `created_by` string - `display_order` integer - `end_date` string - `entity_id` string - `entity_type` 'PLAN' | 'SUBSCRIPTION' | 'ADDON' - `environment_id` string - `feature` DtoFeatureResponse - `alert_settings` TypesAlertSettings - … - `created_at` string - `created_by` string - `description` string - `environment_id` string - `group` DtoGroupResponse - … - `group_id` string - `id` string - `lookup_key` string - `metadata` TypesMetadata - `meter` DtoMeterResponse - … - `meter_id` string - `name` string - `reporting_unit` TypesReportingUnit - … - `status` 'published' | 'deleted' | 'archived' - `tenant_id` string - `type` 'metered' | 'boolean' | 'static' - `unit_plural` string - `unit_singular` string - `updated_at` string - `updated_by` string - `feature_id` string - `feature_type` 'metered' | 'boolean' | 'static' - `id` string - `is_enabled` boolean - `is_soft_limit` boolean - `parent_entitlement_id` string - `plan` DtoPlanResponse — recursive - `plan_id` string — TODO: Remove this once we have a proper entitlement entity type - `start_date` string - `static_value` string - `status` 'published' | 'deleted' | 'archived' - `tenant_id` string - `updated_at` string - `updated_by` string - `usage_limit` integer - `usage_reset_period` 'MONTHLY' | 'ANNUAL' | 'WEEKLY' | 'DAILY' | 'QUARTERLY' | 'HALF_YEARLY' | 'NEVER' - `environment_id` string - `id` string - `lookup_key` string - `metadata` TypesMetadata - `name` string - `prices` DtoPriceResponse[] — TODO: Add inline addons - `status` 'published' | 'deleted' | 'archived' - `tenant_id` string - `updated_at` string - `updated_by` string - `price_unit` string — PriceUnit is the code of the price unit (e.g., 'btc', 'eth') - `price_unit_amount` string — PriceUnitAmount is the amount of the price unit - `price_unit_id` string — PriceUnitID is the id of the price unit (for CUSTOM type) - `price_unit_tiers` PricePriceTier[] — PriceUnitTiers are the tiers for the price unit when BillingModel is TIERED - `flat_amount` string — flat_amount is the flat amount for the given tier (optional) Applied on top of unit_amount*quantity. Useful for cases like "2.7$ + 5c" - `unit_amount` string — unit_amount is the amount per unit for the given tier - `up_to` integer — up_to is the quantity up to which this tier applies. It is null for the last tier. IMPORTANT: Tier boundaries are INCLUSIVE. - If up_to is 1000, then quantity less than or equal to 1000 belongs to this tier - This behavior is consistent across both VOLUME and SLAB tier modes - `price_unit_type` 'FIAT' | 'CUSTOM' - `pricing_unit` DtoPriceUnitResponse - `base_currency` string - `code` string - `conversion_rate` string - `created_at` string - `created_by` string - `environment_id` string - `id` string - `metadata` TypesMetadata - `name` string - `status` 'published' | 'deleted' | 'archived' - `symbol` string - `tenant_id` string - `updated_at` string - `updated_by` string - `start_date` string — StartDate is the start date of the price - `status` 'published' | 'deleted' | 'archived' - `tenant_id` string - `tier_mode` 'VOLUME' | 'SLAB' - `tiers` PricePriceTier[] - `flat_amount` string — flat_amount is the flat amount for the given tier (optional) Applied on top of unit_amount*quantity. Useful for cases like "2.7$ + 5c" - `unit_amount` string — unit_amount is the amount per unit for the given tier - `up_to` integer — up_to is the quantity up to which this tier applies. It is null for the last tier. IMPORTANT: Tier boundaries are INCLUSIVE. - If up_to is 1000, then quantity less than or equal to 1000 belongs to this tier - This behavior is consistent across both VOLUME and SLAB tier modes - `transform_quantity` PriceJSONBTransformQuantity - `divide_by` integer — Divide quantity by this number - `round` 'up' | 'down' - `trial_period` integer — TrialPeriod is the number of days for the trial period Note: This is only applicable for recurring prices (BILLING_CADENCE_RECURRING) - `type` 'USAGE' | 'FIXED' - `updated_at` string - `updated_by` string - `price_id` string - `price_type` 'USAGE' | 'FIXED' - `price_unit` string - `price_unit_id` string - `quantity` string - `start_date` string - `status` 'published' | 'deleted' | 'archived' - `subscription_id` string - `subscription_phase_id` string - `tenant_id` string - `trial_period` integer - `updated_at` string - `updated_by` string - `lookup_key` string — LookupKey is the key used to lookup the subscription in our system - `metadata` TypesMetadata - `overage_factor` string — OverageFactor is a multiplier applied to usage beyond the commitment amount - `parent_subscription_id` string — ParentSubscriptionID is the parent subscription ID for hierarchy (e.g. child subscription under a parent) - `pause_status` 'none' | 'active' | 'scheduled' | 'completed' | 'cancelled' - `pauses` SubscriptionSubscriptionPause[] — Pauses are included when subscription has pause status - `created_at` string - `created_by` string - `environment_id` string — EnvironmentID is the environment identifier for the pause - `id` string — ID is the unique identifier for the subscription pause - `metadata` TypesMetadata - `original_period_end` string — OriginalPeriodEnd is the end of the billing period when the pause was created - `original_period_start` string — OriginalPeriodStart is the start of the billing period when the pause was created - `pause_end` string — PauseEnd is when the pause will end (null for indefinite) - `pause_mode` 'immediate' | 'scheduled' | 'period_end' - `pause_start` string — PauseStart is when the pause actually started - `pause_status` 'none' | 'active' | 'scheduled' | 'completed' | 'cancelled' - `reason` string — Reason is the reason for pausing - `resume_mode` 'immediate' | 'scheduled' | 'auto' - `resumed_at` string — ResumedAt is when the pause was actually ended (if manually resumed) - `status` 'published' | 'deleted' | 'archived' - `subscription_id` string — SubscriptionID is the identifier for the subscription - `tenant_id` string - `updated_at` string - `updated_by` string - `payment_behavior` string — PaymentBehavior determines how subscription payments are handled - `payment_terms` '15 NET' | '30 NET' | '45 NET' | '60 NET' | '75 NET' | '90 NET' - `phases` DtoSubscriptionPhaseResponse[] — Phases are included when "phases" is in expand parameter - `created_at` string - `created_by` string - `end_date` string — EndDate is when the phase ends (nil if phase is still active or indefinite) - `environment_id` string — EnvironmentID is the environment identifier for the phase - `id` string — ID is the unique identifier for the subscription phase - `metadata` TypesMetadata - `start_date` string — StartDate is when the phase starts - `status` 'published' | 'deleted' | 'archived' - `subscription_id` string — SubscriptionID is the identifier for the subscription - `tenant_id` string - `updated_at` string - `updated_by` string - `plan` DtoPlanResponse - `created_at` string - `created_by` string - `credit_grants` DtoCreditGrantResponse[] - `cadence` 'ONETIME' | 'RECURRING' - `conversion_rate` string — amount in the currency = number of credits * conversion_rate ex if conversion_rate is 1, then 1 USD = 1 credit ex if conversion_rate is 2, then 1 USD = 0.5 credits ex if conversion_rate is 0.5, then 1 USD = 2 credits - `created_at` string - `created_by` string - `credit_grant_anchor` string - `credits` string - `end_date` string - `environment_id` string - `expiration_duration` integer - `expiration_duration_unit` 'DAY' | 'WEEK' | 'MONTH' | 'YEAR' - `expiration_type` 'NEVER' | 'DURATION' | 'BILLING_CYCLE' - `id` string - `metadata` TypesMetadata - `name` string - `period` 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'ANNUAL' | 'QUARTERLY' | 'HALF_YEARLY' - `period_count` integer - `plan_id` string - `priority` integer - `scope` 'PLAN' | 'SUBSCRIPTION' - `start_date` string - `status` 'published' | 'deleted' | 'archived' - `subscription_id` string - `tenant_id` string - `topup_conversion_rate` string — topup_conversion_rate is the conversion rate for the topup to the currency ex if topup_conversion_rate is 1, then 1 USD = 1 credit ex if topup_conversion_rate is 2, then 1 USD = 0.5 credits ex if topup_conversion_rate is 0.5, then 1 USD = 2 credits - `updated_at` string - `updated_by` string - `description` string - `display_order` integer - `entitlements` DtoEntitlementResponse[] - `addon` DtoAddonResponse - `created_at` string - `created_by` string - `description` string - `entitlements` DtoEntitlementResponse[] - `environment_id` string - `id` string - `lookup_key` string - `metadata` object - `name` string - `prices` DtoPriceResponse[] — Optional expanded fields - `addon` DtoAddonResponse — recursive - `amount` string — Amount stored in main currency units (e.g., dollars, not cents) For USD: 12.50 means $12.50 - `billing_cadence` 'RECURRING' | 'ONETIME' - `billing_model` 'FLAT_FEE' | 'PACKAGE' | 'TIERED' - `billing_period` 'MONTHLY' | 'ANNUAL' | 'WEEKLY' | 'DAILY' | 'QUARTERLY' | 'HALF_YEARLY' - `billing_period_count` integer — BillingPeriodCount is the count of the billing period ex 1, 3, 6, 12 - `conversion_rate` string — ConversionRate is the conversion rate of the price unit to the fiat currency - `created_at` string - `created_by` string - `currency` string — Currency 3 digit ISO currency code in lowercase ex usd, eur, gbp - `description` string — Description of the price - `display_amount` string — DisplayAmount is the formatted amount with currency symbol For USD: $12.50 - `display_name` string — DisplayName is the name of the price - `display_price_unit_amount` string — DisplayPriceUnitAmount is the formatted amount of the price unit - `end_date` string — EndDate is the end date of the price - `entity_id` string — EntityID holds the value of the "entity_id" field. - `entity_type` 'PLAN' | 'SUBSCRIPTION' | 'ADDON' | 'PRICE' | 'COSTSHEET' - `environment_id` string — EnvironmentID is the environment identifier for the price - `group` DtoGroupResponse - `created_at` string - `entity_ids` string[] - `entity_type` string - `id` string - `lookup_key` string - `metadata` object - `name` string - `status` string - `updated_at` string - `group_id` string — GroupID references the group this price belongs to - `id` string — ID uuid identifier for the price - `invoice_cadence` 'ARREAR' | 'ADVANCE' - `lookup_key` string — LookupKey used for looking up the price in the database - `metadata` PriceJSONBMetadata - `meter` DtoMeterResponse - `aggregation` MeterAggregation - … - `created_at` string - `event_name` string - `filters` MeterFilter[] - … - `id` string - `name` string - `reset_usage` 'BILLING_PERIOD' | 'NEVER' - `status` string - `tenant_id` string - `updated_at` string - `meter_id` string — MeterID is the id of the meter for usage based pricing - `min_quantity` string, nullable — MinQuantity is the minimum quantity of the price - `parent_price_id` string — ParentPriceID references the root price (always set for price lineage tracking) - `plan` DtoPlanResponse — recursive - `price_unit` string — PriceUnit is the code of the price unit (e.g., 'btc', 'eth') - `price_unit_amount` string — PriceUnitAmount is the amount of the price unit - `price_unit_id` string — PriceUnitID is the id of the price unit (for CUSTOM type) - `price_unit_tiers` PricePriceTier[] — PriceUnitTiers are the tiers for the price unit when BillingModel is TIERED - `flat_amount` string — flat_amount is the flat amount for the given tier (optional) Applied on top of unit_amount*quantity. Useful for cases like "2.7$ + 5c" - `unit_amount` string — unit_amount is the amount per unit for the given tier - `up_to` integer — up_to is the quantity up to which this tier applies. It is null for the last tier. IMPORTANT: Tier boundaries are INCLUSIVE. - If up_to is 1000, then quantity less than or equal to 1000 belongs to this tier - This behavior is consistent across both VOLUME and SLAB tier modes - `price_unit_type` 'FIAT' | 'CUSTOM' - `pricing_unit` DtoPriceUnitResponse - `base_currency` string - `code` string - `conversion_rate` string - `created_at` string - `created_by` string - `environment_id` string - `id` string - `metadata` TypesMetadata - `name` string - `status` 'published' | 'deleted' | 'archived' - `symbol` string - `tenant_id` string - `updated_at` string - `updated_by` string - `start_date` string — StartDate is the start date of the price - `status` 'published' | 'deleted' | 'archived' - `tenant_id` string - `tier_mode` 'VOLUME' | 'SLAB' - `tiers` PricePriceTier[] - `flat_amount` string — flat_amount is the flat amount for the given tier (optional) Applied on top of unit_amount*quantity. Useful for cases like "2.7$ + 5c" - `unit_amount` string — unit_amount is the amount per unit for the given tier - `up_to` integer — up_to is the quantity up to which this tier applies. It is null for the last tier. IMPORTANT: Tier boundaries are INCLUSIVE. - If up_to is 1000, then quantity less than or equal to 1000 belongs to this tier - This behavior is consistent across both VOLUME and SLAB tier modes - `transform_quantity` PriceJSONBTransformQuantity - `divide_by` integer — Divide quantity by this number - `round` 'up' | 'down' - `trial_period` integer — TrialPeriod is the number of days for the trial period Note: This is only applicable for recurring prices (BILLING_CADENCE_RECURRING) - `type` 'USAGE' | 'FIXED' - `updated_at` string - `updated_by` string - `status` 'published' | 'deleted' | 'archived' - `tenant_id` string - `type` 'onetime' | 'multiple_instance' - `updated_at` string - `updated_by` string - `created_at` string - `created_by` string - `display_order` integer - `end_date` string - `entity_id` string - `entity_type` 'PLAN' | 'SUBSCRIPTION' | 'ADDON' - `environment_id` string - `feature` DtoFeatureResponse - `alert_settings` TypesAlertSettings - `alert_enabled` boolean - `critical` TypesAlertThreshold - `condition` 'above' | 'below' - `threshold` number - `info` TypesAlertThreshold - `condition` 'above' | 'below' - `threshold` number - `warning` TypesAlertThreshold - `condition` 'above' | 'below' - `threshold` number - `created_at` string - `created_by` string - `description` string - `environment_id` string - `group` DtoGroupResponse - `created_at` string - `entity_ids` string[] - `entity_type` string - `id` string - `lookup_key` string - `metadata` object - `name` string - `status` string - `updated_at` string - `group_id` string - `id` string - `lookup_key` string - `metadata` TypesMetadata - `meter` DtoMeterResponse - `aggregation` MeterAggregation - `bucket_size` 'MONTH' | 'MINUTE' | '15MIN' | '30MIN' | 'HOUR' | '3HOUR' | '6HOUR' | '12HOUR' | 'DAY' | 'WEEK' | 'MONTH' - `expression` string — Expression is an optional CEL expression to compute per-event quantity from event.properties. When set, it replaces Field-based extraction. Property names are used directly (e.g., token * duration * pixel). - `field` string — Field is the key in $event.properties on which the aggregation is to be applied For ex if the aggregation type is sum for API usage, the field could be "duration_ms" Ignored when Expression is set. - `group_by` string — GroupBy is the property name in event.properties to group by before aggregating. Currently only supported for MAX aggregation with bucket_size. When set, aggregation is applied per unique value of this property within each bucket, then the per-group results are summed to produce the bucket total. - `multiplier` string — Multiplier is the multiplier for the aggregation For ex if the aggregation type is sum_with_multiplier for API usage, the multiplier could be 1000 to scale up by a factor of 1000. If not provided, it will be null. - `type` 'COUNT' | 'SUM' | 'AVG' | 'COUNT_UNIQUE' | 'LATEST' | 'SUM_WITH_MULTIPLIER' | 'MAX' | 'WEIGHTED_SUM' - `created_at` string - `event_name` string - `filters` MeterFilter[] - `key` string — Key is the key for the filter from $event.properties Currently we support only first level keys in the properties and not nested keys - `values` string[] — Values are the possible values for the filter to be considered for the meter For ex "model_name" could have values "o1-mini", "gpt-4o" etc - `id` string - `name` string - `reset_usage` 'BILLING_PERIOD' | 'NEVER' - `status` string - `tenant_id` string - `updated_at` string - `meter_id` string - `name` string - `reporting_unit` TypesReportingUnit - `conversion_rate` number — Multiplier: reporting_unit_value = unit_value * conversion_rate; must be > 0 - `unit_plural` string — Display unit label, plural (e.g. "seconds") - `unit_singular` string — Display unit label, singular (e.g. "second") - `status` 'published' | 'deleted' | 'archived' - `tenant_id` string - `type` 'metered' | 'boolean' | 'static' - `unit_plural` string - `unit_singular` string - `updated_at` string - `updated_by` string - `feature_id` string - `feature_type` 'metered' | 'boolean' | 'static' - `id` string - `is_enabled` boolean - `is_soft_limit` boolean - `parent_entitlement_id` string - `plan` DtoPlanResponse — recursive - `plan_id` string — TODO: Remove this once we have a proper entitlement entity type - `start_date` string - `static_value` string - `status` 'published' | 'deleted' | 'archived' - `tenant_id` string - `updated_at` string - `updated_by` string - `usage_limit` integer - `usage_reset_period` 'MONTHLY' | 'ANNUAL' | 'WEEKLY' | 'DAILY' | 'QUARTERLY' | 'HALF_YEARLY' | 'NEVER' - `environment_id` string - `id` string - `lookup_key` string - `metadata` TypesMetadata - `name` string - `prices` DtoPriceResponse[] — TODO: Add inline addons - `addon` DtoAddonResponse - `created_at` string - `created_by` string - `description` string - `entitlements` DtoEntitlementResponse[] - `addon` DtoAddonResponse — recursive - `created_at` string - `created_by` string - `display_order` integer - `end_date` string - `entity_id` string - `entity_type` 'PLAN' | 'SUBSCRIPTION' | 'ADDON' - `environment_id` string - `feature` DtoFeatureResponse - `alert_settings` TypesAlertSettings - … - `created_at` string - `created_by` string - `description` string - `environment_id` string - `group` DtoGroupResponse - … - `group_id` string - `id` string - `lookup_key` string - `metadata` TypesMetadata - `meter` DtoMeterResponse - … - `meter_id` string - `name` string - `reporting_unit` TypesReportingUnit - … - `status` 'published' | 'deleted' | 'archived' - `tenant_id` string - `type` 'metered' | 'boolean' | 'static' - `unit_plural` string - `unit_singular` string - `updated_at` string - `updated_by` string - `feature_id` string - `feature_type` 'metered' | 'boolean' | 'static' - `id` string - `is_enabled` boolean - `is_soft_limit` boolean - `parent_entitlement_id` string - `plan` DtoPlanResponse — recursive - `plan_id` string — TODO: Remove this once we have a proper entitlement entity type - `start_date` string - `static_value` string - `status` 'published' | 'deleted' | 'archived' - `tenant_id` string - `updated_at` string - `updated_by` string - `usage_limit` integer - `usage_reset_period` 'MONTHLY' | 'ANNUAL' | 'WEEKLY' | 'DAILY' | 'QUARTERLY' | 'HALF_YEARLY' | 'NEVER' - `environment_id` string - `id` string - `lookup_key` string - `metadata` object - `name` string - `prices` DtoPriceResponse[] — Optional expanded fields - `status` 'published' | 'deleted' | 'archived' - `tenant_id` string - `type` 'onetime' | 'multiple_instance' - `updated_at` string - `updated_by` string - `amount` string — Amount stored in main currency units (e.g., dollars, not cents) For USD: 12.50 means $12.50 - `billing_cadence` 'RECURRING' | 'ONETIME' - `billing_model` 'FLAT_FEE' | 'PACKAGE' | 'TIERED' - `billing_period` 'MONTHLY' | 'ANNUAL' | 'WEEKLY' | 'DAILY' | 'QUARTERLY' | 'HALF_YEARLY' - `billing_period_count` integer — BillingPeriodCount is the count of the billing period ex 1, 3, 6, 12 - `conversion_rate` string — ConversionRate is the conversion rate of the price unit to the fiat currency - `created_at` string - `created_by` string - `currency` string — Currency 3 digit ISO currency code in lowercase ex usd, eur, gbp - `description` string — Description of the price - `display_amount` string — DisplayAmount is the formatted amount with currency symbol For USD: $12.50 - `display_name` string — DisplayName is the name of the price - `display_price_unit_amount` string — DisplayPriceUnitAmount is the formatted amount of the price unit - `end_date` string — EndDate is the end date of the price - `entity_id` string — EntityID holds the value of the "entity_id" field. - `entity_type` 'PLAN' | 'SUBSCRIPTION' | 'ADDON' | 'PRICE' | 'COSTSHEET' - `environment_id` string — EnvironmentID is the environment identifier for the price - `group` DtoGroupResponse - `created_at` string - `entity_ids` string[] - `entity_type` string - `id` string - `lookup_key` string - `metadata` object - `name` string - `status` string - `updated_at` string - `group_id` string — GroupID references the group this price belongs to - `id` string — ID uuid identifier for the price - `invoice_cadence` 'ARREAR' | 'ADVANCE' - `lookup_key` string — LookupKey used for looking up the price in the database - `metadata` PriceJSONBMetadata - `meter` DtoMeterResponse - `aggregation` MeterAggregation - `bucket_size` 'MONTH' | 'MINUTE' | '15MIN' | '30MIN' | 'HOUR' | '3HOUR' | '6HOUR' | '12HOUR' | 'DAY' | 'WEEK' | 'MONTH' - `expression` string — Expression is an optional CEL expression to compute per-event quantity from event.properties. When set, it replaces Field-based extraction. Property names are used directly (e.g., token * duration * pixel). - `field` string — Field is the key in $event.properties on which the aggregation is to be applied For ex if the aggregation type is sum for API usage, the field could be "duration_ms" Ignored when Expression is set. - `group_by` string — GroupBy is the property name in event.properties to group by before aggregating. Currently only supported for MAX aggregation with bucket_size. When set, aggregation is applied per unique value of this property within each bucket, then the per-group results are summed to produce the bucket total. - `multiplier` string — Multiplier is the multiplier for the aggregation For ex if the aggregation type is sum_with_multiplier for API usage, the multiplier could be 1000 to scale up by a factor of 1000. If not provided, it will be null. - `type` 'COUNT' | 'SUM' | 'AVG' | 'COUNT_UNIQUE' | 'LATEST' | 'SUM_WITH_MULTIPLIER' | 'MAX' | 'WEIGHTED_SUM' - `created_at` string - `event_name` string - `filters` MeterFilter[] - `key` string — Key is the key for the filter from $event.properties Currently we support only first level keys in the properties and not nested keys - `values` string[] — Values are the possible values for the filter to be considered for the meter For ex "model_name" could have values "o1-mini", "gpt-4o" etc - `id` string - `name` string - `reset_usage` 'BILLING_PERIOD' | 'NEVER' - `status` string - `tenant_id` string - `updated_at` string - `meter_id` string — MeterID is the id of the meter for usage based pricing - `min_quantity` string, nullable — MinQuantity is the minimum quantity of the price - `parent_price_id` string — ParentPriceID references the root price (always set for price lineage tracking) - `plan` DtoPlanResponse — recursive - `price_unit` string — PriceUnit is the code of the price unit (e.g., 'btc', 'eth') - `price_unit_amount` string — PriceUnitAmount is the amount of the price unit - `price_unit_id` string — PriceUnitID is the id of the price unit (for CUSTOM type) - `price_unit_tiers` PricePriceTier[] — PriceUnitTiers are the tiers for the price unit when BillingModel is TIERED - `flat_amount` string — flat_amount is the flat amount for the given tier (optional) Applied on top of unit_amount*quantity. Useful for cases like "2.7$ + 5c" - `unit_amount` string — unit_amount is the amount per unit for the given tier - `up_to` integer — up_to is the quantity up to which this tier applies. It is null for the last tier. IMPORTANT: Tier boundaries are INCLUSIVE. - If up_to is 1000, then quantity less than or equal to 1000 belongs to this tier - This behavior is consistent across both VOLUME and SLAB tier modes - `price_unit_type` 'FIAT' | 'CUSTOM' - `pricing_unit` DtoPriceUnitResponse - `base_currency` string - `code` string - `conversion_rate` string - `created_at` string - `created_by` string - `environment_id` string - `id` string - `metadata` TypesMetadata - `name` string - `status` 'published' | 'deleted' | 'archived' - `symbol` string - `tenant_id` string - `updated_at` string - `updated_by` string - `start_date` string — StartDate is the start date of the price - `status` 'published' | 'deleted' | 'archived' - `tenant_id` string - `tier_mode` 'VOLUME' | 'SLAB' - `tiers` PricePriceTier[] - `flat_amount` string — flat_amount is the flat amount for the given tier (optional) Applied on top of unit_amount*quantity. Useful for cases like "2.7$ + 5c" - `unit_amount` string — unit_amount is the amount per unit for the given tier - `up_to` integer — up_to is the quantity up to which this tier applies. It is null for the last tier. IMPORTANT: Tier boundaries are INCLUSIVE. - If up_to is 1000, then quantity less than or equal to 1000 belongs to this tier - This behavior is consistent across both VOLUME and SLAB tier modes - `transform_quantity` PriceJSONBTransformQuantity - `divide_by` integer — Divide quantity by this number - `round` 'up' | 'down' - `trial_period` integer — TrialPeriod is the number of days for the trial period Note: This is only applicable for recurring prices (BILLING_CADENCE_RECURRING) - `type` 'USAGE' | 'FIXED' - `updated_at` string - `updated_by` string - `status` 'published' | 'deleted' | 'archived' - `tenant_id` string - `updated_at` string - `updated_by` string - `plan_id` string — PlanID is the identifier for the plan in our system - `proration_behavior` 'create_prorations' | 'none' - `start_date` string — StartDate is the start date of the subscription - `status` 'published' | 'deleted' | 'archived' - `subscription_status` 'active' | 'paused' | 'cancelled' | 'incomplete' | 'trialing' | 'draft' - `tenant_id` string - `trial_end` string — TrialEnd is the end date of the trial period - `trial_start` string — TrialStart is the start date of the trial period - `updated_at` string - `updated_by` string - `version` integer — Version is used for optimistic locking ## Other responses - `400` — Invalid request - `500` — Server error ## Changes - **2026-04-04** `3d452eb9ebcc` — 1 info - added the optional property `customer/integrations` to the response with the `200` status - **2026-03-02** `8ab89ff34fdc` — 1 info - added the optional property `line_items/items/price/meter/aggregation/expression` to the response with the `200` status [Change history](https://skmtc.dev/flexprice/apis/flexprice-api/changes/subscriptions/:id/v2/get.md) --- [API](https://skmtc.dev/flexprice/apis/flexprice-api.md) · [All operations](https://skmtc.dev/flexprice/apis/flexprice-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/flexprice/flexprice-api/revisions/3d452eb9ebcc/schema)