Skip to content

AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.

feat(backend): track subscription conversion events (#13181)

Swifty39f69e72ebaa
diff --git a/autogpt_platform/backend/backend/data/credit.py b/autogpt_platform/backend/backend/data/credit.py
index 4f032cb2ec..a49340d077 100644
--- a/autogpt_platform/backend/backend/data/credit.py
+++ b/autogpt_platform/backend/backend/data/credit.py
@@ -6,6 +6,7 @@ from collections import defaultdict
from datetime import datetime, timedelta, timezone
from typing import TYPE_CHECKING, Any, Literal, cast
+import posthog
import stripe
from fastapi.concurrency import run_in_threadpool
from prisma.enums import (
@@ -47,6 +48,9 @@ if TYPE_CHECKING:
settings = Settings()
stripe.api_key = settings.secrets.stripe_api_key
+if settings.secrets.posthog_api_key:
+ posthog.api_key = settings.secrets.posthog_api_key
+ posthog.host = settings.secrets.posthog_host
logger = logging.getLogger(__name__)
base_url = settings.config.frontend_base_url or settings.config.platform_base_url
@@ -1037,12 +1041,24 @@ class UserCredit(UserCreditBase):
f"Out of {len(payment_methods)} payment methods tried, none is supported"
)
- await self._enable_transaction(
+ activation = await self._enable_transaction(
transaction_key=transaction_key,
new_transaction_key=new_transaction_key,
user_id=user_id,
metadata=successful_transaction,
)
+ # ``_enable_transaction`` returns None when the transaction is missing
+ # or already active — skip the conversion event in that no-op case so
+ # webhook/retry replays don't double-emit.
+ if activation is not None and amount > 0:
+ _track_billing_event(
+ "credit_topup_success",
+ user_id,
+ {
+ "amount_credits": amount,
+ "top_up_type": top_up_type.value,
+ },
+ )
async def top_up_intent(self, user_id: str, amount: int) -> str:
if amount < 500 or amount % 100 != 0:
@@ -1159,12 +1175,21 @@ class UserCredit(UserCreditBase):
else:
new_transaction_key = None
- await self._enable_transaction(
+ activation = await self._enable_transaction(
transaction_key=credit_transaction.transactionKey,
new_transaction_key=new_transaction_key,
user_id=credit_transaction.userId,
metadata=SafeJson(checkout_session),
)
+ if activation is not None:
+ _track_billing_event(
+ "credit_topup_success",
+ credit_transaction.userId,
+ {
+ "amount_credits": credit_transaction.amount,
+ "top_up_type": "CHECKOUT",
+ },
+ )
async def get_credits(self, user_id: str) -> int:
balance, _ = await self._get_credits(user_id)
@@ -1514,6 +1539,12 @@ async def cancel_stripe_subscription(user_id: str) -> bool:
)
if cancelled_count > 0:
get_pending_subscription_change.cache_delete(user_id)
+ current_tier = user.subscription_tier or SubscriptionTier.NO_TIER
+ _track_billing_event(
+ "subscription_cancellation_scheduled",
+ user_id,
+ {"subscription_tier": current_tier.value},
+ )
return cancelled_count > 0
except stripe.StripeError:
logger.warning(
@@ -1958,8 +1989,10 @@ async def modify_stripe_subscription_for_tier(
# Only catch actual DB/connection failures — letting KeyError,
# AttributeError etc. propagate so programming errors surface in Sentry
# instead of being silently masked as benign DB-write-swallow events.
+ db_flip_succeeded = False
try:
await set_subscription_tier(user_id, tier)
+ db_flip_succeeded = True
except (PrismaError, ConnectionError, asyncio.TimeoutError):
logger.exception(
"modify_stripe_subscription_for_tier: Stripe modify on sub %s"
@@ -1975,6 +2008,19 @@ async def modify_stripe_subscription_for_tier(
user_id,
tier,
)
+ # Only emit on real tier upgrade AND when the DB flip succeeded — the
+ # ``customer.subscription.updated`` webhook is the fallback emit when
+ # the DB flip fails, so gating here avoids double-firing on success.
+ if db_flip_succeeded and is_tier_upgrade(current_tier, tier):
+ _track_billing_event(
+ "subscription_upgraded",
+ user_id,
+ {
+ "previous_subscription_tier": current_tier.value,
+ "subscription_tier": tier.value,
+ "billing_cycle": billing_cycle,
+ },
+ )
return True
finally:
get_pending_subscription_change.cache_delete(user_id)
@@ -2585,6 +2631,19 @@ async def sync_subscription_from_stripe(stripe_subscription: dict) -> None:
# cancel the old sub.
await _cleanup_stale_subscriptions(customer_id, new_sub_id)
await set_subscription_tier(user.id, tier)
+ if is_tier_upgrade(current_tier, tier):
+ billing_cycle = (
+ metadata.get("billing_cycle") if isinstance(metadata, dict) else None
+ )
+ _track_billing_event(
+ "subscription_upgraded",
+ user.id,
+ {
+ "previous_subscription_tier": current_tier.value,
+ "subscription_tier": tier.value,
+ "billing_cycle": billing_cycle,
+ },
+ )
# Tier changed — bust any cached pending-change view so the next
# dashboard fetch reflects the new state immediately.
get_pending_subscription_change.cache_delete(user.id)
@@ -2651,6 +2710,72 @@ def _invoice_subscription_id(invoice: dict) -> str:
return legacy if isinstance(legacy, str) and legacy else ""
+def _track_billing_event(
+ event: str, distinct_id: str, properties: dict[str, Any]
+) -> None:
+ if not settings.secrets.posthog_api_key:
+ return
+
+ try:
+ posthog.capture(
+ event=event,
+ distinct_id=distinct_id,
+ properties=properties,
+ )
+ except Exception:
+ logger.warning(
+ "failed to track billing event %s for user %s",
+ event,
+ distinct_id,
+ exc_info=True,
+ )
+
+
+async def _track_subscription_payment_success(user: User, invoice: dict) -> None:
+ if not settings.secrets.posthog_api_key:
+ return
+
+ try:
+ metadata = _invoice_subscription_metadata(invoice)
+ tier = (
+ metadata.get("tier")
+ or (user.subscriptionTier or SubscriptionTier.NO_TIER).value
+ )
+ billing_cycle = metadata.get("billing_cycle") or (
+ await get_user_billing_cycle(user.id) or "monthly"
+ )
+
+ posthog.capture(
+ event="subscription_payment_success",
+ distinct_id=user.id,
+ properties={
+ "subscription_tier": tier,
+ "billing_cycle": billing_cycle,
+ },
+ )
+ except Exception:
+ logger.warning(
+ "handle_subscription_payment_success: failed to track payment event"
+ " for user %s",
+ user.id,
+ exc_info=True,
+ )
+
+
+def _invoice_subscription_metadata(invoice: dict) -> dict:
+ subscription_details = invoice.get("subscription_details")
+ if not isinstance(subscription_details, dict):
+ parent = invoice.get("parent") or {}
+ if isinstance(parent, dict):
+ subscription_details = parent.get("subscription_details")
+
+ if not isinstance(subscription_details, dict):
+ return {}
+
+ metadata = subscription_details.get("metadata") or {}
+ return metadata if isinstance(metadata, dict) else {}
+
+
async def handle_subscription_payment_failure(invoice: dict) -> None:
"""Handle a failed Stripe subscription payment.
@@ -2843,6 +2968,8 @@ async def handle_subscription_payment_success(invoice: dict) -> None:
)
return
+ await _track_subscription_payment_success(user, invoice)
+
if not settings.config.enable_subscription_credit_grant:
logger.debug(
"handle_subscription_payment_success: credit grant disabled by config"
diff --git a/autogpt_platform/backend/backend/data/credit_subscription_test.py b/autogpt_platform/backend/backend/data/credit_subscription_test.py
index 8b185a6872..11c0807837 100644
--- a/autogpt_platform/backend/backend/data/credit_subscription_test.py
+++ b/autogpt_platform/backend/backend/data/credit_subscription_test.py
@@ -8,10 +8,11 @@ from unittest.mock import AsyncMock, MagicMock, patch
import pytest
import stripe
from prisma.enums import SubscriptionTier
-from prisma.errors import UniqueViolationError
+from prisma.errors import PrismaError, UniqueViolationError
from prisma.models import User
from backend.data.credit import (
+ UserCredit,
cancel_stripe_subscription,
create_subscription_checkout,
get_pending_subscription_change,
@@ -125,6 +126,55 @@ async def test_sync_subscription_from_stripe_active():
mock_set.assert_awaited_once_with("user-1", SubscriptionTier.PRO)
+async def test_sync_subscription_from_stripe_tracks_upgrade():
+ mock_user = _make_user(tier=SubscriptionTier.BASIC)
+ stripe_sub = {
+ "id": "sub_new",
+ "customer": "cus_123",
+ "status": "active",
+ "items": {"data": [{"price": {"id": "price_pro_yearly"}}]},
+ "metadata": {"billing_cycle": "yearly"},
+ }
+ track_mock = MagicMock()
+
+ async def mock_price_id(
+ tier: SubscriptionTier, billing_cycle: str = "monthly"
+ ) -> str | None:
+ if tier == SubscriptionTier.PRO and billing_cycle == "yearly":
+ return "price_pro_yearly"
+ return None
+
+ with (
+ patch(
+ "backend.data.credit.User.prisma",
+ return_value=MagicMock(find_first=AsyncMock(return_value=mock_user)),
+ ),
+ patch(
+ "backend.data.credit.get_subscription_price_id",
+ side_effect=mock_price_id,
+ ),
+ patch(
+ "backend.data.credit._cleanup_stale_subscriptions", new_callable=AsyncMock
+ ),
+ patch("backend.data.credit.set_subscription_tier", new_callable=AsyncMock),
+ patch("backend.data.credit.settings.secrets.posthog_api_key", new="phc_test"),
+ patch("backend.data.credit.posthog.capture", new=track_mock),
+ patch.object(get_pending_subscription_change, "cache_delete"),
+ ):
+ await sync_subscription_from_stripe(stripe_sub)
+
+ track_mock.assert_called_once()
+ _, kwargs = track_mock.call_args
+ assert kwargs["event"] == "subscription_upgraded"
+ assert kwargs["distinct_id"] == "user-1"
+ assert kwargs["properties"] == {
+ "previous_subscription_tier": "BASIC",
+ "subscription_tier": "PRO",
+ "billing_cycle": "yearly",
+ }
+
+
@pytest.mark.asyncio
async def test_sync_subscription_from_stripe_yearly_pro_maps_to_pro():
"""A user on a yearly Pro plan still maps to SubscriptionTier.PRO."""
@@ -473,6 +523,37 @@ async def test_cancel_stripe_subscription_cancels_active():
mock_modify.assert_called_once_with("sub_abc123", cancel_at_period_end=True)
+async def test_cancel_stripe_subscription_tracks_cancellation():
+ mock_user = _make_user_with_stripe("cus_123")
+ mock_user.subscription_tier = SubscriptionTier.PRO
+ track_mock = MagicMock()
+
+ with (
+ patch(
+ "backend.data.credit.get_user_by_id",
+ new_callable=AsyncMock,
+ return_value=mock_user,
+ ),
+ patch(
+ "backend.data.credit._cancel_customer_subscriptions",
+ new_callable=AsyncMock,
+ return_value=1,
+ ),
+ patch("backend.data.credit.settings.secrets.posthog_api_key", new="phc_test"),
+ patch("backend.data.credit.posthog.capture", new=track_mock),
+ patch.object(get_pending_subscription_change, "cache_delete"),
+ ):
+ result = await cancel_stripe_subscription("user-1")
+
+ assert result is True
+ track_mock.assert_called_once()
+ _, kwargs = track_mock.call_args
+ assert kwargs["event"] == "subscription_cancellation_scheduled"
+ assert kwargs["distinct_id"] == "user-1"
+ assert kwargs["properties"] == {"subscription_tier": "PRO"}
+
+
@pytest.mark.asyncio
async def test_cancel_stripe_subscription_no_customer_id_returns_false():
"""Users with no stripe_customer_id return False without creating a Stripe customer."""
@@ -1677,6 +1758,174 @@ async def test_handle_subscription_payment_success_skips_when_disabled():
add_tx_mock.assert_not_called()
+async def test_handle_subscription_payment_success_tracks_paid_plan_when_grants_disabled():
+ """Successful paid subscription invoices emit the subscription analytics."""
+ mock_user = _make_user(user_id="user-1", tier=SubscriptionTier.PRO)
+ invoice = {
+ "id": "in_paid_yearly",
+ "customer": "cus_123",
+ "subscription": "sub_abc123",
+ "amount_paid": 5000,
+ "subscription_details": {
+ "metadata": {
+ "tier": "PRO",
+ "billing_cycle": "yearly",
+ },
+ },
+ }
+
+ track_mock = MagicMock()
+ with (
+ patch(
+ "backend.data.credit.User.prisma",
+ return_value=MagicMock(find_first=AsyncMock(return_value=mock_user)),
+ ),
+ patch(
+ "backend.data.credit.UserCredit._add_transaction",
+ new=AsyncMock(),
+ ) as add_tx_mock,
+ patch("backend.data.credit.settings.secrets.posthog_api_key", new="phc_test"),
+ patch("backend.data.credit.posthog.capture", new=track_mock),
+ _patch_credit_grant_config(False),
+ ):
+ await handle_subscription_payment_success(invoice)
+
+ add_tx_mock.assert_not_called()
+ track_mock.assert_called_once()
+ _, kwargs = track_mock.call_args
+ assert kwargs["event"] == "subscription_payment_success"
+ assert kwargs["distinct_id"] == "user-1"
+ assert kwargs["properties"]["subscription_tier"] == "PRO"
+ assert kwargs["properties"]["billing_cycle"] == "yearly"
+
+
+async def test_handle_subscription_payment_success_metadata_absent_uses_user_tier():
+ """When invoice metadata lacks tier/billing_cycle, falls back to user."""
+ mock_user = _make_user(user_id="user-1", tier=SubscriptionTier.PRO)
+ invoice = {
+ "id": "in_no_meta",
+ "customer": "cus_123",
+ "subscription": "sub_abc123",
+ "amount_paid": 5000,
+ }
+ track_mock = MagicMock()
+ with (
+ patch(
+ "backend.data.credit.User.prisma",
+ return_value=MagicMock(find_first=AsyncMock(return_value=mock_user)),
+ ),
+ patch("backend.data.credit.UserCredit._add_transaction", new=AsyncMock()),
+ patch(
+ "backend.data.credit.get_user_billing_cycle",
+ new_callable=AsyncMock,
+ return_value="monthly",
+ ),
+ patch("backend.data.credit.settings.secrets.posthog_api_key", new="phc_test"),
+ patch("backend.data.credit.posthog.capture", new=track_mock),
+ _patch_credit_grant_config(False),
+ ):
+ await handle_subscription_payment_success(invoice)
+
+ track_mock.assert_called_once()
+ _, kwargs = track_mock.call_args
+ assert kwargs["properties"]["subscription_tier"] == "PRO"
+ assert kwargs["properties"]["billing_cycle"] == "monthly"
+
+
+async def test_handle_subscription_payment_success_reads_parent_metadata():
+ """Stripe API ≥2025-04-01 nests subscription_details under parent."""
+ mock_user = _make_user(user_id="user-1", tier=SubscriptionTier.BASIC)
+ invoice = {
+ "id": "in_parent",
+ "customer": "cus_123",
+ "amount_paid": 5000,
+ "parent": {
+ "subscription_details": {
+ "subscription": "sub_abc123",
+ "metadata": {"tier": "PRO", "billing_cycle": "yearly"},
+ }
+ },
+ }
+ track_mock = MagicMock()
+ with (
+ patch(
+ "backend.data.credit.User.prisma",
+ return_value=MagicMock(find_first=AsyncMock(return_value=mock_user)),
+ ),
+ patch("backend.data.credit.UserCredit._add_transaction", new=AsyncMock()),
+ patch("backend.data.credit.settings.secrets.posthog_api_key", new="phc_test"),
+ patch("backend.data.credit.posthog.capture", new=track_mock),
+ _patch_credit_grant_config(False),
+ ):
+ await handle_subscription_payment_success(invoice)
+
+ track_mock.assert_called_once()
+ _, kwargs = track_mock.call_args
+ assert kwargs["properties"]["subscription_tier"] == "PRO"
+ assert kwargs["properties"]["billing_cycle"] == "yearly"
+
+
+async def test_handle_subscription_payment_success_swallows_posthog_errors():
+ """PostHog failures must not abort the surrounding webhook handler."""
+ mock_user = _make_user(user_id="user-1", tier=SubscriptionTier.PRO)
+ invoice = {
+ "id": "in_err",
+ "customer": "cus_123",
+ "subscription": "sub_abc123",
+ "amount_paid": 5000,
+ "subscription_details": {
+ "metadata": {"tier": "PRO", "billing_cycle": "yearly"},
+ },
+ }
+ track_mock = MagicMock(side_effect=RuntimeError("posthog down"))
+ with (
+ patch(
+ "backend.data.credit.User.prisma",
+ return_value=MagicMock(find_first=AsyncMock(return_value=mock_user)),
+ ),
+ patch("backend.data.credit.UserCredit._add_transaction", new=AsyncMock()),
+ patch("backend.data.credit.settings.secrets.posthog_api_key", new="phc_test"),
+ patch("backend.data.credit.posthog.capture", new=track_mock),
+ _patch_credit_grant_config(False),
+ ):
+ await handle_subscription_payment_success(invoice)
+
+ track_mock.assert_called_once()
+
+
+async def test_handle_subscription_payment_success_skips_tracking_when_posthog_disabled():
+ """No API key configured → no capture call."""
+ mock_user = _make_user(user_id="user-1", tier=SubscriptionTier.PRO)
+ invoice = {
+ "id": "in_disabled",
+ "customer": "cus_123",
+ "subscription": "sub_abc123",
+ "amount_paid": 5000,
+ "subscription_details": {
+ "metadata": {"tier": "PRO", "billing_cycle": "yearly"},
+ },
+ }
+ track_mock = MagicMock()
+ with (
+ patch(
+ "backend.data.credit.User.prisma",
+ return_value=MagicMock(find_first=AsyncMock(return_value=mock_user)),
+ ),
+ patch("backend.data.credit.UserCredit._add_transaction", new=AsyncMock()),
+ patch("backend.data.credit.settings.secrets.posthog_api_key", new=""),
+ patch("backend.data.credit.posthog.capture", new=track_mock),
+ _patch_credit_grant_config(False),
+ ):
+ await handle_subscription_payment_success(invoice)
+
+ track_mock.assert_not_called()
+
+
@pytest.mark.asyncio
async def test_handle_subscription_payment_success_skips_non_subscription_invoice():
"""Invoices with no subscription field (one-off invoices) are no-ops —
@@ -2002,6 +2251,106 @@ async def test_top_up_intent_references_product_id_when_flag_set():
assert "product_data" not in price_data
+async def test_top_up_credits_tracks_success():
+ credit_system = UserCredit()
+ payment_method = MagicMock()
+ payment_method.id = "pm_123"
+ payment_intent = MagicMock()
+ payment_intent.status = "succeeded"
+ payment_intent.id = "pi_123"
+ track_mock = MagicMock()
+
+ with (
+ patch.object(
+ credit_system,
+ "_add_transaction",
+ new_callable=AsyncMock,
+ return_value=(0, "tx_123"),
+ ),
+ patch.object(
+ credit_system,
+ "_enable_transaction",
+ new_callable=AsyncMock,
+ return_value=(500, "pi_123"),
+ ),
+ patch(
+ "backend.data.credit.get_stripe_customer_id",
+ new_callable=AsyncMock,
+ return_value="cus_123",
+ ),
+ patch(
+ "backend.data.credit.stripe.PaymentMethod.list",
+ return_value=[payment_method],
+ ),
+ patch(
+ "backend.data.credit.stripe.PaymentIntent.create",
+ return_value=payment_intent,
+ ),
+ patch("backend.data.credit.settings.secrets.posthog_api_key", new="phc_test"),
+ patch("backend.data.credit.posthog.capture", new=track_mock),
+ ):
+ await credit_system._top_up_credits("user-1", 500)
+
+ track_mock.assert_called_once()
+ _, kwargs = track_mock.call_args
+ assert kwargs["event"] == "credit_topup_success"
+ assert kwargs["distinct_id"] == "user-1"
+ assert kwargs["properties"] == {
+ "amount_credits": 500,
+ "top_up_type": "UNCATEGORIZED",
+ }
+
+
+async def test_fulfill_checkout_tracks_credit_topup_success():
+ credit_system = UserCredit()
+ transaction = MagicMock()
+ transaction.transactionKey = "cs_test_topup"
+ transaction.userId = "user-1"
+ transaction.amount = 2500
+ checkout_session = stripe.checkout.Session.construct_from(
+ {
+ "id": "cs_test_topup",
+ "payment_status": "paid",
+ "payment_intent": stripe.PaymentIntent.construct_from(
+ {"id": "pi_test_topup"}, "k"
+ ),
+ },
+ "k",
+ )
+ track_mock = MagicMock()
+
+ with (
+ patch(
+ "backend.data.credit.CreditTransaction.prisma",
+ return_value=MagicMock(find_first=AsyncMock(return_value=transaction)),
+ ),
+ patch(
+ "backend.data.credit.stripe.checkout.Session.retrieve",
+ return_value=checkout_session,
+ ),
+ patch.object(
+ credit_system,
+ "_enable_transaction",
+ new_callable=AsyncMock,
+ return_value=(2500, "pi_test_topup"),
+ ),
+ patch("backend.data.credit.settings.secrets.posthog_api_key", new="phc_test"),
+ patch("backend.data.credit.posthog.capture", new=track_mock),
+ ):
+ await credit_system.fulfill_checkout(session_id="cs_test_topup")
+
+ track_mock.assert_called_once()
+ _, kwargs = track_mock.call_args
+ assert kwargs["event"] == "credit_topup_success"
+ assert kwargs["distinct_id"] == "user-1"
+ assert kwargs["properties"] == {
+ "amount_credits": 2500,
+ "top_up_type": "CHECKOUT",
+ }
+
+
@pytest.mark.asyncio
async def test_modify_stripe_subscription_for_tier_modifies_existing_sub():
"""modify_stripe_subscription_for_tier calls Subscription.modify and returns True."""
@@ -2359,6 +2708,65 @@ async def test_modify_stripe_subscription_for_tier_upgrade_immediate_proration()
mock_schedule_create.assert_not_called()
+async def test_modify_stripe_subscription_skips_emit_when_db_flip_fails():
+ """When ``set_subscription_tier`` fails after a successful Stripe modify,
+ the immediate ``subscription_upgraded`` emit must be skipped — the webhook
+ is the fallback emit path and would otherwise produce a duplicate event."""
+ mock_sub = stripe.Subscription.construct_from(
+ {
+ "id": "sub_pro",
+ "items": {"data": [{"id": "si_pro", "price": {"id": "price_pro_monthly"}}]},
+ "schedule": None,
+ "cancel_at_period_end": False,
+ },
+ "k",
+ )
+ mock_list = MagicMock()
+ mock_list.data = [mock_sub]
+
+ mock_user = MagicMock(spec=User)
+ mock_user.stripe_customer_id = "cus_abc"
+ mock_user.subscription_tier = SubscriptionTier.PRO
+
+ track_mock = MagicMock()
+ with (
+ patch(
+ "backend.data.credit.get_subscription_price_id",
+ new_callable=AsyncMock,
+ return_value="price_biz_monthly",
+ ),
+ patch(
+ "backend.data.credit.get_user_by_id",
+ new_callable=AsyncMock,
+ return_value=mock_user,
+ ),
+ patch(
+ "backend.data.credit.stripe.Subscription.list_async",
+ new_callable=AsyncMock,
+ return_value=mock_list,
+ ),
+ patch(
+ "backend.data.credit.stripe.Subscription.modify_async",
+ new_callable=AsyncMock,
+ ),
+ patch(
+ "backend.data.credit.set_subscription_tier",
+ new_callable=AsyncMock,
+ side_effect=PrismaError("db down"),
+ ),
+ patch("backend.data.credit.settings.secrets.posthog_api_key", new="phc_test"),
+ patch("backend.data.credit.posthog.capture", new=track_mock),
+ patch.object(get_pending_subscription_change, "cache_delete"),
+ ):
+ result = await modify_stripe_subscription_for_tier(
+ "user-1", SubscriptionTier.BUSINESS
+ )
+
+ assert result is True
+ track_mock.assert_not_called()
+
+
@pytest.mark.asyncio
async def test_modify_stripe_subscription_for_tier_pro_to_max_bills_immediately():
"""Pro→Max upgrade calls Stripe with always_invoice + error_if_incomplete so the