fivetran · fivetran-savage · Jul 21, 2026 · Jul 15, 2026 · Jul 15, 2026 · Jul 15, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,14 @@
+# dbt_stripe v1.9.0
+
+[PR #153](https://github.com/fivetran/dbt_stripe/pull/153) includes the following updates:
+
+## Schema/Data Change
+**1 total change • 1 possible breaking change**
+
+| Data Model(s) | Change type | Old | New | Notes |
+| ------------- | ----------- | --- | --- | ----- |
+| `stripe__subscription_item_mrr_report` (possible breaking change) | Changed model | Date spine starts at `current_period_start`, every month uses the current quantity, and the model runs with only `stripe__using_subscriptions`. | Date spine anchors to each item's `created_at`; historical months use the invoiced quantity (from `invoice_line_item`), the current month uses the live quantity. Now also requires `stripe__using_invoices`. | See the [DECISIONLOG](https://github.com/fivetran/dbt_stripe/blob/main/DECISIONLOG.md#mrr-history-anchored-to-each-subscription-items-creation-date). |
+
 # dbt_stripe v1.8.0
 
 [PR #152](https://github.com/fivetran/dbt_stripe/pull/152) includes the following updates:

diff --git a/DECISIONLOG.md b/DECISIONLOG.md
@@ -1,3 +1,25 @@
+## MRR History Anchored to Each Subscription Item's Creation Date
+
+The `stripe__subscription_item_mrr_report` model anchors each item's MRR timeline to that item's `created_at`, reporting MRR from when the item was added through the current month. 
+
+Because `subscription_item` retains only the current state of each item, we reconstruct historical quantity from `invoice_line_item`, which records the quantity actually billed for each period. For each month, we use the quantity from the most recent invoice line whose period overlaps that month (proration adjustment lines excluded); the current month uses the live `subscription_item` quantity. This lets the report surface real `expansion` and `contraction` between months rather than back-projecting today's quantity across all history.
+
+Because this model depends on `invoice_line_item` for historical quantity, it requires `stripe__using_invoices` (enabled by default) and does not build when that variable is disabled. Stripe generates an invoice each billing period, so gaps are not expected, but when a month has no invoice line we carry the most recent prior invoiced quantity forward rather than snapping to today's quantity (which would invent phantom changes in the gap). A month falls back to the current `subscription_item` quantity only when no earlier invoice exists (months before the first invoice). Prices are not back-filled — historical months apply the item's current price.
+
+## MRR Timeline Uses an End-of-Month Snapshot
+
+The `stripe__subscription_item_mrr_report` model keeps a month for an item only when the subscription is still active at month-end. We enforce this by truncating `current_period_end` to its month in the timeline's upper bound, so a month is kept only while its first day is before the start of the `current_period_end` month.
+
+The effect is that a subscription paid through the middle of a month is not on the books at that month's end and is considered to have churned, so MRR is not recognized for that month. For example, a monthly subscription whose last paid period runs May 15 to June 15 recognizes MRR for May (a full month) but considers June as a churned month ($0 MRR), because it has lapsed by June 30.
+
+## Stripe Subscription and Item Start-Date Fields
+
+We anchor to `subscription_item.created_at` because MRR is reported at the item grain. The relevant fields are not interchangeable:
+
+- **`subscription.start_date_at`** — Stripe's authoritative subscription start, backdate-aware, but at the subscription grain.
+- **`subscription.created_at`** — when the subscription object was created; usually equals `start_date`, but diverges on backdating or imports.
+- **`subscription_item.created_at`** — when the item was added. Stripe allows items to be added or removed mid-cycle (add-ons, seat changes, plan upgrades) and prorates by default, so this can fall later than the subscription's start. Anchoring per item attributes MRR only to the months the item existed.
+
 ## MRR Date Spine Capped at the Current Month
 
 The `stripe__subscription_item_mrr_report` model caps its date spine at the end of the current month, regardless of how far into the future a subscription's `current_period_end` extends.

diff --git a/README.md b/README.md
@@ -45,7 +45,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> |
+| [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. Relies on `invoice_line_item` for historical quantity, so it requires `stripe__using_invoices` (enabled by default) and does not build when that variable is disabled.<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`.
 
@@ -80,7 +80,7 @@ Include the following stripe package version in your `packages.yml` file:
 ```yaml
 packages:
   - package: fivetran/stripe
-    version: [">=1.8.0", "<1.9.0"]
+    version: [">=1.9.0", "<1.10.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.
 
@@ -136,9 +136,9 @@ 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_invoices:                False  #Disable if you are not using the invoice and invoice_line_item tables. Setting to False will disable  the stripe__subscription_item_mrr report as well.
     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_subscriptions:           False  #Disable if you are not using the subscription, subscription_item, and plan/price tables. Setting to False will disable the the stripe__subscription_item_mrr report as well.
     stripe__using_coupons:                 False  #Disable if you are not using coupon codes to apply discounts.
     stripe__using_subscription_discounts:  False  #Disable if you are not using the subscription_discount table.
     stripe__using_credit_notes:            True   #Enable if you are using the credit note tables.

diff --git a/analyses/README.md b/analyses/README.md
@@ -5,8 +5,8 @@
 ## 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. |
+| [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 and invoices must both 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. Subscriptions and invoices must both be enabled for this report to compile correctly.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:

diff --git a/analyses/stripe__arr_snapshot_analysis.sql b/analyses/stripe__arr_snapshot_analysis.sql
@@ -1,4 +1,4 @@
-{{ config(enabled=var('stripe__using_subscriptions', True)) }}
+{{ config(enabled=var('stripe__using_subscriptions', True) and var('stripe__using_invoices', True)) }}
 
 with mrr_by_item as (
     select *

diff --git a/analyses/stripe__customer_mrr_analysis.sql b/analyses/stripe__customer_mrr_analysis.sql
@@ -1,4 +1,4 @@
-{{ config(enabled=var('stripe__using_subscriptions', True)) }}
+{{ config(enabled=var('stripe__using_subscriptions', True) and var('stripe__using_invoices', True)) }}
 
 with item_mrr as (
     select *

diff --git a/dbt_project.yml b/dbt_project.yml
@@ -1,7 +1,7 @@
 config-version: 2
 name: 'stripe'
 
-version: '1.8.0'
+version: '1.9.0'
 require-dbt-version: [">=1.3.0", "<3.0.0"]
 
 models:

diff --git a/docs/catalog.json b/docs/catalog.json
diff --git a/docs/manifest.json b/docs/manifest.json
diff --git a/integration_tests/ci/test_scenarios.yml b/integration_tests/ci/test_scenarios.yml
@@ -48,6 +48,12 @@ test_scenarios:
       stripe__standardized_billing_model_enabled: true
     include_incremental: false
 
+  - name: "subscriptions without invoices"
+    vars:
+      stripe__using_subscriptions: true
+      stripe__using_invoices: false
+    include_incremental: false
+
   - name: "MDLS"
     vars:
       fivetran_using_source_casing: true

diff --git a/integration_tests/dbt_project.yml b/integration_tests/dbt_project.yml
@@ -2,7 +2,7 @@ config-version: 2
 
 name: 'stripe_integration_tests'
 
-version: '1.8.0'
+version: '1.9.0'
 
 profile: 'integration_tests'
 

diff --git a/models/stripe.yml b/models/stripe.yml
@@ -967,7 +967,10 @@ models:
         description: "{{ doc('source_relation') }}"
 
   - name: stripe__subscription_item_mrr_report
-    description: Each record represents a subscription item for a given month with monthly recurring revenue (MRR) metrics and movement classification. Tracks MRR changes over time, classifying each month as new, expansion, contraction, churned, reactivation, or unchanged.
+    description: >
+      Each record represents a subscription item for a given month with monthly recurring revenue (MRR) metrics and movement classification. Tracks MRR changes over time, classifying each month as new, expansion, contraction, churned, reactivation, or unchanged.
+      Reconstructs historical MRR amount changes from invoice line items and anchors each item's timeline to its creation date. Requires `stripe__using_invoices`: true to build.
+      See the [DECISIONLOG](https://github.com/fivetran/dbt_stripe/blob/main/DECISIONLOG.md) for full details.
     columns:
       - name: source_relation
         description: "{{ doc('source_relation') }}"
@@ -990,7 +993,7 @@ models:
       - name: subscription_year
         description: Year of the subscription period.
       - name: month_contract_mrr
-        description: Contracted monthly recurring revenue for this subscription item for this subscription month before discounts are applied. "{{ doc('convert_values') }}"
+        description: Contracted monthly recurring revenue for this subscription item for this subscription month before discounts are applied. Historical months use current price with historical quantity. "{{ doc('convert_values') }}"
       - name: month_discount_applied
         description: Discount amount applied to this subscription item for this month, allocated proportionally based on the item's share of the subscription's total contracted MRR. "{{ doc('convert_values') }}"
       - name: month_billed_mrr