Stripe Subscription Upgrades: How to Sync Prorated Charges to HubSpot?

TL;DR — Stripe Upgrade → HubSpot Revenue Sync

• Listen to invoice.payment_succeeded, not customer.subscription.updated. The subscription event fires before payment is confirmed. The invoice event fires after money has changed hands and gives you the invoice object to verify what was charged.
• Never use the invoice total as the new MRR. The invoice total is the prorated charge for the upgrade — a fraction of a month. MRR comes from the subscription’s current price after the upgrade: subscription.items.data[0].price.unit_amount / 100.
• Calculate the MRR delta explicitly from the subscription’s previous and current plan prices, not from invoice arithmetic. Stripe’s customer.subscription.updated event includes previous_attributes — store this when it fires so the subsequent invoice handler has access to the before state.
• In HubSpot, write to custom MRR properties (mrr_current, mrr_previous, last_upgrade_date, upgrade_mrr_delta) rather than updating amount directly. Create a note with the Stripe invoice ID and the MRR change for audit trail. The deal’s amount field can then reflect current MRR without historical data being overwritten.

⚠ What Needs to Be in Place First

This pattern assumes: Stripe customers are linked to HubSpot contacts via a stored stripe_customer_id metadata field on the HubSpot contact, HubSpot deals are associated with those contacts and represent active subscriptions, and your webhook endpoint already handles HMAC verification (covered separately). Without the Stripe customer → HubSpot contact link, finding the right deal to update requires an additional lookup step that can fail if the mapping is missing.

Stripe proration math — $60/month → $120/month on day 18 of 30

Days remaining in cycle  = 30 - 18 = 12 days
Days in full cycle       = 30 days
Proration fraction       = 12 / 30 = 0.40

Credit for unused old plan  = $60.00 × 0.40 = $24.00  (negative line item)
Charge for new plan time    = $120.00 × 0.40 = $48.00  (positive line item)

Net invoice total           = $48.00 - $24.00 = $24.00

# ❌ Wrong: Store $24 as the new MRR in HubSpot
# ✅ Correct: MRR increased by $60/month. New MRR is $120/month.

# The prorated charge ($24) tells you WHAT WAS BILLED this cycle.
# The subscription's current price tells you MRR.

Webhook handler — both events, correct sequencing

import stripe
import json
from flask import Flask, request
from datetime import datetime

app = Flask(__name__)

# Temporary store for subscription state transitions
# In production: use Redis or a database table, not an in-process dict
pending_upgrades = {}

@app.route("/webhooks/stripe", methods=["POST"])
def stripe_webhook():
    payload = request.get_data()
    sig_header = request.headers.get("Stripe-Signature")

    try:
        event = stripe.Webhook.construct_event(
            payload, sig_header, STRIPE_WEBHOOK_SECRET
        )
    except stripe.error.SignatureVerificationError:
        return "Unauthorized", 401

    if event["type"] == "customer.subscription.updated":
        handle_subscription_updated(event["data"])

    elif event["type"] == "invoice.payment_succeeded":
        handle_invoice_paid(event["data"]["object"])

    return "OK", 200


def handle_subscription_updated(data: dict):
    """
    Store previous plan price so invoice handler can compute MRR delta.
    Only store upgrade events (amount increased).
    """
    subscription = data["object"]
    previous = data.get("previous_attributes", {})

    if "items" not in previous:
        return  # Plan didn't change — nothing to store

    sub_id = subscription["id"]
    current_items = subscription["items"]["data"]
    prev_items = previous.get("items", {}).get("data", [])

    if not prev_items:
        return

    old_unit_amount = prev_items[0]["price"]["unit_amount"]
    new_unit_amount = current_items[0]["price"]["unit_amount"]

    if new_unit_amount <= old_unit_amount:
        return  # Downgrade or no change — handle separately if needed

    # Store the transition keyed by subscription ID
    pending_upgrades[sub_id] = {
        "old_plan_id":      prev_items[0]["price"]["id"],
        "old_unit_amount":  old_unit_amount,   # In cents
        "old_interval":     prev_items[0]["price"]["recurring"]["interval"],
        "new_plan_id":      current_items[0]["price"]["id"],
        "new_unit_amount":  new_unit_amount,
        "new_interval":     current_items[0]["price"]["recurring"]["interval"],
        "customer_id":      subscription["customer"],
        "stored_at":        datetime.utcnow().isoformat(),
    }


def handle_invoice_paid(invoice: dict):
    """
    Confirmed payment received. Compute real MRR and update HubSpot.
    """
    # Only process invoices with proration line items
    has_proration = any(
        line.get("proration") for line in invoice["lines"]["data"]
    )
    if not has_proration:
        return

    sub_id = invoice.get("subscription")
    if not sub_id or sub_id not in pending_upgrades:
        return  # No pending upgrade stored for this subscription

    upgrade_data = pending_upgrades.pop(sub_id)  # Remove from store
    process_upgrade_sync(invoice, upgrade_data)

MRR calculation — normalize by billing interval

def unit_amount_to_monthly_mrr(unit_amount_cents: int, interval: str) -> float:
    """
    Convert Stripe price unit_amount (in cents) to monthly MRR (in dollars).

    Stripe intervals: "day", "week", "month", "year"
    For simplicity this covers month/year — add day/week if your plans use them.
    """
    amount_dollars = unit_amount_cents / 100

    if interval == "month":
        return amount_dollars
    elif interval == "year":
        return amount_dollars / 12
    elif interval == "week":
        return amount_dollars * 52 / 12
    elif interval == "day":
        return amount_dollars * 365 / 12
    else:
        raise ValueError(f"Unknown billing interval: {interval}")


def process_upgrade_sync(invoice: dict, upgrade_data: dict):
    old_mrr = unit_amount_to_monthly_mrr(
        upgrade_data["old_unit_amount"],
        upgrade_data["old_interval"]
    )
    new_mrr = unit_amount_to_monthly_mrr(
        upgrade_data["new_unit_amount"],
        upgrade_data["new_interval"]
    )
    mrr_delta = new_mrr - old_mrr

    # Verify against the invoice proration math (sanity check only — don't use
    # invoice amounts to derive MRR)
    proration_lines = [l for l in invoice["lines"]["data"] if l.get("proration")]
    net_proration_cents = sum(l["amount"] for l in proration_lines)
    net_proration_dollars = net_proration_cents / 100

    # Expected proration from cycle timing
    period = proration_lines[0]["period"]
    days_remaining = (period["end"] - invoice["created"]) / 86400
    days_in_cycle = (period["end"] - period["start"]) / 86400
    expected_proration = mrr_delta * (days_remaining / days_in_cycle)

    # If actual vs expected differ by more than $1, log for investigation
    if abs(net_proration_dollars - expected_proration) > 1.00:
        print(
            f"WARNING: Proration mismatch on {invoice['id']}. "
            f"Expected ${expected_proration:.2f}, "
            f"got ${net_proration_dollars:.2f}. "
            f"May indicate multi-item subscription or coupon."
        )

    # Proceed with the MRR-based update regardless
    update_hubspot_deal(
        customer_id=upgrade_data["customer_id"],
        old_mrr=old_mrr,
        new_mrr=new_mrr,
        mrr_delta=mrr_delta,
        invoice_id=invoice["id"],
        upgrade_date=datetime.utcfromtimestamp(invoice["created"]).isoformat()
    )

Stripe doesn’t include previous plan data on invoice.payment_succeeded. The invoice tells you what was billed; it doesn’t tell you what changed from. To know the old plan price, you either have to listen to customer.subscription.updated first and store the previous state yourself, or make a second API call to retrieve the subscription’s price history — which Stripe doesn’t expose directly and requires reconstructing from event logs. This forces every developer building upgrade-sync logic to maintain their own state machine for subscription transitions, even though Stripe already computed and stored exactly this information to generate the invoice in the first place.

HubSpot deal update — custom MRR properties + audit note

import requests as req

HUBSPOT_TOKEN = "your-hubspot-private-app-token"
HS_BASE = "https://api.hubapi.com"

HEADERS = {
    "Authorization": f"Bearer {HUBSPOT_TOKEN}",
    "Content-Type": "application/json",
}

# Custom HubSpot properties (create these in HubSpot Settings → Properties):
# mrr_current       (Number)  — current monthly recurring revenue
# mrr_previous      (Number)  — MRR before the most recent upgrade
# mrr_delta         (Number)  — MRR increase from most recent upgrade
# last_upgrade_date (Date)    — date of most recent upgrade
# stripe_invoice_id (Single-line text) — Stripe invoice ID of last upgrade

def find_deal_by_stripe_customer(customer_id: str) -> dict | None:
    """
    Find HubSpot deal via contact's stripe_customer_id metadata.
    Assumes contacts have a custom property 'stripe_customer_id'.
    """
    # Search contacts by Stripe customer ID
    contact_search = req.post(
        f"{HS_BASE}/crm/v3/objects/contacts/search",
        headers=HEADERS,
        json={
            "filterGroups": [{
                "filters": [{
                    "propertyName": "stripe_customer_id",
                    "operator": "EQ",
                    "value": customer_id
                }]
            }],
            "properties": ["stripe_customer_id", "associatedcompanyid"],
            "limit": 1
        }
    )
    contact_search.raise_for_status()
    results = contact_search.json().get("results", [])
    if not results:
        return None

    contact_id = results[0]["id"]

    # Get associated deals
    deals_resp = req.get(
        f"{HS_BASE}/crm/v3/objects/contacts/{contact_id}/associations/deals",
        headers=HEADERS,
    )
    deals_resp.raise_for_status()
    deal_ids = [r["id"] for r in deals_resp.json().get("results", [])]

    if not deal_ids:
        return None

    # Return most recently updated deal (assumes one active deal per customer)
    deal_resp = req.get(
        f"{HS_BASE}/crm/v3/objects/deals/{deal_ids[0]}",
        headers=HEADERS,
        params={"properties": "mrr_current,amount,dealname"}
    )
    deal_resp.raise_for_status()
    return deal_resp.json()


def update_hubspot_deal(
    customer_id: str,
    old_mrr: float,
    new_mrr: float,
    mrr_delta: float,
    invoice_id: str,
    upgrade_date: str,
):
    deal = find_deal_by_stripe_customer(customer_id)
    if not deal:
        print(f"No HubSpot deal found for Stripe customer {customer_id}")
        return

    deal_id = deal["id"]

    # Step 1: Update deal properties
    # amount = new MRR (keeps standard reporting current)
    # Custom properties preserve history
    update_resp = req.patch(
        f"{HS_BASE}/crm/v3/objects/deals/{deal_id}",
        headers=HEADERS,
        json={
            "properties": {
                "amount":             str(round(new_mrr, 2)),
                "mrr_current":        str(round(new_mrr, 2)),
                "mrr_previous":       str(round(old_mrr, 2)),
                "mrr_delta":          str(round(mrr_delta, 2)),
                "last_upgrade_date":  upgrade_date[:10],  # YYYY-MM-DD
                "stripe_invoice_id":  invoice_id,
            }
        }
    )
    update_resp.raise_for_status()
    print(f"Updated deal {deal_id}: MRR ${old_mrr:.2f} → ${new_mrr:.2f}")

    # Step 2: Create an immutable audit note on the deal
    note_body = (
        f"Subscription upgraded via Stripe.\n\n"
        f"Previous MRR: ${old_mrr:.2f}/month\n"
        f"New MRR: ${new_mrr:.2f}/month\n"
        f"MRR increase: +${mrr_delta:.2f}/month\n"
        f"Effective date: {upgrade_date[:10]}\n"
        f"Stripe invoice: {invoice_id}"
    )

    import time
    note_resp = req.post(
        f"{HS_BASE}/crm/v3/objects/notes",
        headers=HEADERS,
        json={
            "properties": {
                "hs_note_body":  note_body,
                "hs_timestamp":  str(int(time.time() * 1000)),  # Unix ms
            },
            "associations": [{
                "to": {"id": deal_id},
                "types": [{
                    "associationCategory": "HUBSPOT_DEFINED",
                    "associationTypeId": 214   # Note → Deal association
                }]
            }]
        }
    )
    note_resp.raise_for_status()
    print(f"Created audit note on deal {deal_id}")

Multi-item subscription — sum MRR across all price items

def calculate_total_mrr(subscription_items: list) -> float:
    """
    Sum MRR across all items in a subscription.
    Handles per-seat pricing (quantity > 1) and mixed intervals.
    """
    total_mrr = 0.0

    for item in subscription_items:
        price = item["price"]
        quantity = item.get("quantity", 1)

        item_mrr = unit_amount_to_monthly_mrr(
            unit_amount_cents=price["unit_amount"],
            interval=price["recurring"]["interval"]
        )
        total_mrr += item_mrr * quantity  # Multiply by quantity for per-seat items

    return total_mrr

# In process_upgrade_sync():
# Instead of reading from stored upgrade_data for multi-item subs,
# fetch the current subscription to get the full item list
subscription = stripe.Subscription.retrieve(
    sub_id,
    expand=["items.data.price"]
)
new_mrr = calculate_total_mrr(subscription["items"]["data"])

ℹ Building the Stripe Customer → HubSpot Deal Link

If you don’t yet have a stripe_customer_id on your HubSpot contacts, the approach is to add it when a customer first subscribes: on customer.subscription.created, find or create the HubSpot contact by email, then write the Stripe customer ID to the contact’s custom property. Every subsequent webhook event — upgrades, renewals, cancellations — can then find the right HubSpot record reliably via that property.

For existing customers without the link, run a one-time backfill: fetch all Stripe customers, search HubSpot for contacts with matching email addresses, and write the Stripe customer ID to the matching contacts. Track the percentage matched — any customers not linked will be missed by the webhook sync until their contact is found and the property is set.