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.
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.
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, andaddress_id. - Status and lifecycle: what state the subscription is now and when it got there, like
subscription_status,subscription_created_at, andsubscription_canceled_at. - Billing cycle: how and when the subscription bills, like
subscription_billing_intervalandsubscription_billing_frequency. - Items: what the subscription includes, like
subscription_item_countandsubscription_total_units. - Trials: how the subscription trial was set up and whether it converted, like
subscription_trial_typeandsubscription_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. Data is provided in the following columns:
subscription_idstring
Example:
sub_01h04vsc0qhwtsbsxh3422wjs4Unique Paddle ID for this subscription, prefixed with
sub_.Pattern:
^sub_[a-z\d]{26}$customer_idstring
Example:
ctm_01grnn4zta5a1mf02jjze7y2ysPaddle ID of the customer that this subscription belongs to, prefixed with
ctm_.Pattern:
^ctm_[a-z\d]{26}$business_idstring | null
Example:
biz_01grrebrzaee2qj2fqqhmcyzajPaddle ID of the business that this subscription is billed to, prefixed with
biz_. null if this subscription isn't billed to a business.Pattern:
^biz_[a-z\d]{26}$address_idstring | null
Example:
add_01gm302t81w94gyjpjpqypkzkfPaddle ID of the billing address for this subscription, prefixed with
add_.Pattern:
^add_[a-z\d]{26}$subscription_created_atstring (date-time)
Example:
2026-05-12T07:20:50.52ZRFC 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.subscription_started_atstring (date-time) | null
Example:
2026-05-12T07:25:11.00ZRFC 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.subscription_next_billed_atstring (date-time) | null
Example:
2026-06-12T07:25:11.00ZRFC 3339 datetime string of when this subscription is next scheduled to bill.
subscription_current_cycle_started_atstring (date-time) | null
Example:
2026-05-12T07:25:11.00ZRFC 3339 datetime string of when the current billing cycle started.
subscription_current_cycle_ended_atstring (date-time) | null
Example:
2026-06-12T07:25:11.00ZRFC 3339 datetime string of when the current billing cycle ends.
subscription_trial_started_atstring (date-time) | null
Example:
2026-04-28T07:20:50.52ZRFC 3339 datetime string of when the trial started.
null if this subscription never had a trial.subscription_trial_ended_atstring (date-time) | null
Example:
2026-05-12T07:20:50.52ZRFC 3339 datetime string of when the trial ends.
null if this subscription never had a trial.subscription_paused_atstring (date-time) | null
RFC 3339 datetime string of when this subscription was paused.
subscription_canceled_atstring (date-time) | null
RFC 3339 datetime string of when this subscription was canceled.
subscription_past_due_atstring (date-time) | null
RFC 3339 datetime string of when this subscription became past due.
subscription_scheduled_change_requested_atstring (date-time) | null
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.subscription_scheduled_cancellation_effective_atstring (date-time) | null
RFC 3339 datetime string of when a scheduled cancellation takes effect.
null if no cancellation is scheduled.subscription_scheduled_pause_effective_atstring (date-time) | null
RFC 3339 datetime string of when a scheduled pause takes effect.
null if no pause is scheduled.subscription_scheduled_resume_atstring (date-time) | null
RFC 3339 datetime string of when a paused or pausing subscription is scheduled to resume.
null if no resume is scheduled.subscription_ends_atstring (date-time) | null
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.subscription_last_billed_atstring (date-time) | null
Example:
2026-05-12T07:25:11.00ZRFC 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.subscription_statusstring
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.Values
activePaddle is billing for this subscription and it isn't past due.canceledThis subscription is canceled.past_dueThis subscription has an overdue payment.pausedThis subscription is paused.trialingThis subscription is in trial.
subscription_scheduled_change_actionstring | null
Type of change scheduled on this subscription.
null if no change is scheduled.Values
cancelThis subscription is scheduled to cancel.pauseThis subscription is scheduled to pause.resumeThis subscription is scheduled to resume.
subscription_collection_modestring | null
How payment is collected for this subscription.
Values
automaticPaddle charges a saved payment method automatically.manualPaddle invoices the customer, who pays against the invoice.
subscription_originstring | null
How this subscription was created, like
checkout or import. This isn't a fixed set of values, so handle unrecognized values gracefully.subscription_imported_fromstring | null
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_reasonstring | null
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_intervalstring | null
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.Values
dayBilling cycles are measured in days.weekBilling cycles are measured in weeks.monthBilling cycles are measured in months.yearBilling cycles are measured in years.
subscription_billing_frequencyinteger | null
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_codestring | null
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_codestring | null
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_codestring | null
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_typestring | null
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.Values
noneThis subscription never had a trial.paidThe trial was configured with a price above zero.freeThe trial was configured without a price.
subscription_trial_currency_codestring | null
Three-letter ISO 4217 currency code of
subscription_trial_amount. null if subscription_trial_amount is null.subscription_trial_balance_currency_codestring | null
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_codestring | null
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_codestring | null
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_codestring | null
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_codestring | null
Example:
USTwo-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.customer_emailstring | null
Email address of the customer that this subscription belongs to.
active_recurring_product_id_listarray
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_listarray
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_listarray
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_listarray
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_listarray
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_listarray
Array of names for the products in
historic_product_id_list, in the same order and of the same length.historic_price_id_listarray
Array of every distinct price that this subscription has ever had, including the prices still recurring, prefixed with
pri_.historic_price_name_listarray
Array of names for the prices in
historic_price_id_list, in the same order and of the same length.discount_id_listarray
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_listarray
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_trialboolean | null
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_chargebackboolean
Whether this subscription has ever had a chargeback. Stays
true after a chargeback is reversed.subscription_has_refundboolean
Whether this subscription has ever had a refund.
subscription_has_recurring_discountboolean
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_countinteger | null
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_countinteger | null
Number of those items that bill every cycle, meaning recurring and not deactivated.
subscription_total_unitsinteger | null
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_amountstring | null
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_currencystring | null
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_amountstring | null
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_currencystring | null
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_countinteger
Number of recurring discounts in force on this subscription.
0, not null, if there are none.subscription_discount_amountstring | null
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_currencystring | null
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_cyclesinteger
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_daysinteger | null
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_refundedstring | null
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_currencystring | null
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_backstring | null
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_currencystring | null
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_grossstring | null
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_currencystring | null
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_netstring | null
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_currencystring | null
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.