> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt). # Subscriptions reports Generate detailed reports about your subscriptions, including status, items, billing cycle, billing dates, and customer location. --- Subscriptions reports contain information about the current state of your subscriptions, including status, items, billing cycle, billing dates, and customer location. Use them to understand the shape of your subscription base and discover actionable patterns. ## When to use - **Review your subscription base** See how subscriptions break down by status, billing cadence, currency, and country. - **Build segments to act on** Find the subscriptions that need attention, like trials that haven't converted, subscriptions with an overdue payment, or subscriptions scheduled to cancel. - **Automate reporting workflows** Generate reports via API to feed subscription data into your own dashboards and business intelligence tools. ## Report filters When generating subscriptions reports, you can filter by: | Field | Description | Use case | |-------|-------------|------------| | `subscription_status` | Filter by subscription status. Pass one or more of the following statuses: `active`, `canceled`, `past_due`, `paused`, and `trialing`. | Reporting on a single part of the base, like subscriptions with an overdue payment. | | `subscription_created_at` | Filter by the date range when subscriptions were created. Pass an RFC 3339 datetime string with a `gte` or `lt` operator, and combine two filters to scope to a specific range. If you don't pass this filter, the report includes every subscription ever created. | Reporting on subscriptions created in a specific period, or limiting the size of the report output. | | `customer_country_code` | Filter by customer country. Pass one or more two-letter ISO 3166-1 alpha-2 country codes, like `US` or `GB`. | Comparing your subscription base in specific markets. | ### How customer country is determined Paddle resolves a customer's country from the country their most recent completed subscription transaction was taxed in. Where that transaction has no tax country recorded, the country on the billing address of that transaction is used. If a subscription doesn't have any completed transactions, Paddle uses the country on the subscription's current billing address. Because of this, the customer country may differ from the subscription's current billing address. {% callout type="info" %} Subscriptions reports are updated daily and show each subscription's current state. For example, a canceled subscription is displayed with a `canceled` status, no matter what status it had while it was active. It's not possible to generate a subscriptions report for a past date. {% /callout %} ## Report columns Each row in the report is one subscription. Columns cover the details, content, and amounts of the subscription: - **Identifiers**: the subscription and the objects it's linked to, like `subscription_id`, `customer_id`, `business_id`, and `address_id`. - **Status and lifecycle**: what state the subscription is now and when it got there, like `subscription_status`, `subscription_created_at`, and `subscription_canceled_at`. - **Billing cycle**: how and when the subscription bills, like `subscription_billing_interval` and `subscription_billing_frequency`. - **Items**: what the subscription includes, like `subscription_item_count` and `subscription_total_units`. - **Trials**: how the subscription trial was set up and whether it converted, like `subscription_trial_type` and `subscription_trial_amount`. - **Amounts, discounts, and totals**: what the last cycle billed and what discounts take off it, and what the subscription has charged, refunded, and lost to chargebacks overall. Column headings on subscriptions reports mirror fields in [the Paddle API](https://developer.paddle.com/api-reference.md). Data is provided in the following columns: ```yaml title: Subscriptions report type: object properties: subscription_id: type: string pattern: ^sub_[a-z\d]{26}$ description: Unique Paddle ID for this subscription, prefixed with `sub_`. title: Subscription ID examples: - sub_01h04vsc0qhwtsbsxh3422wjs4 customer_id: type: string pattern: ^ctm_[a-z\d]{26}$ description: Paddle ID of the customer that this subscription belongs to, prefixed with `ctm_`. title: Customer ID examples: - ctm_01grnn4zta5a1mf02jjze7y2ys business_id: type: - string - "null" pattern: ^biz_[a-z\d]{26}$ description: Paddle ID of the business that this subscription is billed to, prefixed with `biz_`. `null` if this subscription isn't billed to a business. title: Business ID examples: - biz_01grrebrzaee2qj2fqqhmcyzaj address_id: type: - string - "null" pattern: ^add_[a-z\d]{26}$ description: Paddle ID of the billing address for this subscription, prefixed with `add_`. title: Address ID examples: - add_01gm302t81w94gyjpjpqypkzkf subscription_created_at: type: string format: date-time description: RFC 3339 datetime string of when this subscription was created. This is never earlier than `subscription_started_at` and can be a lot later, so use `subscription_started_at` for when a subscription began. The `subscription_created_at` filter matches on this column. title: Created at examples: - "2026-05-12T07:20:50.52Z" subscription_started_at: type: - string - "null" format: date-time description: RFC 3339 datetime string of when this subscription started. Use this rather than `subscription_created_at` for when a subscription began. The two are usually within a second of each other for a subscription that came from a checkout, and can sit years apart for an imported subscription, which was already running before it reached Paddle. title: Started at examples: - "2026-05-12T07:25:11.00Z" subscription_next_billed_at: type: - string - "null" format: date-time description: RFC 3339 datetime string of when this subscription is next scheduled to bill. title: Next billed at examples: - "2026-06-12T07:25:11.00Z" subscription_current_cycle_started_at: type: - string - "null" format: date-time description: RFC 3339 datetime string of when the current billing cycle started. title: Current cycle started at examples: - "2026-05-12T07:25:11.00Z" subscription_current_cycle_ended_at: type: - string - "null" format: date-time description: RFC 3339 datetime string of when the current billing cycle ends. title: Current cycle ended at examples: - "2026-06-12T07:25:11.00Z" subscription_trial_started_at: type: - string - "null" format: date-time description: RFC 3339 datetime string of when the trial started. `null` if this subscription never had a trial. title: Trial started at examples: - "2026-04-28T07:20:50.52Z" subscription_trial_ended_at: type: - string - "null" format: date-time description: RFC 3339 datetime string of when the trial ends. `null` if this subscription never had a trial. title: Trial ended at examples: - "2026-05-12T07:20:50.52Z" subscription_paused_at: type: - string - "null" format: date-time description: RFC 3339 datetime string of when this subscription was paused. title: Paused at subscription_canceled_at: type: - string - "null" format: date-time description: RFC 3339 datetime string of when this subscription was canceled. title: Canceled at subscription_past_due_at: type: - string - "null" format: date-time description: RFC 3339 datetime string of when this subscription became past due. title: Past due at subscription_scheduled_change_requested_at: type: - string - "null" format: date-time description: RFC 3339 datetime string of when a scheduled cancel, pause, or resume was requested, as distinct from when it takes effect. Covers the latest scheduled change only. `null` if no change is scheduled. title: Scheduled change requested at subscription_scheduled_cancellation_effective_at: type: - string - "null" format: date-time description: RFC 3339 datetime string of when a scheduled cancellation takes effect. `null` if no cancellation is scheduled. title: Scheduled cancellation effective at subscription_scheduled_pause_effective_at: type: - string - "null" format: date-time description: RFC 3339 datetime string of when a scheduled pause takes effect. `null` if no pause is scheduled. title: Scheduled pause effective at subscription_scheduled_resume_at: type: - string - "null" format: date-time description: RFC 3339 datetime string of when a paused or pausing subscription is scheduled to resume. `null` if no resume is scheduled. title: Scheduled resume at subscription_ends_at: type: - string - "null" format: date-time description: RFC 3339 datetime string of when this subscription stopped, or is scheduled to stop, being active. This is the cancellation or pause timestamp once it takes effect, otherwise the effective date of a scheduled cancellation or pause. A scheduled pause sets this even though a later resume may clear it. `null` if no end is scheduled. title: Ends at subscription_last_billed_at: type: - string - "null" format: date-time description: RFC 3339 datetime string of when this subscription's most recent paid billing cycle billed. May predate a later one-off charge, so it isn't necessarily the date of the last payment. `null` if this subscription has never billed. title: Last billed at examples: - "2026-05-12T07:25:11.00Z" subscription_status: type: string enum: - active - canceled - past_due - paused - trialing description: Current status of this subscription. A subscription that's scheduled to cancel or pause in the future is still `active`. The `subscription_status` filter takes these same values. x-enum-descriptions: active: description: Paddle is billing for this subscription and it isn't past due. canceled: description: This subscription is canceled. past_due: description: This subscription has an overdue payment. paused: description: This subscription is paused. trialing: description: This subscription is in trial. subscription_scheduled_change_action: type: - string - "null" enum: - cancel - pause - resume description: Type of change scheduled on this subscription. `null` if no change is scheduled. x-enum-descriptions: cancel: description: This subscription is scheduled to cancel. pause: description: This subscription is scheduled to pause. resume: description: This subscription is scheduled to resume. subscription_collection_mode: type: - string - "null" enum: - automatic - manual description: How payment is collected for this subscription. x-enum-descriptions: automatic: description: Paddle charges a saved payment method automatically. manual: description: Paddle invoices the customer, who pays against the invoice. subscription_origin: type: - string - "null" description: How this subscription was created, like `checkout` or `import`. This isn't a fixed set of values, so handle unrecognized values gracefully. subscription_imported_from: type: - string - "null" description: Billing system that this subscription was imported from, like `paddle_classic` or `stripe`. `null` for subscriptions created in Paddle Billing. This isn't a fixed set of values, so handle unrecognized values gracefully. subscription_cancellation_reason: type: - string - "null" description: Why this subscription was canceled, where a reason is available, like `customer_request`, `seller_request`, or `chargeback`. A reason isn't always recorded, so `null` is common even for canceled subscriptions. This isn't a fixed set of values, so handle unrecognized values gracefully. subscription_billing_interval: type: - string - "null" enum: - day - week - month - year description: Unit of this subscription's billing cadence. Read it together with `subscription_billing_frequency`, which says how many of these units each cycle spans. `null` if the billing cadence isn't an exact multiple of one of these units. x-enum-descriptions: day: description: Billing cycles are measured in days. week: description: Billing cycles are measured in weeks. month: description: Billing cycles are measured in months. year: description: Billing cycles are measured in years. subscription_billing_frequency: type: - integer - "null" description: How many `subscription_billing_interval` units each billing cycle spans. With an interval of `month`, `1` is monthly and `3` is quarterly. `null` if `subscription_billing_interval` is `null`. The two are always null together. subscription_currency_code: type: - string - "null" description: Three-letter ISO 4217 currency code that this subscription is configured to bill in. Don't use it to label the amounts in this report — read each amount's currency from the currency column that sits beside it. subscription_last_billed_currency_code: type: - string - "null" description: Three-letter ISO 4217 currency code of `subscription_last_billed_cycle_amount` and `subscription_discount_amount`. Matches `subscription_currency_code`, except for the few subscriptions whose billing currency changed after their last cycle billed. Amounts are never silently converted. `null` if this subscription has never billed. subscription_last_billed_balance_currency_code: type: - string - "null" description: Three-letter ISO 4217 currency code of `subscription_last_billed_cycle_amount_in_balance_currency` and `subscription_discount_amount_in_balance_currency` — the currency the last billed cycle actually settled in. This isn't always `balance_currency_code`, the currency you're paid out in today, because a subscription's earlier cycles can have settled in a currency you've since changed. `null` if this subscription has never billed, or if the settlement currency for that cycle couldn't be resolved. If the last billed cycle is the transaction that imported this subscription, this falls back to `balance_currency_code` instead. That applies only while that import charge is the last billed cycle — once the subscription renews on Paddle, this column resolves from that renewal instead. subscription_trial_type: type: - string - "null" enum: - none - paid - free description: Whether this subscription had a trial, and how that trial was configured. This is the trial configuration, not what was charged — for the charge, see `subscription_trial_amount`. `null` if the trial detail hasn't been processed yet, which can happen for a trial that started recently. x-enum-descriptions: none: description: This subscription never had a trial. paid: description: The trial was configured with a price above zero. free: description: The trial was configured without a price. subscription_trial_currency_code: type: - string - "null" description: Three-letter ISO 4217 currency code of `subscription_trial_amount`. `null` if `subscription_trial_amount` is `null`. subscription_trial_balance_currency_code: type: - string - "null" description: Three-letter ISO 4217 currency code of `subscription_trial_amount_in_balance_currency` — the currency the trial charge actually settled in. This can differ from `subscription_last_billed_balance_currency_code` on the same subscription, because the trial charge settled on its own, earlier date. `null` if `subscription_trial_amount` is `null`, or if the settlement currency for the trial charge couldn't be resolved. If the trial charge is the transaction that imported this subscription, this falls back to `balance_currency_code` instead. balance_currency_code: type: - string - "null" description: Three-letter ISO 4217 currency code that you're paid out in today. This is an account-level setting rather than a property of any one charge, so it isn't necessarily the currency of the amounts in this report — for those, read the `_balance_currency_code` column that sits beside each amount. One of `USD`, `GBP`, `EUR`, `CAD`, or `AUD`. Paddle can add payout currencies, so treat this as an open set. subscription_total_spend_currency_code: type: - string - "null" description: "Three-letter ISO 4217 currency code of `subscription_total_spend_gross`, `subscription_total_refunded`, `subscription_total_charged_back`, and `subscription_total_spend_net` — the single currency that all of this subscription's charges and adjustments share. This isn't always `subscription_currency_code`: a subscription whose billing currency changed keeps its earlier charges in the earlier currency, and these columns cover those too. `null` if this subscription's charges and adjustments span more than one currency, and `null` where those four columns read `0` because this subscription has none." subscription_total_spend_balance_currency_code: type: - string - "null" description: Three-letter ISO 4217 currency code of the four lifetime `_in_balance_currency` columns — the currency each charge actually settled in, not `balance_currency_code`, the currency you're paid out in today. `null` if this subscription's charges settled in more than one currency over its life, if none of them has a settlement currency Paddle could resolve, or if the four lifetime totals net to exactly `0`. customer_country_code: type: - string - "null" description: Two-letter ISO 3166-1 alpha-2 country code for the customer. Taken from the country of this subscription's most recent completed transaction, falling back to the country on its current billing address if there's no completed transaction — so it isn't always the billing address country. The `customer_country_code` filter matches on this column. examples: - US customer_email: type: - string - "null" description: Email address of the customer that this subscription belongs to. active_recurring_product_id_list: type: array items: type: string pattern: ^pro_[a-z\d]{26}$ description: Array of the distinct products on this subscription that recur and haven't been deactivated, prefixed with `pro_`. That's a property of each item rather than of the subscription, so this stays populated for nearly all canceled subscriptions and for most paused ones — read it together with `subscription_status` if you want only the subscriptions Paddle bills today. Empty where no item is both recurring and still active. active_recurring_product_name_list: type: array items: type: string description: Array of names for the products in `active_recurring_product_id_list`, in the same order and of the same length. Holds an empty string if a product has no name. active_recurring_price_id_list: type: array items: type: string pattern: ^pri_[a-z\d]{26}$ description: "Array of the distinct prices on this subscription that recur and haven't been deactivated, prefixed with `pri_`. Same item-level caveat as `active_recurring_product_id_list`: it stays populated for nearly all canceled subscriptions and for most paused ones." active_recurring_price_name_list: type: array items: type: string description: Array of names for the prices in `active_recurring_price_id_list`, in the same order and of the same length. Usually holds empty strings, because most prices have no name set. historic_product_id_list: type: array items: type: string pattern: ^pro_[a-z\d]{26}$ description: Array of every distinct product that this subscription has ever had, including the products still recurring, prefixed with `pro_`. It's a superset of `active_recurring_product_id_list`, not an addition to it. The two are identical for most subscriptions and differ if items changed. This is the only one of the two that's populated when no item is both recurring and still active. historic_product_name_list: type: array items: type: string description: Array of names for the products in `historic_product_id_list`, in the same order and of the same length. historic_price_id_list: type: array items: type: string pattern: ^pri_[a-z\d]{26}$ description: Array of every distinct price that this subscription has ever had, including the prices still recurring, prefixed with `pri_`. historic_price_name_list: type: array items: type: string description: Array of names for the prices in `historic_price_id_list`, in the same order and of the same length. discount_id_list: type: array items: type: string pattern: ^dsc_[a-z\d]{26}$ description: Array of the recurring discounts in force on this subscription right now, prefixed with `dsc_`, ordered by discount ID. Empty if no recurring discount is in force. discount_code_list: type: array items: type: string description: Array of the redemption codes for the discounts in `discount_id_list`, in the same order and of the same length. A code is optional, and a discount that you apply directly has none, so its position holds an empty string. subscription_has_converted_from_trial: type: - boolean - "null" description: Whether the trial converted, meaning this subscription billed a full cycle at or after the trial ended, whatever the amount. It records a historical event, so it stays `true` if the subscription later cancels. `false` also covers not yet converted, like a trial that's still running or a first charge after the trial that's still in flight. `null` if this subscription never had a trial, or where its trial detail hasn't been processed yet. subscription_has_chargeback: type: boolean description: Whether this subscription has ever had a chargeback. Stays `true` after a chargeback is reversed. subscription_has_refund: type: boolean description: Whether this subscription has ever had a refund. subscription_has_recurring_discount: type: boolean description: Whether a recurring discount is in force on this subscription right now, meaning still attached, recurring, and valid for the current billing cycle. This is narrower than whether the subscription has ever had a discount — it excludes a one-off discount, one that's used up its cycles, and one that hasn't started yet. subscription_item_count: type: - integer - "null" description: Number of items on this subscription, one per price that it holds, whatever their status. Items aren't units — a Pro plan plus a four-seat add-on is two items and five units. subscription_recurring_item_count: type: - integer - "null" description: Number of those items that bill every cycle, meaning recurring and not deactivated. subscription_total_units: type: - integer - "null" description: Sum of the quantities across the same items that `subscription_item_count` covers. Equals `subscription_item_count` if every item has a quantity of one, and is never lower than it. subscription_last_billed_cycle_amount: type: - string - "null" description: Amount that this subscription billed in its most recent paid cycle, excluding tax and net of discounts, in `subscription_last_billed_currency_code`. A decimal amount in the major unit of the currency, like dollars rather than cents. It reports what the last completed cycle charged, not what the subscription's current items would bill, so it can be out of date if items changed since. Excludes proration, one-off charges, and card verification charges. For a subscription that's still in a trial, the last billed cycle is the trial charge. May be negative, like where a mid-cycle downgrade prorated the cycle. `null` if this subscription has never billed. subscription_last_billed_cycle_amount_in_balance_currency: type: - string - "null" description: "`subscription_last_billed_cycle_amount` converted to `subscription_last_billed_balance_currency_code` at the rate Paddle applied when that cycle settled, not at today's rate, so the converted amount doesn't move between reports. Reads the same as `subscription_last_billed_cycle_amount` if the cycle already billed in its settlement currency. If the last billed cycle is the transaction that imported this subscription, there's no settlement record to take a rate from, so this is an estimate converted into `balance_currency_code` at the average rate for the day that cycle billed. Because that targets the currency you're paid out in today, changing your payout currency changes the estimate, and once the subscription renews on Paddle this column carries the rate that renewal settled at instead. `null` if this subscription has never billed, or if no rate could be resolved for the cycle — like a cycle covered entirely by customer credit, a negative mid-cycle proration, or a payment that hasn't settled yet." subscription_trial_amount: type: - string - "null" description: Amount that the trial charge collected, excluding tax and net of discounts, in `subscription_trial_currency_code`. A decimal amount in the major unit of the currency, like dollars rather than cents. The trial charge is the first cycle billed during the trial. A free trial normally reads `0`, which is what it charged, so use `subscription_trial_type` to tell paid trials from free ones. `null` if this subscription never had a trial, or where Paddle hasn't resolved the trial charge. subscription_trial_amount_in_balance_currency: type: - string - "null" description: "`subscription_trial_amount` converted to `subscription_trial_balance_currency_code` at the rate Paddle applied when the trial charge settled, not at today's rate. Reads the same as `subscription_trial_amount` if the trial already billed in its settlement currency. If the trial charge is the transaction that imported this subscription, this is an estimate converted into `balance_currency_code` at the average rate for the day that charge billed, which is rare, because an imported subscription almost never has a trial charge in Paddle. `null` if `subscription_trial_amount` is `null`, or if no rate could be resolved for the trial charge." subscription_discount_count: type: integer description: Number of recurring discounts in force on this subscription. `0`, not `null`, if there are none. subscription_discount_amount: type: - string - "null" description: What the recurring discount in force takes off a cycle the size of the last one billed, excluding tax, in `subscription_last_billed_currency_code`. A decimal amount in the major unit of the currency, like dollars rather than cents. This is current per-cycle exposure, not a lifetime total or an amount already collected. `null` if no recurring discount is in force, or if the basis can't be established — like a subscription that has never billed, or whose last cycle credited rather than charged. subscription_discount_amount_in_balance_currency: type: - string - "null" description: "`subscription_discount_amount` converted the same way as `subscription_last_billed_cycle_amount_in_balance_currency`, and labeled by the same currency column, `subscription_last_billed_balance_currency_code` — the discount applies to that cycle, so it shares its settlement currency and rate. `null` if `subscription_discount_amount` is `null`, or if no rate could be resolved for the cycle." subscription_successful_billing_cycles: type: integer description: Count of this subscription's successful recurring billing cycles to date. Excludes a free trial's own cycle, which bills zero or less, and isn't net of refunds or chargebacks. `0`, not `null`, if this subscription has never billed. subscription_lifetime_days: type: - integer - "null" description: Days from `subscription_started_at` to the cancellation, or to the last update for a subscription that's still active or paused. Pausing doesn't stop this count. Elapsed time only — uncapped, and not projected forward. subscription_total_refunded: type: - string - "null" description: Total amount refunded on this subscription over its lifetime, excluding tax, in `subscription_total_spend_currency_code`. A decimal amount in the major unit of the currency, like dollars rather than cents. Given as a positive amount, not a negative one. Isn't net of chargebacks — see `subscription_total_charged_back`. `0`, not `null`, if this subscription has no refunds. `null` if its charges and adjustments span more than one currency. subscription_total_refunded_in_balance_currency: type: - string - "null" description: "`subscription_total_refunded` converted to `subscription_total_spend_balance_currency_code` — the currency each refund actually settled in, not `balance_currency_code`. `0`, not `null`, if this subscription has no refunds. `null` if its charges settled in more than one currency over its life, if any one of them has no settlement currency Paddle could resolve, or, rarely, if a rate hasn't been applied yet." subscription_total_charged_back: type: - string - "null" description: Net chargeback impact on this subscription over its lifetime, excluding tax, in `subscription_total_spend_currency_code` — chargebacks, minus any that were later reversed. A decimal amount in the major unit of the currency, like dollars rather than cents. Given as a positive amount, not a negative one. May be negative for a subscription whose only chargeback activity is a reversal with no matching chargeback, and `subscription_has_chargeback` is `false` on those even though this column isn't `0`. `0`, not `null`, if this subscription has no chargebacks. `null` if its charges and adjustments span more than one currency. subscription_total_charged_back_in_balance_currency: type: - string - "null" description: "`subscription_total_charged_back` converted to `subscription_total_spend_balance_currency_code` — the currency each chargeback actually settled in, not `balance_currency_code`. `0`, not `null`, if this subscription has no chargebacks. `null` if its charges settled in more than one currency over its life, if any one of them has no settlement currency Paddle could resolve, or, rarely, if a rate hasn't been applied yet." subscription_total_spend_gross: type: - string - "null" description: Total amount this subscription has charged over its lifetime, excluding tax, in `subscription_total_spend_currency_code`. A decimal amount in the major unit of the currency, like dollars rather than cents. Includes amounts settled with customer credit. Isn't net of refunds or chargebacks — see `subscription_total_spend_net`. `0`, not `null`, if this subscription has never charged. `null` if its charges and adjustments span more than one currency. subscription_total_spend_gross_in_balance_currency: type: - string - "null" description: "`subscription_total_spend_gross` converted to `subscription_total_spend_balance_currency_code` — the currency each charge actually settled in, not `balance_currency_code`. `0`, not `null`, if this subscription has never charged. `null` if its charges settled in more than one currency over its life, if any one of them has no settlement currency Paddle could resolve, or, rarely, if a rate hasn't been applied yet." subscription_total_spend_net: type: - string - "null" description: "`subscription_total_spend_gross` minus `subscription_total_refunded` minus `subscription_total_charged_back`, excluding tax, in `subscription_total_spend_currency_code`. A decimal amount in the major unit of the currency, like dollars rather than cents. Net means net of refunds and chargebacks only: it doesn't deduct Paddle fees, payment fees, chargeback fees, or currency conversion fees. `0`, not `null`, if this subscription has never charged. `null` if its charges and adjustments span more than one currency." subscription_total_spend_net_in_balance_currency: type: - string - "null" description: "`subscription_total_spend_net` converted to `subscription_total_spend_balance_currency_code` — the currency each charge actually settled in, not `balance_currency_code`. `0`, not `null`, if this subscription has never charged. `null` if its charges settled in more than one currency over its life, if any one of them has no settlement currency Paddle could resolve, or, rarely, if a rate hasn't been applied yet." ```