Stripe Subscription Data for Planning

How to map Stripe subscription, invoice, and customer data into planning dimensions for MRR, churn, and revenue forecasting.

Overview

Stripe subscription data is one of the most valuable inputs for SaaS revenue planning. VersionForge extracts customers, subscriptions, invoices, products, and prices from Stripe and maps them into the dimensional structure your planning tool expects. This guide explains the Stripe data model from a planning perspective and how to configure field mappings for common use cases.

MRR Calculation from Subscriptions

Monthly Recurring Revenue (MRR) is the foundation of SaaS financial planning. VersionForge calculates MRR from Stripe subscription data using these fields:

| Stripe Field | Extracted As | MRR Role | |---|---|---| | items.data[0].price.unit_amount | items_data_0_price_unit_amount | Per-unit price in cents | | items.data[0].quantity | items_data_0_quantity | Number of units (seats, licenses) | | items.data[0].price.recurring.interval | items_data_0_price_recurring_interval | Billing frequency (month, year) | | status | status | Active, trialing, past_due, canceled | | current_period_start | current_period_start | Period start for MRR attribution | | current_period_end | current_period_end | Period end for MRR attribution |

MRR formula: For monthly subscriptions, MRR equals unit_amount * quantity / 100 (converting cents to dollars). For annual subscriptions, divide by 12.

VersionForge performs the MRR normalization in the transform layer. You do not need to write custom formulas -- configure the billing interval mapping and VersionForge handles the monthly normalization automatically.

Invoice Line Items

For granular revenue recognition, invoice line items provide the most precise data. Each invoice contains one or more line items, each tied to a subscription item, a price, and a billing period.

Key invoice fields for planning:

| Field | Planning Use | |---|---| | amount_due | Total invoice amount for cash flow forecasting | | amount_paid | Realized revenue for actuals reporting | | status | Invoice lifecycle: draft, open, paid, void, uncollectible | | subscription | Links the invoice to a subscription for cohort analysis | | period_start / period_end | Revenue recognition period | | lines.data[].amount | Per-line-item revenue for product-level breakdown |

Customer Metadata for Dimensions

Stripe customer metadata is a powerful tool for adding planning dimensions that do not exist natively in Stripe. Common metadata fields that FP&A teams use:

industry -- for revenue segmentation by vertical
region or country -- for geographic revenue breakdown
account_manager -- for sales team performance analysis
plan_tier -- for pricing tier analysis (Starter, Growth, Enterprise)
company_size -- for cohort analysis by customer segment

VersionForge extracts all metadata fields and flattens them into the record. For example, metadata.industry becomes the field metadata_industry, which you can map to a planning dimension like "Industry Segment".

{
  "columnMapping": {
    "metadata_industry": "Industry",
    "metadata_region": "Region",
    "metadata_plan_tier": "Plan Tier"
  }
}

Mapping Stripe Data to Planning Dimensions

A typical Stripe-to-planning dimension mapping:

| Planning Dimension | Stripe Source | Notes | |---|---|---| | Product | product.name or price.product | Group by product for revenue mix analysis | | Plan/Tier | price.nickname or metadata.plan_tier | Monthly vs Annual, Starter vs Enterprise | | Customer Segment | metadata.company_size or metadata.industry | Requires customer metadata to be populated | | Geography | Customer address or metadata.region | Use billing address country for tax compliance | | Period | current_period_start | Month-year for time-series alignment | | Currency | currency | Multi-currency support for international billing |

Churn and Retention Analysis

Canceled subscriptions are critical for churn modeling. VersionForge extracts subscriptions with status=all, which includes:

active -- currently paying subscriptions (positive MRR)
trialing -- free trial, potential future MRR
past_due -- payment failed, at risk of involuntary churn
canceled -- churned subscriptions (MRR loss)
unpaid -- subscription paused due to non-payment

Use the canceled_at and cancel_at_period_end fields to distinguish between immediate cancellations and end-of-period cancellations. This distinction matters for churn timing in your planning model.

Stripe marks subscriptions as canceled only after the cancellation takes effect. If a customer cancels mid-cycle but the subscription runs until the period end, the status remains active with cancel_at_period_end=true until the period ends.

Putting It Together

A complete Stripe-to-Pigment sync profile for revenue planning might look like:

{
  "source": {
    "connector": "stripe",
    "objectType": "subscription",
    "filters": { "since": "2025-01-01T00:00:00Z" }
  },
  "target": {
    "connector": "pigment",
    "importConfigId": "cfg_revenue_plan",
    "importMode": "upsert"
  },
  "transform": {
    "mrrNormalization": true,
    "billingIntervalField": "items_data_0_price_recurring_interval",
    "amountField": "items_data_0_price_unit_amount",
    "amountDivisor": 100
  }
}

This extracts all subscriptions created since January 2025, normalizes annual amounts to monthly, converts cents to dollars, and pushes the result to Pigment for revenue forecasting.