Cohort Reports for WooCommerce Subscriptions

=== Cohort Reports for WooCommerce Subscriptions === Contributors: automattic Tags: woocommerce, subscriptions, analytics, cohorts, retention Requires at least: 6.4 Tested up to: 6.7 Requires PHP: 8.0 Stable tag: 1.0.0 License: GPLv2 or later License URI: https://www.gnu.org/licenses/gpl-2.0.html

Adds a Subscription Cohorts analytics report to WooCommerce Analytics.

== Description ==

Cohort Reports for WooCommerce Subscriptions adds a Subscription Cohorts report to the WooCommerce Analytics section of your WordPress dashboard. It lets you track how groups of subscribers acquired in the same period retain (or churn) over time.

Two metrics are supported:

• MRR (Monthly Recurring Revenue) — tracks how much monthly revenue a cohort retains across periods, normalised across billing frequencies (weekly, monthly, annual).
• Subscribers — tracks the headcount of active subscribers in each cohort over time.

Three display modes:

• % of original — each period shown as a percentage of the cohort's starting value.
• % of previous — each period shown as a percentage of the prior period (period-over-period change).
• Absolute — raw MRR or subscriber counts.

Filters:

• Date range and cohort interval (week / month / year)
• Subscription product
• Billing period (weekly, monthly, quarterly, annual, etc.)
• Trial start definition (subscription creation date or first payment date)
• Include or exclude the same-period column

Settings (per user):

• Deduct taxes from MRR
• Deduct shipping from MRR
• Count on-hold subscriptions as churned

A weighted average retention row is shown at the bottom of the table. Every report URL is bookmarkable — all filter state is synced to the query string.

Reports can be exported to CSV via the download button in the table header.

Requirements:

• WooCommerce 8.0 or later
• WooCommerce Subscriptions (latest stable)

== Installation ==

1. Upload the plugin folder to /wp-content/plugins/.
2. Activate the plugin through the Plugins menu in WordPress.
3. Navigate to WooCommerce → Analytics → Subscription Cohorts.

If WooCommerce or WooCommerce Subscriptions is not active, an admin notice will be shown and the menu item will not appear.

== Frequently Asked Questions ==

= What does "cohort" mean here? =

A cohort is a group of subscriptions that started (or made their first payment) within the same time period — for example, all subscriptions created in March 2024. The report shows how that group retains over subsequent periods.

= How is MRR calculated? =

MRR is derived from the _recurring_total order meta of each subscription's renewal orders, normalised to a monthly figure. A weekly subscription is multiplied by 52/12; an annual subscription is divided by 12. You can optionally exclude taxes and/or shipping from the figure in the per-user settings panel.

= What counts as "retained" vs "churned"? =

By default, subscriptions with an active or on-hold status are counted as retained. Subscriptions with a cancelled, expired, pending-cancel, or trash status are counted as churned from the period in which they reached that status. You can opt to treat on-hold as churned in the settings panel.

= Are the results cached? =

Yes. Query results are cached for one hour using WooCommerce's transient cache. The cache is invalidated whenever a subscription status changes.

= Is this compatible with HPOS (High-Performance Order Storage)? =

Yes. The underlying SQL query is HPOS-aware.

== Screenshots ==

1. The Subscription Cohorts report showing MRR retention by monthly cohort.
2. Filter bar with date range, interval, and product filters.
3. Per-user settings panel for deducting taxes, shipping, and on-hold behaviour.
4. Cell tooltip showing absolute value, percentage retained, and delta vs. prior period.

== Changelog ==

= 1.0.0 =

• Initial release.

== Upgrade Notice ==

= 1.0.0 = Initial release.