ChartMogul Filter Language

Learn how to use the ChartMogul Filter Language (CFL) to filter data programmatically.

The ChartMogul Filter Language (CFL) is a string-based syntax for filtering data.

CFL allows you to programmatically apply the same filters that you use in the ChartMogul interface. When you apply filters in the app, the resulting CFL string appears in your browser’s address bar.

Metrics API endpoints accept an optional filters parameter that uses CFL to define filter criteria.

Syntax

CFL has the following format:

[filter]~[operator]~[value]~AND~[filter]~[operator]~[value]~AND~…

Key rules

Special case: plan filters

Plan and plan group filters have a unique behavior: when connected with the AND operator, they function as an OR condition. This behavior reflects how the filters work in the app.

Let’s take the following expression as an example:

plan~ANY~<PLAN_UUID>~AND~plan_group~ANY~<PLAN_GROUP_UUID>

Even though the filters are connected with the AND operator, a plan must match either the plan UUID OR the plan group UUID.

Operators

CFL uses the following operators:

Set operators

Comparison operators

Range operators

Containment operators

Identity operators

Review operators available for each filter.

Getting CFL from the app

The easiest way to construct a valid CFL string is to obtain it from the app:

  1. Navigate to Reports in ChartMogul.
  2. Apply your desired filters.
  3. Copy the filters parameter value from the browser address bar.
Screenshot of the MRR chart with filters applied with the value of the filters parameter highlighted in the browser address bar

Using CFL in API requests

Use CFL as the value of the optional filters parameter when calling Metrics API endpoints. The parameter is only available for cURL calls.

Either use URL-encoded CFL copied from the address bar:

curl -X GET "https://api.chartmogul.com/v1/metrics/arr" \
  -u YOUR_API_KEY: \
  -d start-date=2025-01-01 \
  -d end-date=2025-03-31 \
  -d interval=month \
  -d filters=region~ANY~%27US%27%2C%27FR%27%2C%27DE%27~AND~mrr~GT~150

Or write CFL manually (requires double quotes around the key-value pair):

curl -X GET "https://api.chartmogul.com/v1/metrics/arr" \
  -u YOUR_API_KEY: \
  -d start-date=2025-01-01 \
  -d end-date=2025-03-31 \
  -d interval=month \
  -d "filters=region~ANY~'US','FR','DE'~AND~mrr~GT~150"

Available filters

The following table lists filters that can be used in CFL expressions, along with supported operators and example values. Click a filter to open a page with its detailed description.

Paid subscription quantity active_quantity

Name in UI Name in API Operators Accepts Returns
Paid subscription quantity active_quantity BETWEEN, EQ, NOT_EQ, GT, GTE, LT, LTE Integers customer 
active_quantity~BETWEEN~0,11

Summary

  • Use the Paid subscription quantity filter to include or exclude customers based on the total quantity of their paid subscriptions.

How are reports filtered?

  • Looks at the total aggregated subscription quantity across all active (or past due) paid subscriptions belonging to a customer. Returns the entire customer if there’s a match.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

# of active subscriptions active_subscriptions

Name in UI Name in API Operators Accepts Returns
# of active subscriptions active_subscriptions BETWEEN, EQ, NOT_EQ, GT, GTE, LT, LTE Integers customer 
active_subscriptions~LT~3

Summary

  • Use the # of active subscriptions filter to include or exclude customers based on how many active paid subscriptions they have.

How are reports filtered?

  • The filter counts the number of active paid subscriptions for each customer.
  • Free subscriptions are excluded.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Average order value average_order_value

Name in UI Name in API Operators Accepts Returns
Average order value average_order_value BETWEEN, EQ, NOT_EQ, GT, GTE, LT, LTE Integers and floats customer 
average_order_value~BETWEEN~5,12.5

Summary

  • Use the Average order value filter to include or exclude customers based on their average non-recurring purchase value.

How are reports filtered?

  • Average order value is calculated as the total amount received from non-recurring (non-subscription) payments, divided by the total number of paid invoices for the customer.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Churned churned_on

Name in UI Name in API Operators Accepts Returns
Churned churned_on BETWEEN, EQ, GT, GTE, LT, LTE, IS, IS_NOT ISO 8601 dates and NULL customer 
churned_on~LT~2025-12-06

Summary

  • Use the Churned filter to include or exclude customers based on when they moved from being a paid subscriber to a canceled subscriber.

How are reports filtered?

  • A churn event occurs on the date a customer’s total MRR drops to $0.
  • If a customer has multiple paid subscriptions and only one is canceled while others remain active, this does not count as churn.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Cancellation scheduled for churning_at

Name in UI Name in API Operators Accepts Returns
Cancellation scheduled for churning_at BETWEEN, EQ, GT, GTE, LT, LTE, IS, IS_NOT ISO 8601 dates and NULL customer 
churning_at~IS_NOT~NULL

Summary

  • Use the Cancellation scheduled for filter to include or exclude customers based on when they are scheduled to fully churn.

How are reports filtered?

  • The filter applies only to customers who currently have active (or past due) paid subscriptions.
  • If a customer has multiple subscriptions and only some are scheduled to cancel, the customer is not considered scheduled to churn.
  • If all paid subscriptions are scheduled to cancel, the latest scheduled cancellation date is used.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

# of contacts contacts_count

Name in UI Name in API Operators Accepts Returns
# of contacts contacts_count BETWEEN, EQ, NOT_EQ, GT, GTE, LT, LTE Integers customer 
contacts_count~GT~1

Summary

  • Use the # of contacts filter to include or exclude customers based on how many associated contacts they have.

How are reports filtered?

  • The filter counts the number of contacts associated with each customer.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

MRR contracted contracted_on

Name in UI Name in API Operators Accepts Returns
MRR contracted contracted_on BETWEEN, EQ, GT, GTE, LT, LTE, IS, IS_NOT ISO 8601 dates and NULL customer 
contracted_on~BETWEEN~2025-01-01,2025-06-01

Summary

  • Use the MRR contracted filter to include or exclude customers based on when their total MRR decreased.

How are reports filtered?

  • The filter looks at changes in a customer’s total MRR and identifies dates on which a contraction occurred.
  • If a downgrade and an upgrade occur at the same time, the net MRR movement is used to determine whether a contraction happened.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Currency currency

Name in UI Name in API Operators Accepts Returns
Currency currency ALL, ANY, NONE Single-quoted ISO 4127 currency codes customer 
currency~ANY~'EUR','USD'

Summary

  • Use the Currency filter to include or exclude customers based on the currencies of their subscriptions.

How are reports filtered?

  • Customers are included if any of their subscriptions (active or canceled) use a currency that matches the selected criteria.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

<attribute name> custom_attribute

Name in UI Name in API Operators Accepts Returns
<attribute name> custom_attribute Type-dependent If boolean: TRUE and FALSE If date: ISO 8601 dates and NULL If float: Integers and floats If integer: Integers If string: Single-quoted strings and NULL If string array: Comma-separated single-quoted strings and NULL customer 
custom.Company_Size~IS~'Whale'

Summary

  • Use the filter to include or exclude customers based on the value of this custom attribute.

How are reports filtered?

  • The filter evaluates the customer’s custom attribute.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Customer customer

Name in UI Name in API Operators Accepts Returns
Customer customer ALL, ANY, NONE Customer UUIDs customer 
customer~ANY~cus_abc123,cus_def456

Summary

  • Use the Customer filter to include or exclude specific customers from a report.

How are reports filtered?

  • Customers are included or excluded based on whether they are explicitly selected in the filter.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Didn’t cancel within N days of purchase customer_lifetime

Name in UI Name in API Operators Accepts Returns
Didn’t cancel within N days of purchase customer_lifetime BETWEEN, EQ, NOT_EQ, GT, GTE, LT, LTE Integers customer 
customer_lifetime~LTE~2

Summary

  • Use the Didn’t cancel within N days of purchase filter to include or exclude customers who did not churn within a specified number of days after their initial paid subscription purchase.

How are reports filtered?

  • The filter measures the time between a customer’s first paid subscription purchase and any subsequent churn.
  • Customers who remain subscribed beyond the specified number of days are included.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Customer since customer_since

Name in UI Name in API Operators Accepts Returns
Customer since customer_since BETWEEN, EQ, GT, GTE, LT, LTE, IS, IS_NOT ISO 8601 dates and NULL customer 
customer_since~GT~2024-12-31

Summary

  • Use the Customer since filter to include or exclude customers based on the date they first made a payment.

How are reports filtered?

  • The filter uses the date of the customer’s first successful payment, whether from a subscription or a one-time purchase.
  • This date may be earlier than Paid subscriber since if the customer made a one-time purchase before starting a paid subscription.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Customer status customer_status

Name in UI Name in API Operators Accepts Returns
Customer status customer_status ANY, NONE Single-quoted strings with customer status values: 'new_lead', 'working_lead', 'qualified_lead', 'unqualified_lead', 'active', 'past_due' or 'cancelled' customer 
customer_status~ANY~'past_due','cancelled'

Summary

  • Use the Customer status filter to include or exclude customers based on their current status.

How are reports filtered?

  • Customer status may be a lead status (for customers who have never had a paid subscription), which can be set manually.
  • It may also be a computed subscription status, such as Active Paying Subscriber, Past Due Subscriber, or Canceled Subscriber, derived from the current state of the customer’s subscriptions.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Source data_source

Name in UI Name in API Operators Accepts Returns
Source data_source ALL, ANY, NONE Data source UUIDs customer 
data_source~NONE~ds_abc-123

Summary

  • Use the Source filter to include or exclude customers based on the data sources associated with them.

How are reports filtered?

  • The filter looks at the sources linked to the customer in ChartMogul.
  • Customers may be associated with multiple sources.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Past due date due_at

Name in UI Name in API Operators Accepts Returns
Past due date due_at BETWEEN, EQ, GT, GTE, LT, LTE, IS, IS_NOT ISO 8601 dates and NULL customer 
due_at~LT~2025-06-01

Summary

  • Use the Past due date filter to include or exclude customers based on when they became past due.

How are reports filtered?

  • If a customer has multiple past due invoices, the date of the earliest unpaid invoice is used.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

MRR expanded expanded_on

Name in UI Name in API Operators Accepts Returns
MRR expanded expanded_on BETWEEN, EQ, GT, GTE, LT, LTE, IS, IS_NOT ISO 8601 dates and NULL customer 
expanded_on~BETWEEN~2025-01-01,2025-06-01

Summary

  • Use the MRR expanded filter to include or exclude customers based on when their total MRR increased.

How are reports filtered?

  • The filter looks at changes in a customer’s total MRR and identifies dates on which an expansion occurred.
  • If a downgrade and an upgrade occur at the same time, the net MRR movement is used to determine whether an expansion happened.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Free trial started at free_trial_started_at

Name in UI Name in API Operators Accepts Returns
Free trial started at free_trial_started_at BETWEEN, EQ, GT, GTE, LT, LTE, IS, IS_NOT ISO 8601 dates and NULL customer 
free_trial_started_at~IS~NULL

Summary

  • Use the Free trial started at filter to include or exclude customers based on when their free trial began.

  • For companies that do not track free trial subscriptions in ChartMogul, this field can be set manually to represent a single trial start date per customer.
  • For companies that track free trial subscriptions in ChartMogul, this field is automatically populated using the earliest free trial start date across the customer’s subscriptions.

How are reports filtered?

  • The filter looks at the free_trial_started_at date on the customer record.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Has discount has_discount

Name in UI Name in API Operators Accepts Returns
Has discount has_discount EQ TRUE and FALSE customer 
has_discount~EQ~TRUE

Summary

  • Use the Has discount filter to include or exclude customers based on whether any of their subscriptions currently have a discount applied.

How are reports filtered?

  • Customers are included if at least one of their active subscriptions has a discount.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Has open task has_open_task

Name in UI Name in API Operators Accepts Returns
Has open task has_open_task EQ TRUE and FALSE customer 
has_open_task~EQ~FALSE

Summary

  • Use the Has open task filter to include or exclude customers based on whether they currently have any open tasks.

How are reports filtered?

  • Customers are included if they have one or more open tasks.
  • Closed tasks are not counted.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Has opportunity has_opportunity

Name in UI Name in API Operators Accepts Returns
Has opportunity has_opportunity EQ TRUE and FALSE customer 
has_opportunity~EQ~TRUE

Summary

  • Use the Has opportunity filter to include or exclude customers based on whether they have an associated opportunity.

How are reports filtered?

  • Customers are included if they have one or more associated opportunities, regardless of whether those opportunities are open or closed.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Last active at last_active_at

Name in UI Name in API Operators Accepts Returns
Last active at last_active_at BETWEEN, EQ, GT, GTE, LT, LTE, IS, IS_NOT ISO 8601 dates and NULL customer 
last_active_at~GTE~2025-12-06

Summary

  • Use the Last active at filter to include or exclude customers based on when they were last active.

How are reports filtered?

  • The filter looks at the Last active property on the customer record.
  • This date is the most recent Last active value across the customer’s associated contacts and can’t be set directly on the customer.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Last communication at last_communication_at

Name in UI Name in API Operators Accepts Returns
Last communication at last_communication_at BETWEEN, EQ, GT, GTE, LT, LTE, IS, IS_NOT ISO 8601 dates and NULL customer 
last_communication_at~IS_NOT~NULL

Summary

  • Use the Last communication at filter to include or exclude customers based on the date of their most recent communication.

How are reports filtered?

  • The filter considers emails sent or received, as well as calls logged for the customer.
  • Emails must appear in ChartMogul via email sync to be counted.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Last email received from customer at last_email_received_from_customer_at

Name in UI Name in API Operators Accepts Returns
Last email received from customer at last_email_received_from_customer_at BETWEEN, EQ, GT, GTE, LT, LTE, IS, IS_NOT ISO 8601 dates and NULL customer 
last_email_received_from_customer_at~LT~2025-01-01

Summary

  • Use the Last email received from customer at filter to include or exclude customers based on when they last sent an email.

How are reports filtered?

  • The filter looks at the most recent email received from the customer.
  • The email must appear in ChartMogul via email sync to be counted.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Last email sent to customer at last_email_sent_to_customer_at

Name in UI Name in API Operators Accepts Returns
Last email sent to customer at last_email_sent_to_customer_at BETWEEN, EQ, GT, GTE, LT, LTE, IS, IS_NOT ISO 8601 dates and NULL customer 
last_email_sent_to_customer_at~LT~2025-01-01

Summary

  • Use the Last email sent to customer at filter to include or exclude customers based on when they were last emailed.

How are reports filtered?

  • The filter looks at the most recent email sent to the customer.
  • The email does not need to have been sent from within ChartMogul, but it must be synced to ChartMogul to be counted.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Last payment last_payment

Name in UI Name in API Operators Accepts Returns
Last payment last_payment BETWEEN, EQ, GT, GTE, LT, LTE, IS, IS_NOT ISO 8601 dates and NULL customer 
last_payment~BETWEEN~2025-02-01,2025-03-01

Summary

  • Use the Last payment filter to include or exclude customers based on the date of their most recent successful payment.

How are reports filtered?

  • The filter looks at the date of the most recent successful payment made by a customer, whether for a subscription or a one-time purchase.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Lead created at lead_created_at

Name in UI Name in API Operators Accepts Returns
Lead created at lead_created_at BETWEEN, EQ, GT, GTE, LT, LTE, IS, IS_NOT ISO 8601 dates and NULL customer 
lead_created_at~GT~2024-06-01

Summary

  • Use the Lead created at filter to include or exclude customers based on when their lead record was created.

How are reports filtered?

  • The filter looks at the lead_created_at date on the customer record.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

MRR (Current) mrr

Name in UI Name in API Operators Accepts Returns
MRR (Current) mrr BETWEEN, EQ, NOT_EQ, GT, GTE, LT, LTE Integers and floats customer 
mrr~BETWEEN~1234.5,2468

Summary

  • Use the MRR (Current) filter to include or exclude customers based on their current total MRR.

How are reports filtered?

  • The filter only looks at the total MRR for each customer and does not consider the MRR of individual subscriptions.
  • For canceled and free subscribers, the current MRR is treated as $0.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

MRR (at time of purchase) mrr_at_time_of_purchase

Name in UI Name in API Operators Accepts Returns
MRR (at time of purchase) mrr_at_time_of_purchase BETWEEN, EQ, NOT_EQ, GT, GTE, LT, LTE Integers and floats customer 
mrr_at_time_of_purchase~GT~444.44

Summary

  • Use the MRR (at time of purchase) filter to include or exclude customers based on their total MRR on the day they first purchased a paid subscription.

How are reports filtered?

  • The filter only looks at the total MRR for each customer on the day of their first paid subscription purchase and does not consider the MRR of individual subscriptions.
  • Subsequent upgrades, downgrades, cancellations, or reactivations do not affect whether a customer matches this filter.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

MRR (Current, or at time of cancellation) mrr_before_churn

Name in UI Name in API Operators Accepts Returns
MRR (Current, or at time of cancellation) mrr_before_churn BETWEEN, EQ, NOT_EQ, GT, GTE, LT, LTE Integers and floats customer 
mrr_before_churn~LT~10.14

Summary

  • Use the MRR (Current, or at time of cancellation) filter to include or exclude customers based on their current total MRR, or their MRR immediately before cancellation.

When should I use this instead of the MRR (Current) filter?

This filter is generally more useful than the MRR (Current) filter when filtering any sort of time-series report. MRR (current) will generally exclude all churned subscribers, this makes it not particularly useful when used with a chart (but often more useful for filtering customer lists).

MRR (Current, or at time of cancellation) on the other hand does include churned subscribers, and therefore is a useful filter for understanding trends over time.

How are reports filtered?

  • For canceled subscribers, the filter uses the customer’s MRR immediately before cancellation, rather than $0.
  • The filter only looks at the total MRR for each customer and does not consider the MRR of individual subscriptions.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Net payments net_payments

Name in UI Name in API Operators Accepts Returns
Net payments net_payments BETWEEN, EQ, NOT_EQ, GT, GTE, LT, LTE Integers and floats customer 
net_payments~BETWEEN~1000,1234.56

Summary

  • Use the Net payments filter to include or exclude customers based on the total value of payments received, minus any refunds.

How are reports filtered?

  • The filter calculates the net total of all successful payments received from a customer, subtracting any refunds.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Next payment next_payment

Name in UI Name in API Operators Accepts Returns
Next payment next_payment BETWEEN, EQ, GT, GTE, LT, LTE, IS, IS_NOT ISO 8601 dates and NULL customer 
next_payment~IS_NOT~NULL

Summary

  • Use the Next payment filter to include or exclude customers based on the date of their next expected subscription payment.

How are reports filtered?

  • The filter looks at the next anticipated payment date across all active (or past due) paid subscriptions for a customer.
  • If a customer has multiple active paid subscriptions, the earliest upcoming payment date is used.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Owner owner

Name in UI Name in API Operators Accepts Returns
Owner owner ANY, NONE, IS, IS_NOT Integers (representing owners) and NULL customer 
owner~ANY~0,118,999,88199,9119,725

Summary

  • Use the Owner filter to include or exclude customers based on their assigned account owner.

How are reports filtered?

  • The filter looks at the customer’s current Owner property.
  • The Owner can be any staff user, admin, or CRM-only user in your ChartMogul account.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Paid subscription quantity before churn paid_quantity_before_churn

Name in UI Name in API Operators Accepts Returns
Paid subscription quantity before churn paid_quantity_before_churn BETWEEN, EQ, NOT_EQ, GT, GTE, LT, LTE Integers customer 
paid_quantity_before_churn~BETWEEN~10,20

Summary

  • Use the Paid subscription quantity before churn filter to include or exclude customers based on the total quantity of their paid subscriptions.

How are reports filtered?

  • Looks at the total aggregated subscription quantity across all paid subscriptions belonging to a customer.
  • For canceled customers, the filter uses the subscription quantity immediately before churn rather than 0.
  • This makes churn and retention analysis more meaningful than using the Paid subscription quantity filter, since churned customers are not treated as having a quantity of 0.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Paid subscriber since paid_subscriber_since

Name in UI Name in API Operators Accepts Returns
Paid subscriber since paid_subscriber_since BETWEEN, EQ, GT, GTE, LT, LTE, IS, IS_NOT ISO 8601 dates and NULL customer 
paid_subscriber_since~LT~2025-12-06

Summary

  • Use the Paid subscriber since filter to include or exclude customers based on when they first became a paid subscriber.

How are reports filtered?

  • The filter uses the earliest date on which the customer started a paid subscription.
  • Free trials, paid trials, and free subscriptions are excluded.
  • If a customer subscribes, cancels, and later subscribes again, the earliest paid subscription date is used.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Plan plan

Name in UI Name in API Operators Accepts Returns
Plan plan ALL, ANY, NONE Plan UUIDs subscription 
plan~ANY~pl_abc123,pl_def456

Summary

  • Use the Plan filter to include or exclude subscriptions based on their plan.

How are reports filtered?

  • With charts
    • For each time interval on a chart, a subscription is included or excluded if it matches the filtered plan(s) during that period.
    • If a subscription changes plan during the report's date range it may enter or exit the filtered results and contribute to the chart at different times.
    • These transitions are reflected in the data table below the chart using special rows, such as MRR/Subscribers that entered or left the segment, when applicable.
  • With customer lists
    • Returns (or excludes) customers who are currently subscribed to the selected plan(s), or who were on those plans at the time they canceled.
  • With cohorts
    • Applies the filter only to the subscription(s) used to define the starting cohort.

Operator behavior

  • The rules above apply when using the is one of and is none of operators.
  • The has all of operator always returns customers who are currently subscribed to all selected plans, regardless of where the filter is used (charts, lists, or cohorts).

Plan at time of first purchase plan_at_purchase

Name in UI Name in API Operators Accepts Returns
Plan at time of first purchase plan_at_purchase ANY, NONE Plan UUIDs customer 
plan_at_purchase~ANY~pl_abc123

Summary

  • Use the Plan at time of first purchase filter to include or exclude customers based on the plan they selected when they first became a paying subscriber.

How are reports filtered?

  • Additional plans purchased after the initial subscription purchase – or the subscription plan selected when a previously churned customer reactivates – are not considered.
  • If a customer purchases multiple plans at the same time (for example, a multi-product or multi-component subscription), the customer will match the filter if any of those plans meet the criteria.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Plan (at subscription start) plan_at_subscription_start

Name in UI Name in API Operators Accepts Returns
Plan (at subscription start) plan_at_subscription_start ALL, ANY, NONE, IS_NOT Plan UUIDs and NULL subscription 
plan_at_subscription_start~IS_NOT~pl_abc123

Summary

  • Use the Plan at subscription start filter to include or exclude subscriptions based on the plan selected when the subscription began.

How are reports filtered?

  • With charts
    • Subscriptions are included or excluded based on the plan they were on at the moment the subscription started.
    • Both free and paid subscriptions are considered.
    • If a customer starts multiple subscriptions during the report period, each subscription is evaluated independently.
  • With customer lists
    • Returns (or excludes) customers who have at least one subscription that started on the specified plan(s).
  • With cohorts
    • Applies the filter only to the subscription(s) used to define the starting cohort.

Plan during trial plan_at_trial_start

Name in UI Name in API Operators Accepts Returns
Plan during trial plan_at_trial_start ALL, ANY, NONE, IS_NOT Plan UUIDs and NULL subscription 
plan_at_trial_start~NONE~pl_abc123

Summary

  • Use the Plan during trial filter to include or exclude subscriptions based on the plan associated with a trial.

How are reports filtered?

  • With charts
    • This filter looks at the plan associated with a subscription at the time it was in a trial state.
    • Both free and paid trials are considered.
    • Customers may match the filter multiple times if they have multiple trials that meet the criteria.
  • With customer lists
    • Customers are included or excluded based on whether any of their trials match the selected plan(s).
  • With cohorts
    • Customers are included or excluded from the cohort based on whether any of their trials match the selected plan(s).

Plan (including all items in subscriptions set) plan_sub_set

Name in UI Name in API Operators Accepts Returns
Plan (including all items in subscriptions set) plan_sub_set ALL, ANY, NONE Plan UUIDs subscription 
plan_sub_set~ALL~pl_abc123,pl_def456

Summary

  • Use the Plan (including all items in subscriptions set) filter to include or exclude all subscriptions in a subscription set based on one or more specified plans.

When should I use this instead of the Plan filter?

This filter is useful when you use add-ons with plans that are shared across different base plans.

For example, using the standard Plan filter with Silver plan + Powerup addon plan will include all subscriptions with the Powerup addon plan, including those associated with a different base plan such as Gold plan.

With Plan (including all items in subscription set), you can filter by just Silver plan. The filter will then include all subscriptions (including their add-ons) that belong to the same subscription set as the Silver plan, while excluding instances of Powerup addon plan associated with other base plans.

This allows you to analyze the full economic impact of the Silver plan without including add-on revenue tied to other plans.

How are reports filtered?

  • With charts
    • For each time interval on a chart, all subscriptions in a subscription set are included (or excluded) if any subscription in that set matches the selected plan(s) during that period.
    • If a subscription set gains or loses a matching plan during the report’s date range, all subscriptions in that set may enter or leave the filtered results and contribute to the report at different times.
    • These transitions are reflected in the data table below the chart using special rows, such as MRR/Subscribers that entered or left the segment, when applicable.
  • With customer lists
    • Behaves the same as the standard Plan filter: returns (or excludes) customers who are currently subscribed to the selected plan(s), or who were on one of those plans at the time they canceled.
  • With cohorts
    • Behaves the same as the standard Plan filter: applies the filter only to the subscription(s) used to define the starting cohort.

Reactivated reactivated_on

Name in UI Name in API Operators Accepts Returns
Reactivated reactivated_on BETWEEN, EQ, GT, GTE, LT, LTE, IS, IS_NOT ISO 8601 dates and NULL customer 
reactivated_on~IS_NOT~2025-01-01

Summary

  • Use the Reactivated filter to include or exclude customers based on when they returned to being a paying subscriber.

How are reports filtered?

  • A reactivation occurs when a customer’s total MRR increases from $0 to above $0 after previously being churned.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Region region

Name in UI Name in API Operators Accepts Returns
Region region ANY, NONE, IS, IS_NOT Single-quoted strings or NULL customer 
region~ANY~'US','FR'

Summary

  • Use the Region filter to include or exclude customers based on where they’re located.

How are reports filtered?

  • A region can be a country, a state, or a custom grouping of countries and/or states.
  • Customers are included or excluded based on whether their region matches the selected criteria.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Renewal date renewal_at

Name in UI Name in API Operators Accepts Returns
Renewal date renewal_at BETWEEN, EQ, GT, GTE, LT, LTE, IS, IS_NOT ISO 8601 dates and NULL customer 
renewal_at~BETWEEN~2025-01-01,2025-06-01

Summary

  • Use the Renewal date filter to include or exclude customers based on when they are due to renew a paid subscription.

How are reports filtered?

  • The filter looks at the renewal dates of all active paid subscriptions for a customer.
  • If multiple active paid subscriptions exist, the earliest renewal date is used.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Subscriber since subscriber_since

Name in UI Name in API Operators Accepts Returns
Subscriber since subscriber_since BETWEEN, EQ, GT, GTE, LT, LTE, IS, IS_NOT ISO 8601 dates and NULL customer 
subscriber_since~GT~2024-01-01

Summary

  • Use the Subscriber since filter to include or exclude customers based on when they first became a subscriber.

How are reports filtered?

  • The filter uses the earliest date on which the customer started a subscription, whether free or paid.
  • Free and paid trials are excluded.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Number of successful payments successful_payment_count

Name in UI Name in API Operators Accepts Returns
Number of successful payments successful_payment_count BETWEEN, EQ, NOT_EQ, GT, GTE, LT, LTE Integers customer 
successful_payment_count~GTE~10

Summary

  • Use the Number of successful payments filter to include or exclude customers based on how many successful payments they have made.

How are reports filtered?

  • The filter counts the total number of successful payments made by a customer.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Tags tags

Name in UI Name in API Operators Accepts Returns
Tags tags ALL, ANY, NONE, IS, IS_NOT Single-quoted strings customer 
tags~ANY~'managed_account','churn_risk'

Summary

  • Use the Tags filter to include or exclude customers based on the tags applied to them.

How are reports filtered?

  • The filter looks at the tags currently assigned to the customer.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.

Trial-to-conversion in days trial_to_conversion_in_days

Name in UI Name in API Operators Accepts Returns
Trial-to-conversion in days trial_to_conversion_in_days BETWEEN, EQ, NOT_EQ, GT, GTE, LT, LTE Integers subscription 
trial_to_conversion_in_days~LT~30

Summary

  • Use the Trial-to-conversion in days filter to include or exclude subscriptions based on the number of days between starting a trial and converting to either a free or paid subscription.

How are reports filtered?

  • When a customer has one or more trial subscriptions, the filter works at the subscription level.
  • For each trial, the filter measures the time between the trial start date and the start date of the subscription the trial converted into, whether that subscription is free or paid.
  • If any trial-to-conversion matches the selected criteria, the corresponding subscriptions are included.
  • This filter can be combined with Plan during trial and Plan at subscription start to narrow the set of trials and subscriptions considered.
  • If a customer has no trial subscriptions, the filter falls back to customer-level data and measures the time between the customer’s free_trial_started_at date and their subscriber_since date. In this case, the filter includes or excludes the entire customer.

Trial-to-paid in days trial_to_paid_in_days

Name in UI Name in API Operators Accepts Returns
Trial-to-paid in days trial_to_paid_in_days BETWEEN, EQ, NOT_EQ, GT, GTE, LT, LTE Integers subscription 
trial_to_paid_in_days~GT~7

Summary

  • Use the Trial-to-paid in days filter to include or exclude subscriptions based on the number of days between starting a trial and starting a paid subscription.

How are reports filtered?

  • When a customer has one or more trial subscriptions, the filter evaluates those trials at the subscription level.
  • For each trial, the filter measures the time between the trial start date and the start date of the subscription that the trial converted into.
  • If any trial-to-paid conversion matches the selected criteria, both the trial subscription and the resulting paid subscription are included.
  • This filter can be combined with Plan during trial and Plan at subscription start to narrow the set of trials and subscriptions considered.
  • If a customer has no trial subscriptions, the filter falls back to customer-level data and measures the time between the customer’s free_trial_started_at date and their paid_subscriber_since date. In this case, the filter includes or excludes the entire customer.

Website website

Name in UI Name in API Operators Accepts Returns
Website website ANY, NONE Single-quoted strings and NULL customer 
website~NOT_CONTAINS~'https://'

Summary

  • Use the Website filter to include or exclude customers based on their website domain.

How are reports filtered?

  • The filter looks at the customer’s Website property.
  • ChartMogul attempts to automatically populate this field using the email domains of the customer’s associated contacts, but it can also be set manually.
  • This is a customer-level filter. Customers are either included or excluded in their entirety if they match the filter criteria.