Feature/stripe mrr arr models

.quickstart/quickstart.yml

@@ -12,10 +12,13 @@ table_variables:
     - payment_method
   stripe__using_subscriptions:
     - subscription_history
+    - subscription_item
     - product
   stripe__using_credit_notes:
     - credit_note_line_item
     - credit_note
+  stripe__using_coupons:
+    - coupon
 
   _fivetran_quickstart_account:
     - account
@@ -38,7 +41,8 @@ public_models: [
   "stripe__balance_change_from_activity_itemized_3",
   "stripe__ending_balance_reconciliation_itemized_4",
   "stripe__payout_itemized_3",
-  "stripe__line_item_enhanced"
+  "stripe__line_item_enhanced",
+  "stripe__subscription_item_mrr_report"
 ]
 
 supported_vars:

CHANGELOG.md

@@ -1,3 +1,80 @@
+# dbt_stripe v1.4.0
+[PR #138](https://github.com/fivetran/dbt_stripe/pull/138) includes the following updates:
+
+## Schema/Data Change
+**3 total change • 0 possible breaking changes**
+
+| Data Model(s) | Change type | Old | New | Notes |
+| ---------- | ----------- | -------- | -------- | ----- |
+| [`stripe__subscription_item_mrr_report`](https://fivetran.github.io/dbt_stripe/#!/model/model.stripe.stripe__subscription_item_mrr_report) | New End Model | | | Each record represents a subscription item for a given month with MRR metrics for both contract and billed/net mrr, movement classification, and monthly discounts applied. Tracks MRR changes over time, classifying each month as new, expansion, contraction, churned, reactivation, or unchanged. |
+| [`stg_stripe__coupon`](https://fivetran.github.io/dbt_stripe/#!/model/model.stripe.stg_stripe__coupon) | New Staging Model | | | Staging model for Stripe coupon data. |
+| [`stg_stripe__coupon_tmp`](https://fivetran.github.io/dbt_stripe/#!/model/model.stripe.stg_stripe__coupon_tmp) | New Staging Model | | | |
+
+- Explicitly casts `recurring_interval` field from the `stg_stripe__price_plan` model as string to avoid datatype errors.
+- Explicitly casts `recurring_interval_count` field from the `stg_stripe__price_plan` model as integer to avoid datatype errors.
+
+## Feature Update
+- Adds new analyses folder with compiled SQL for advanced revenue reporting:
+ - `stripe__arr_snapshot_analysis`: Generates a high-level ARR snapshot report for the entire business for revenue forecasting.
+ - `stripe__customer_mrr_analysis`: Generates an MRR report at the customer level for retention reporting and cohort analysis.
+ - These analysis files reference the `stripe__subscription_item_mrr_report` model and can be compiled using `dbt compile` and executed directly in your data warehouse.
+
+## Documentation
+- Adds comprehensive column documentation for `stripe__subscription_item_mrr_report` in `stripe.yml`.
+- Adds README in the analysis folder with instructions on how to compile and use the analysis SQL.
+
+## Under the Hood
+- Adds consistency test for `stripe__subscription_item_mrr_report` model.
+- Updates `integration_tests/seeds/price_data.csv` with additional test data.
+- Adds `stripe__subscription_item_mrr_report` model to quickstart.yml public models list.
+
+# dbt_stripe v1.3.0-a4
+[PR #138](https://github.com/fivetran/dbt_stripe/pull/138) includes the following update:
+
+## Under the Hood
+- Removes dependency on `int_stripe__date_spine` from `stripe__subscription_item_mrr_report` so users do not need to have the account table enabled to use the MRR report.
+- Explicitly casts `recurring_interval` field as string to avoid datatype errors.
+
+# dbt_stripe v1.3.0-a3
+[PR #138](https://github.com/fivetran/dbt_stripe/pull/138) includes the following update:
+
+## Under the Hood
+- Adds docs with the updated manifest to ensure deployment of our Quickstart models.
+
+# dbt_stripe v1.3.0-a2
+[PR #138](https://github.com/fivetran/dbt_stripe/pull/138) includes the following updates:
+
+
+## Under the Hood
+- Adds `stripe__subscription_item_mrr_report` model to quickstart.yml public models list.
+
+# dbt_stripe v1.3.0-a1
+[PR #138](https://github.com/fivetran/dbt_stripe/pull/138) includes the following updates:
+
+## Schema/Data Change
+**1 total change • 0 possible breaking changes**
+
+| Data Model(s) | Change type | Old | New | Notes |
+| ---------- | ----------- | -------- | -------- | ----- |
+| [`stripe__subscription_item_mrr_report`](https://fivetran.github.io/dbt_stripe/#!/model/model.stripe.stripe__subscription_item_mrr_report) | New End Model | | | Each record represents a subscription item for a given month with MRR metrics and movement classification. Tracks MRR changes over time, classifying each month as new, expansion, contraction, churned, reactivation, or unchanged. |
+
+## Feature Update
+- Adds new analyses folder with compiled SQL for advanced revenue reporting:
+ - `stripe__arr_snapshot_analysis`: Generates a high-level ARR snapshot report for the entire business for revenue forecasting.
+ - `stripe__customer_mrr_analysis`: Generates an MRR report at the customer level for retention reporting and cohort analysis.
+ - These analysis files reference the `stripe__subscription_item_mrr_report` model and can be compiled using `dbt compile` and executed directly in your data warehouse.
+
+## Bug Fix
+- Fixes a circular reference in `stg_stripe__price_plan` where the model incorrectly references itself instead of `stg_stripe__price_plan_tmp`, causing compilation errors.
+
+## Documentation
+- Adds comprehensive column documentation for `stripe__subscription_item_mrr_report` in `stripe.yml`.
+- Adds README in the analysis folder with instructions on how to compile and use the analysis SQL.
+
+## Under the Hood
+- Adds consistency test for `stripe__subscription_item_mrr_report` model.
+- Updates `integration_tests/seeds/price_data.csv` with additional test data.
+
 # dbt_stripe v1.3.0
 
 [PR #139](https://github.com/fivetran/dbt_stripe/pull/139) includes the following updates:
@@ -24,8 +101,8 @@
 **2 total changes • 2 possible breaking changes**
 | **Data Model** | **Change type** | **Old** | **New** | **Notes** |
 | ---------------- | --------------- | ------------ | ------------ | --------- |
-| [`stg_stripe__subscription_item`](https://fivetran.github.io/dbt_stripe/#!/model/model.stripe.stg_stripe__subscription_line_item) | New Staging Model | |  | As of July 31, 2025, new Stripe connections store the subscription `current_period_start` and `current_period_end` fields in the `SUBSCRIPTION_ITEM` source table instead of in `SUBSCRIPTION_HISTORY`.|
-| [`stg_stripe__subscription_item_tmp`](https://fivetran.github.io/dbt_stripe/#!/model/model.stripe.stg_stripe__subscription_line_item_tmp) | New Staging Model | | | |
+| [`stg_stripe__subscription_item`](https://fivetran.github.io/dbt_stripe/#!/model/model.stripe.stg_stripe__subscription_item) | New Staging Model | |  | As of July 31, 2025, new Stripe connections store the subscription `current_period_start` and `current_period_end` fields in the `SUBSCRIPTION_ITEM` source table instead of in `SUBSCRIPTION_HISTORY`.|
+| [`stg_stripe__subscription_item_tmp`](https://fivetran.github.io/dbt_stripe/#!/model/model.stripe.stg_stripe__subscription_item_tmp) | New Staging Model | | | |
 | [`stripe__subscription_details`](https://fivetran.github.io/dbt_stripe/#!/model/model.stripe.stripe_subscription_details) | New Source Data | `current_period_start/end` fields sourced from `stg_stripe__subscription_history`  | `current_period_start/end` fields sourced from both `stg_stripe__subscription_history` and `stg_stripe__subscription_item`. | Fields have been coalesced to reference either table, so the package will work for all versions.|
 | [`stripe__line_item_enhanced`](https://fivetran.github.io/dbt_stripe/#!/model/model.stripe.stripe_line_item_enhanced) | New Source Data |`current_period_start/end` fields sourced from `stg_stripe__subscription_history`  |`current_period_start/end` fields sourced from both `stg_stripe__subscription_history` and `stg_stripe__subscription_item`. |Fields have been coalesced to reference either table, so the package will work for all versions. |
 

DECISIONLOG.md

@@ -0,0 +1,6 @@
+## Stripe MRR Weekly Subscription Logic
+
+We were unable to validate MRR numbers for weekly subscriptions with live data, but because Stripe does allow for weekly subscriptions, that level of granularity is included in the MRR calculation logic. If you notice any issues, please open a [github issue](https://github.com/fivetran/dbt_stripe/issues) and we will work with you to solve it.
+
+## Stripe MRR Reactivation Definition
+MRR type is defined as a reactivation only after a subscription item has at least three months of history. This helps distinguish true reactivations from short-term billing gaps, proration effects, or delayed subscription starts that are common in Stripe data. A three-month threshold reflects common SaaS analytics practice and provides a conservative, stable definition of reactivation without introducing additional configuration complexity. However, we understand that this definition may not be the right one for every user of this package and we'd love to collaborate with you. Please open up a [feature request](https://github.com/fivetran/dbt_stripe/issues/new?template=feature-request.yml) if you have ideas or suggestions as to how this should be defined.

README.md

@@ -20,7 +20,7 @@ This dbt package transforms data from Fivetran's Stripe connector into analytics
 
 ## Resources
 
-- Number of materialized models¹: 58
+- Number of materialized models¹: 59
 - Connector documentation
   - [Stripe connector documentation](https://fivetran.com/docs/connectors/applications/stripe)
   - [Stripe ERD](https://fivetran.com/docs/connectors/applications/stripe#schemainformation)
@@ -57,6 +57,7 @@ By default, this package materializes the following final tables:
 | [stripe__ending_balance_reconciliation_itemized_4](https://fivetran.github.io/dbt_stripe/#!/model/model.stripe.stripe__ending_balance_reconciliation_itemized_4) | Matches bank payouts with unsettled Stripe transactions.<br><br>**Example Analytics Questions:**<br><ul><li>Which transactions remain unsettled as of the last payout?</li><li>Do all automatic payouts reconcile fully with balance changes?</li></ul> |
 | [stripe__payout_itemized_3](https://fivetran.github.io/dbt_stripe/#!/model/model.stripe.stripe__payout_itemized_3) | Details expected and actual payout amounts and statuses.<br><br>**Example Analytics Questions:**<br><ul><li>When should I expect my next payout, and for how much?</li><li>Are there any delayed or failed payouts that need follow-up?</li></ul> |
 | [stripe__line_item_enhanced](https://fivetran.github.io/dbt_stripe/#!/model/model.stripe.stripe__line_item_enhanced) | Provides unified reporting across billing platforms on product, customer, and revenue metrics. See the [Fivetran Billing Model Streamlit App](https://fivetran-billing-model.streamlit.app/) for more details.<br><br>**Example Analytics Questions:**<br><ul><li>What are the top revenue-generating products or SKUs?</li><li>What is the average revenue per user (ARPU) by subscription plan?</li></ul> |
+| [stripe__subscription_item_mrr_report](https://fivetran.github.io/dbt_stripe/#!/model/model.stripe.stripe__subscription_item_mrr_report) | Shows both contracted and billed MRR (monthly recurring revenue) with discounts applied at the subscription item level. Tracks MRR changes over time, classifying each month as new, expansion, contraction, churned, reactivation, or unchanged.<br><br>**Example Analytics Questions:**<br><ul><li>What percentage of subscription customers are churning each month as compared to new?</li><li>How much subscription revenue was lost last year due to discounts?</li></ul> |
 
 ¹ Each Quickstart transformation job run materializes these models if all components of this data model are enabled. This count includes all staging, intermediate, and final models materialized as `view`, `table`, or `incremental`.
 
@@ -91,7 +92,7 @@ Include the following stripe package version in your `packages.yml` file:
 ```yaml
 packages:
   - package: fivetran/stripe
-    version: [">=1.3.0", "<1.4.0"]
+    version: [">=1.4.0", "<1.5.0"]
 ```
 > All required sources and staging models are now bundled into this transformation package. Do not include `fivetran/stripe_source` in your `packages.yml` since this package has been deprecated.
 
@@ -120,9 +121,10 @@ This package takes into consideration that not every Stripe account utilizes the
 
 ...
 vars:
-    stripe__using_invoices:        False  #Disable if you are not using the invoice and invoice_line_item tables
-    stripe__using_payment_method:  False  #Disable if you are not using the payment_method and payment_method_card tables
-    stripe__using_subscriptions:   False  #Disable if you are not using the subscription, and plan/price tables.
+    stripe__using_invoices:        False  #Disable if you are not using the invoice and invoice_line_item tables.
+    stripe__using_payment_method:  False  #Disable if you are not using the payment_method and payment_method_card tables.
+    stripe__using_subscriptions:   False  #Disable if you are not using the subscription, subscription_item, and plan/price tables.
+    stripe__using_coupons:         False  #Disable if you are not using coupon codes to apply discounts.
     stripe__using_credit_notes:    True   #Enable if you are using the credit note tables.
 ```
 ### (Optional) Additional configurations
@@ -790,9 +792,9 @@ sources:
           - name: livemode
             description: Indicates if this is a test invoice.
           - name: period_start
-            description: Start of the usage period during for which the invoice was created.
+            description: Start of the usage period for which the invoice was created.
           - name: period_end
-            description: End of the usage period during for which the invoice was created.
+            description: End of the usage period for which the invoice was created.
           - name: default_payment_method_id
             description: ID of the default payment method in this invoice.
           - name: payment_intent_id
@@ -1248,6 +1250,40 @@ sources:
             description: The date that the coupon was applied.
           - name: subscription_id
             description: The subscription that this coupon is applied to, if it is applied to a particular subscription.
+
+
+        - name: coupon
+        identifier: "{{ var('stripe_coupon_identifier', 'coupon') }}"
+        description: A coupon represents a discount that can be applied to a subscription or invoice. It contains information about the coupon's duration, amount, and applicability.
+        config:
+          freshness: null
+        columns:
+          - name: id
+            description: The ID of the coupon.
+          - name: amount_off
+            description: The amount taken off the total price in the selected currency.
+          - name: created
+            description: Time at which the object was created.
+          - name: currency
+            description: Three-letter ISO currency code, in lowercase.
+          - name: duration
+            description: The duration of the coupon. Typically "forever," "once," or "repeating."
+          - name: duration_in_months
+            description: If the coupon does not last forever, the duration in months you can apply it. For a forever coupon, this attribute is null.
+          - name: livemode
+            description: Indicates whether the coupon is in live mode or test mode.
+          - name: max_redemptions
+            description: The maximum number of times this coupon can be redeemed.
+          - name: name
+            description: Name of the coupon or promotion.
+          - name: percent_off
+            description: The percentage taken off the total price.
+          - name: redeem_by
+            description: The date by which the coupon must be redeemed.
+          - name: times_redeemed
+            description: The number of times this coupon has been redeemed.
+          - name: valid
+            description: Indicates whether the coupon can still be applied to a customer.
 ```
 
 </details>

analyses/README.md

@@ -0,0 +1,21 @@
+# Stripe Analyses
+> Note: The compiled SQL within the analyses folder references the [stripe__subscription_item_mrr_report](https://github.com/fivetran/dbt_stripe/blob/master/models/stripe_financial_reports/stripe__subscription_item_mrr_report.sql) model. You must execute `dbt run` before compiling the analysis SQL.
+
+
+## Analysis SQL
+| **SQL**                | **Description**                                                                                                                                |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| [stripe__arr_snapshot_analysis](https://github.com/fivetran/dbt_stripe/blob/master/analyses/stripe__arr_snapshot_analysis.sql) | This analysis generates a high-level ARR snapshot report for your business that you can use for revenue forecasting. The analysis provides year-end ARR metrics by aggregating MRR data from the last month of each calendar year and multiplying by 12. The SQL references the `stripe__subscription_item_mrr_report` model and aggregates metrics by currency. Subscriptions must be enabled for this report to compile correctly. |
+| [stripe__customer_mrr_analysis](https://github.com/fivetran/dbt_stripe/blob/master/analyses/stripe__customer_mrr_analysis.sql) | This analysis generates an MRR report at the customer level that you can use for retention reporting and cohort analysis. The analysis aggregates monthly recurring revenue by customer and month, providing insights into customer-level revenue trends over time. The SQL references the `stripe__subscription_item_mrr_report` model. You can also generate this report at the overall business level by removing the customer_id field from the aggregation. |
+
+## SQL Compile Instructions
+You can leverage the above SQL using the [analysis functionality of dbt](https://docs.getdbt.com/docs/building-a-dbt-project/analyses/). To compile the SQL, perform the following steps:
+- Execute `dbt run` to create the package models.
+- Execute `dbt compile` to generate the target-specific SQL.
+- Navigate to your project's `/target/compiled/stripe/analyses` directory.
+- Copy the desired analysis code (`stripe__arr_snapshot_analysis` or `stripe__customer_mrr_analysis`) and run it in your data warehouse.
+- Confirm the revenue metrics match your expected subscription and billing patterns.
+- Analyze the ARR snapshots and customer-level MRR trends to identify growth opportunities, retention patterns, and revenue forecasting insights.
+
+## Contributions
+Don't see a compiled SQL statement you'd like to include? Notice any bugs when compiling and running the analysis SQL? If so, we highly encourage and welcome contributions to this package! If interested, the best first step is [opening a feature request](https://github.com/fivetran/dbt_stripe/issues/new?template=feature-request.yml).