Feature/stripe mrr arr models

.quickstart/quickstart.yml

@@ -16,6 +16,8 @@ table_variables:
   stripe__using_credit_notes:
     - credit_note_line_item
     - credit_note
+  stripe__using_coupons:
+    - coupon
 
   _fivetran_quickstart_account:
     - account
@@ -38,7 +40,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. If you notice any discrepencies in MRR calculations with this new model, please open up a [support ticket](https://support.fivetran.com/hc/en-us). |
+| [`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 Temp Model | | | |
+| [`stg_stripe__price_plan`](https://fivetran.github.io/dbt_stripe/#!/model/model.stripe.stg_stripe__price_plan) | Datatype casts| | `recurring_interval` field as `string`<br>`recurring_interval_count` field as `integer`<br>`price_plan_id` field as `string` | Avoids datatype errors. |
+| [`stg_stripe__subscription_item`](https://fivetran.github.io/dbt_stripe/#!/model/model.stripe.stg_stripe__subscription_item) | Datatype casts | |  `plan_id` field as `string` | Avoids datatype errors. |
+
+
+## Feature Update
+- Adds new analyses folder with 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¹: 61
 - Connector documentation
   - [Stripe connector documentation](https://fivetran.com/docs/connectors/applications/stripe)
   - [Stripe ERD](https://fivetran.com/docs/connectors/applications/stripe#schemainformation)
@@ -29,6 +29,7 @@ This dbt package transforms data from Fivetran's Stripe connector into analytics
   - [dbt Docs](https://fivetran.github.io/dbt_stripe/#!/overview)
   - [DAG](https://fivetran.github.io/dbt_stripe/#!/overview?g_v=1)
   - [Changelog](https://github.com/fivetran/dbt_stripe/blob/main/CHANGELOG.md)
+  - [Decisionlog](https://github.com/fivetran/dbt_stripe/blob/main/DECISIONLOG.md)
 
 ## What does this dbt package do?
 This package enables you to better understand your Stripe transactions, enhance balance transaction entries with useful fields, and generate metrics tables for account activity analysis. It creates enriched models with metrics focused on transaction analysis, customer insights, and revenue tracking.
@@ -57,6 +58,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 +93,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.
 
@@ -113,16 +115,17 @@ vars:
 ```
 
 ### Disable models for non-existent sources
-This package takes into consideration that not every Stripe account utilizes the `invoice`, `invoice_line_item`, `payment_method`, `payment_method_card`, `plan`, `price`, `subscription`, or `credit_note` features, and allows you to disable the corresponding functionality. By default, all variables' values are assumed to be `true` with the exception of `credit_note`. Add variables for only the tables you want to disable or enable respectively:
+This package takes into consideration that not every Stripe account utilizes the `invoice`, `invoice_line_item`, `payment_method`, `payment_method_card`, `plan`, `price`, `subscription`, `coupon`, or `credit_note` features, and allows you to disable the corresponding functionality. By default, all variables' values are assumed to be `true` with the exception of `credit_note`. Add variables for only the tables you want to disable or enable respectively:
 
 ```yml
 # dbt_project.yml
 
 ...
 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 +793,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 +1251,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>
@@ -1448,4 +1485,4 @@ We highly encourage and welcome contributions to this package. Learn how to cont
 
 ## Are there any resources available?
 - If you have questions or want to reach out for help, see the [GitHub Issue](https://github.com/fivetran/dbt_stripe/issues/new/choose) section to find the right avenue of support for you.
-- If you would like to provide feedback to the dbt package team at Fivetran or would like to request a new dbt package, fill out our [Feedback Form](https://www.surveymonkey.com/r/DQ7K7WW).
+- If you would like to provide feedback to the dbt package team at Fivetran or would like to request a new dbt package, fill out our [Feedback Form](https://www.surveymonkey.com/r/DQ7K7WW).