--- title: "Get usage by subscription" method: POST path: "/subscriptions/usage" tags: ["Subscriptions"] --- # Get usage by subscription `POST /subscriptions/usage` Use when showing usage for a subscription (e.g. in a portal or for overage checks). Supports time range and filters. ## Request body - GetUsageBySubscriptionRequest - `end_time` string, date-time - `lifetime_usage` boolean - `start_time` string, date-time - `subscription_id` string, required ## Response `200` OK - GetUsageBySubscriptionResponse - `amount` number - `charges` SubscriptionUsageByMetersResponse[] - `amount` number - `currency` string - `display_amount` string - `filter_values` PriceJSONBFilters - `is_overage` boolean — Whether this charge is at overage rate - `meter_display_name` string - `meter_id` string - `overage_factor` number — Factor applied to this charge if in overage - `price` PricePrice - `amount` string — Amount stored in main currency units (e.g., dollars, not cents) For USD: 12.50 means $12.50 - `billing_cadence` 'RECURRING' - `billing_model` 'FLAT_FEE' | 'PACKAGE' | 'TIERED' - `billing_period` 'MONTHLY' | 'ANNUAL' | 'WEEKLY' | 'DAILY' | 'QUARTERLY' | 'HALF_YEARLY' | 'ONETIME' - `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, date-time - `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, date-time — 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_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_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) - `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' - `sequence` integer — Sequence is the monotonic stamp bumped on every state change that subscription line items need to react to. Read by the plan-price sync; set by the database (DEFAULT nextval) on create and by the price repository on termination / compatibility-affecting edits. - `start_date` string, date-time — 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_days` integer — TrialPeriodDays 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, date-time - `updated_by` string - `quantity` number - `subscription_line_item_id` string — For feature_usage: direct match by sub_line_item_id - `commitment_amount` number - `commitment_utilized` number — Amount of commitment used - `currency` string - `display_amount` string - `end_time` string, date-time - `has_overage` boolean — Whether any usage exceeded commitment - `overage_amount` number — Amount charged at overage rate - `overage_factor` number - `start_time` string, date-time ## Other responses - `400` — Invalid request - `500` — Server error --- [API](https://skmtc.net/flexprice/apis/flexprice-api-2.md) · [All operations](https://skmtc.net/flexprice/apis/flexprice-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/flexprice/flexprice-api-2/versions/da8f268dc77d/schema)