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): bidirectional Stripe tier reconciliation with provenance + periodic sweep (#13284)

Zamil Majdy6811bfdffdd9
diff --git a/autogpt_platform/backend/backend/api/features/subscription_routes_test.py b/autogpt_platform/backend/backend/api/features/subscription_routes_test.py
index 1c611d86cc..4cde008949 100644
--- a/autogpt_platform/backend/backend/api/features/subscription_routes_test.py
+++ b/autogpt_platform/backend/backend/api/features/subscription_routes_test.py
@@ -1701,7 +1701,7 @@ def test_update_subscription_tier_no_tier_no_stripe_subscription(
assert response.status_code == 200
assert response.json()["url"] == ""
cancel_mock.assert_awaited_once_with(TEST_USER_ID)
- # DB tier must be updated immediately — no webhook will fire for a missing sub
+ # DB tier must be updated immediately — no webhook will fire for a missing sub.
set_tier_mock.assert_awaited_once_with(TEST_USER_ID, SubscriptionTier.NO_TIER)
diff --git a/autogpt_platform/backend/backend/api/features/v1.py b/autogpt_platform/backend/backend/api/features/v1.py
index 4fb4c4689b..b0a77d9265 100644
--- a/autogpt_platform/backend/backend/api/features/v1.py
+++ b/autogpt_platform/backend/backend/api/features/v1.py
@@ -1098,6 +1098,8 @@ async def update_subscription_tier(
),
)
if not had_subscription:
+ # No Stripe subscription drove this change (admin-granted or
+ # never-paid).
await set_subscription_tier(user_id, tier)
return await get_subscription_status(user_id)
await set_subscription_tier(user_id, tier)
diff --git a/autogpt_platform/backend/backend/api/features/v1_stripe_webhook_test.py b/autogpt_platform/backend/backend/api/features/v1_stripe_webhook_test.py
index 42d9d219f8..0a41042c0e 100644
--- a/autogpt_platform/backend/backend/api/features/v1_stripe_webhook_test.py
+++ b/autogpt_platform/backend/backend/api/features/v1_stripe_webhook_test.py
@@ -7,6 +7,7 @@ import fastapi.testclient
import pytest
import pytest_mock
import stripe
+from prisma.enums import SubscriptionTier
from backend.data.credit import (
_expire_open_subscription_sessions,
@@ -500,10 +501,14 @@ async def test_reconcile_stripe_tier_no_customer_returns_false(
mock_get_sub.assert_not_called()
-async def test_reconcile_stripe_tier_no_active_sub_returns_false(
+async def test_reconcile_stripe_tier_no_active_sub_already_no_tier_returns_false(
mocker: pytest_mock.MockFixture,
) -> None:
- user = MagicMock(stripe_customer_id="cus_abc")
+ """A reconcilable user already on NO_TIER stays put (no write, no sync)."""
+ user = MagicMock(
+ stripe_customer_id="cus_abc",
+ subscription_tier=SubscriptionTier.NO_TIER,
+ )
mocker.patch(
"backend.data.credit.get_user_by_id", new_callable=AsyncMock, return_value=user
)
@@ -515,9 +520,100 @@ async def test_reconcile_stripe_tier_no_active_sub_returns_false(
mock_sync = mocker.patch(
"backend.data.credit.sync_subscription_from_stripe", new_callable=AsyncMock
)
+ mock_set = mocker.patch(
+ "backend.data.credit.set_subscription_tier", new_callable=AsyncMock
+ )
assert await reconcile_stripe_tier_for_user("user_abc") is False
mock_sync.assert_not_called()
+ mock_set.assert_not_called()
+
+
+async def test_reconcile_stripe_tier_no_active_sub_downgrades_payer(
+ mocker: pytest_mock.MockFixture,
+) -> None:
+ """A reconcilable payer with no active sub is downgraded to NO_TIER."""
+ user = MagicMock(
+ stripe_customer_id="cus_abc",
+ subscription_tier=SubscriptionTier.PRO,
+ )
+ mocker.patch(
+ "backend.data.credit.get_user_by_id", new_callable=AsyncMock, return_value=user
+ )
+ mocker.patch(
+ "backend.data.credit._get_active_subscription",
+ new_callable=AsyncMock,
+ return_value=None,
+ )
+ mock_set = mocker.patch(
+ "backend.data.credit.set_subscription_tier", new_callable=AsyncMock
+ )
+ mock_alert = mocker.patch(
+ "backend.data.credit.alert_tier_reconciliation_discrepancy",
+ new_callable=AsyncMock,
+ )
+
+ assert await reconcile_stripe_tier_for_user("user_abc") is True
+ mock_set.assert_awaited_once_with("user_abc", SubscriptionTier.NO_TIER)
+ # A silently-missed cancellation webhook must alert ops, not be corrected quietly.
+ mock_alert.assert_awaited_once()
+ assert "DOWNGRADED" in mock_alert.await_args.args[0]
+
+
+async def test_reconcile_stripe_tier_lazy_upgrade_alerts(
+ mocker: pytest_mock.MockFixture,
+) -> None:
+ """A lazy reconcile that finds an active sub the DB missed also alerts ops."""
+ user = MagicMock(
+ stripe_customer_id="cus_abc",
+ subscription_tier=SubscriptionTier.NO_TIER,
+ )
+ upgraded = MagicMock(subscription_tier=SubscriptionTier.PRO)
+ mocker.patch(
+ "backend.data.credit.get_user_by_id",
+ new_callable=AsyncMock,
+ side_effect=[user, upgraded],
+ )
+ mocker.patch(
+ "backend.data.credit._get_active_subscription",
+ new_callable=AsyncMock,
+ return_value={"id": "sub_1", "customer": "cus_abc", "status": "active"},
+ )
+ mocker.patch(
+ "backend.data.credit.sync_subscription_from_stripe", new_callable=AsyncMock
+ )
+ mock_alert = mocker.patch(
+ "backend.data.credit.alert_tier_reconciliation_discrepancy",
+ new_callable=AsyncMock,
+ )
+
+ assert await reconcile_stripe_tier_for_user("user_abc") is True
+ mock_alert.assert_awaited_once()
+ assert "upgrade" in mock_alert.await_args.args[0]
+
+
+async def test_reconcile_stripe_tier_enterprise_user_skipped(
+ mocker: pytest_mock.MockFixture,
+) -> None:
+ """An ENTERPRISE tier is never reconciled/downgraded against Stripe, even
+ with a Stripe customer."""
+ user = MagicMock(
+ stripe_customer_id="cus_abc",
+ subscription_tier=SubscriptionTier.ENTERPRISE,
+ )
+ mocker.patch(
+ "backend.data.credit.get_user_by_id", new_callable=AsyncMock, return_value=user
+ )
+ mock_get_active = mocker.patch(
+ "backend.data.credit._get_active_subscription", new_callable=AsyncMock
+ )
+ mock_set = mocker.patch(
+ "backend.data.credit.set_subscription_tier", new_callable=AsyncMock
+ )
+
+ assert await reconcile_stripe_tier_for_user("user_abc") is False
+ mock_get_active.assert_not_called()
+ mock_set.assert_not_called()
async def test_reconcile_stripe_tier_stripe_error_returns_false(
@@ -543,10 +639,16 @@ async def test_reconcile_stripe_tier_stripe_error_returns_false(
async def test_reconcile_stripe_tier_active_sub_syncs_and_returns_true(
mocker: pytest_mock.MockFixture,
) -> None:
- user = MagicMock(stripe_customer_id="cus_abc")
+ before = MagicMock(
+ stripe_customer_id="cus_abc",
+ subscription_tier=SubscriptionTier.NO_TIER,
+ )
+ after = MagicMock(subscription_tier=SubscriptionTier.PRO)
fake_sub = MagicMock()
mocker.patch(
- "backend.data.credit.get_user_by_id", new_callable=AsyncMock, return_value=user
+ "backend.data.credit.get_user_by_id",
+ new_callable=AsyncMock,
+ side_effect=[before, after],
)
mocker.patch(
"backend.data.credit._get_active_subscription",
@@ -559,3 +661,29 @@ async def test_reconcile_stripe_tier_active_sub_syncs_and_returns_true(
assert await reconcile_stripe_tier_for_user("user_abc") is True
mock_sync.assert_called_once_with(dict(fake_sub))
+
+
+async def test_reconcile_stripe_tier_active_sub_unchanged_returns_false(
+ mocker: pytest_mock.MockFixture,
+) -> None:
+ """Active sub already matches the DB tier: no change, returns False."""
+ user = MagicMock(
+ stripe_customer_id="cus_abc",
+ subscription_tier=SubscriptionTier.PRO,
+ )
+ after = MagicMock(subscription_tier=SubscriptionTier.PRO)
+ mocker.patch(
+ "backend.data.credit.get_user_by_id",
+ new_callable=AsyncMock,
+ side_effect=[user, after],
+ )
+ mocker.patch(
+ "backend.data.credit._get_active_subscription",
+ new_callable=AsyncMock,
+ return_value=MagicMock(),
+ )
+ mocker.patch(
+ "backend.data.credit.sync_subscription_from_stripe", new_callable=AsyncMock
+ )
+
+ assert await reconcile_stripe_tier_for_user("user_abc") is False
diff --git a/autogpt_platform/backend/backend/data/credit.py b/autogpt_platform/backend/backend/data/credit.py
index 8a138dbf02..6f154ebe47 100644
--- a/autogpt_platform/backend/backend/data/credit.py
+++ b/autogpt_platform/backend/backend/data/credit.py
@@ -18,7 +18,11 @@ from prisma.enums import (
)
from prisma.errors import PrismaError, UniqueViolationError
from prisma.models import CreditRefundRequest, CreditTransaction, User, UserBalance
-from prisma.types import CreditRefundRequestCreateInput, CreditTransactionWhereInput
+from prisma.types import (
+ CreditRefundRequestCreateInput,
+ CreditTransactionWhereInput,
+ UserUpdateInput,
+)
from pydantic import BaseModel
from backend.api.features.admin.model import UserHistoryResponse
@@ -31,8 +35,9 @@ from backend.data.model import (
RefundRequest,
TopUpType,
TransactionHistory,
- UserTransaction,
)
+from backend.data.model import User as AppUser
+from backend.data.model import UserTransaction
from backend.data.notifications import NotificationEventModel, RefundRequestData
from backend.data.user import get_user_by_id, get_user_email_by_id
from backend.notifications.notifications import queue_notification_async
@@ -40,6 +45,7 @@ from backend.util.cache import cached
from backend.util.exceptions import InsufficientBalanceError
from backend.util.feature_flag import Flag, get_feature_flag_value
from backend.util.json import SafeJson, dumps
+from backend.util.metrics import DiscordChannel, discord_send_alert
from backend.util.models import Pagination
from backend.util.retry import func_retry
from backend.util.settings import Settings
@@ -1420,12 +1426,15 @@ async def set_auto_top_up(user_id: str, config: AutoTopUpConfig):
get_user_by_id.cache_delete(user_id)
-async def set_subscription_tier(user_id: str, tier: SubscriptionTier) -> None:
- """Set the user's subscription tier (used by webhook and admin flows)."""
- await User.prisma().update(
- where={"id": user_id},
- data={"subscriptionTier": tier},
- )
+async def set_subscription_tier(
+ user_id: str,
+ tier: SubscriptionTier,
+) -> None:
+ """Set the user's subscription tier."""
+ data: UserUpdateInput = {
+ "subscriptionTier": tier,
+ }
+ await User.prisma().update(where={"id": user_id}, data=data)
get_user_by_id.cache_delete(user_id)
# Also invalidate the rate-limit tier cache so CoPilot picks up the new
# tier immediately rather than waiting up to 5 minutes for the TTL to expire.
@@ -2307,6 +2316,32 @@ async def get_subscription_price_id(
return price_id if isinstance(price_id, str) and price_id else None
+_PRICEABLE_TIERS: tuple[SubscriptionTier, ...] = (
+ SubscriptionTier.BASIC,
+ SubscriptionTier.PRO,
+ SubscriptionTier.MAX,
+ SubscriptionTier.BUSINESS,
+)
+
+
+async def build_price_to_tier_map() -> dict[str, SubscriptionTier]:
+ """Map every configured monthly+yearly Stripe price ID to its tier.
+
+ Lets a yearly plan resolve back to the same tier as its monthly twin.
+ Shared by the webhook sync and the periodic reconciliation sweep so both
+ interpret Stripe prices identically.
+ """
+ prices = await asyncio.gather(
+ *[get_subscription_price_id(t, "monthly") for t in _PRICEABLE_TIERS],
+ *[get_subscription_price_id(t, "yearly") for t in _PRICEABLE_TIERS],
+ )
+ price_to_tier: dict[str, SubscriptionTier] = {}
+ for t, pid in zip(_PRICEABLE_TIERS + _PRICEABLE_TIERS, prices):
+ if pid:
+ price_to_tier[pid] = t
+ return price_to_tier
+
+
async def _expire_open_subscription_sessions(customer_id: str) -> None:
"""Expire open subscription checkout sessions for the customer.
@@ -2344,15 +2379,34 @@ async def _expire_open_subscription_sessions(customer_id: str) -> None:
)
+def _is_stripe_reconcilable(user: AppUser) -> bool:
+ """True when Stripe is the authoritative source for this user's tier.
+
+ A user is reconcilable (auto-downgradable) iff they have a Stripe customer
+ and are not on ENTERPRISE. Manual/admin grants are modeled as a paid tier
+ with no Stripe customer, or as ENTERPRISE — both are managed out-of-band and
+ must never be auto-revoked by Stripe reconciliation.
+ """
+ return (
+ user.stripe_customer_id is not None
+ and user.subscription_tier != SubscriptionTier.ENTERPRISE
+ )
+
+
async def reconcile_stripe_tier_for_user(user_id: str) -> bool:
- """Check Stripe for an active subscription and sync tier if found.
+ """Make Stripe the source of truth for a single reconcilable user's tier.
+
+ Bidirectional: sets the tier to the user's current active/trialing Stripe
+ subscription, and DOWNGRADES to NO_TIER when no active sub exists. Never
+ touches non-reconcilable rows (no Stripe customer, or ENTERPRISE). Returns
+ True when the tier was changed.
- Called as a lazy fallback when a user is on NO_TIER to recover from
- missed webhooks. Returns True if an active subscription was found and
- synced. Does NOT create a Stripe customer — only checks existing ones.
+ Routes through ``sync_subscription_from_stripe`` so the active-sub path
+ shares the webhook's idempotency + "other active subs" downgrade guard.
+ Does NOT create a Stripe customer — only checks existing ones.
"""
user = await get_user_by_id(user_id)
- if not user.stripe_customer_id:
+ if not user.stripe_customer_id or not _is_stripe_reconcilable(user):
return False
try:
sub = await _get_active_subscription(user.stripe_customer_id)
@@ -2362,9 +2416,44 @@ async def reconcile_stripe_tier_for_user(user_id: str) -> bool:
user_id[:8],
)
return False
- if sub is None:
+ current_tier = user.subscription_tier or SubscriptionTier.NO_TIER
+ if sub is not None:
+ await sync_subscription_from_stripe(dict(sub))
+ new_tier = (
+ await get_user_by_id(user_id)
+ ).subscription_tier or SubscriptionTier.NO_TIER
+ if new_tier == current_tier:
+ return False
+ direction = log_tier_reconciliation_discrepancy(
+ user_id=user_id,
+ stripe_customer_id=user.stripe_customer_id,
+ previous_tier=current_tier,
+ new_tier=new_tier,
+ via="lazy-reconcile",
+ )
+ await alert_tier_reconciliation_discrepancy(
+ f"⚠️ Payments integrity: on-access reconcile {direction} user "
+ f"`{user_id}` {current_tier.value} → {new_tier.value} — Stripe "
+ f"disagreed with our DB, a subscription webhook was likely missed."
+ )
+ return True
+ # No active/trialing sub — downgrade a reconcilable row to NO_TIER.
+ if current_tier == SubscriptionTier.NO_TIER:
return False
- await sync_subscription_from_stripe(dict(sub))
+ await set_subscription_tier(user_id, SubscriptionTier.NO_TIER)
+ log_tier_reconciliation_discrepancy(
+ user_id=user_id,
+ stripe_customer_id=user.stripe_customer_id,
+ previous_tier=current_tier,
+ new_tier=SubscriptionTier.NO_TIER,
+ via="lazy-reconcile",
+ )
+ await alert_tier_reconciliation_discrepancy(
+ f"🚨 Payments integrity: on-access reconcile DOWNGRADED user `{user_id}` "
+ f"{current_tier.value} → NO_TIER — no active Stripe subscription, but our "
+ f"DB had them on a paid tier. A cancellation webhook was likely missed; "
+ f"investigate the webhook pipeline."
+ )
return True
@@ -2501,7 +2590,9 @@ async def sync_subscription_from_stripe(stripe_subscription: dict) -> None:
# ENTERPRISE user to a different tier — if a user on ENTERPRISE somehow has
# a self-service Stripe sub, it's a data-consistency issue for an operator,
# not something the webhook should automatically "fix".
- current_tier = user.subscriptionTier or SubscriptionTier.NO_TIER
+ # Prisma returns the enum column as a plain str at runtime, so coerce to the
+ # enum before any `.value` access (e.g. the upgrade analytics event below).
+ current_tier = SubscriptionTier(user.subscriptionTier or SubscriptionTier.NO_TIER)
if current_tier == SubscriptionTier.ENTERPRISE:
logger.warning(
"sync_subscription_from_stripe: refusing to overwrite ENTERPRISE tier"
@@ -2518,22 +2609,7 @@ async def sync_subscription_from_stripe(stripe_subscription: dict) -> None:
items = stripe_subscription.get("items", {}).get("data", [])
if items:
price_id = items[0].get("price", {}).get("id", "")
- priceable = (
- SubscriptionTier.BASIC,
- SubscriptionTier.PRO,
- SubscriptionTier.MAX,
- SubscriptionTier.BUSINESS,
- )
- # Gather monthly + yearly price IDs for every priceable tier so a user
- # on a yearly plan still maps back to the correct tier.
- prices = await asyncio.gather(
- *[get_subscription_price_id(t, "monthly") for t in priceable],
- *[get_subscription_price_id(t, "yearly") for t in priceable],
- )
- price_to_tier: dict[str, SubscriptionTier] = {}
- for t, pid in zip(priceable + priceable, prices):
- if pid:
- price_to_tier[pid] = t
+ price_to_tier = await build_price_to_tier_map()
matched = price_to_tier.get(price_id) if price_id else None
if matched is not None:
tier = matched
@@ -2712,6 +2788,60 @@ def _invoice_subscription_id(invoice: dict) -> str:
return legacy if isinstance(legacy, str) and legacy else ""
+TIER_RECONCILIATION_DISCREPANCY_EVENT = "subscription_tier_reconciliation_discrepancy"
+
+
+def log_tier_reconciliation_discrepancy(
+ *,
+ user_id: str,
+ stripe_customer_id: str | None,
+ previous_tier: SubscriptionTier,
+ new_tier: SubscriptionTier,
+ via: str,
+) -> str:
+ """Record a Stripe<->DB tier discrepancy that reconciliation had to correct.
+
+ A correction means a Stripe webhook was missed or dropped — a payments-
+ integrity signal to investigate, NOT a routine fix. Emits an ERROR log
+ (captured by Sentry via the logging integration) plus a PostHog event so the
+ rate of discrepancies is trended. Returns the direction ("downgrade"/"upgrade").
+ """
+ direction = "upgrade" if is_tier_upgrade(previous_tier, new_tier) else "downgrade"
+ logger.error(
+ "Stripe tier reconciliation %s for user %s (%s -> %s, via %s): a Stripe "
+ "webhook was likely missed. Investigate the webhook pipeline — payments-"
+ "integrity signal, not a routine correction.",
+ direction,
+ user_id[:8],
+ previous_tier.value,
+ new_tier.value,
+ via,
+ )
+ _track_billing_event(
+ TIER_RECONCILIATION_DISCREPANCY_EVENT,
+ user_id,
+ {
+ "direction": direction,
+ "previous_subscription_tier": previous_tier.value,
+ "subscription_tier": new_tier.value,
+ "via": via,
+ "stripe_customer_id": stripe_customer_id,
+ },
+ )
+ return direction
+
+
+async def alert_tier_reconciliation_discrepancy(message: str) -> None:
+ """Best-effort ops alert to the platform Discord channel. Never raises so a
+ Discord outage can't break reconciliation."""
+ try:
+ await discord_send_alert(message, DiscordChannel.PLATFORM)
+ except Exception:
+ logger.warning(
+ "failed to send tier-reconciliation Discord alert", exc_info=True
+ )
+
+
def _track_billing_event(
event: str, distinct_id: str, properties: dict[str, Any]
) -> None:
@@ -2741,7 +2871,7 @@ async def _track_subscription_payment_success(user: User, invoice: dict) -> None
metadata = _invoice_subscription_metadata(invoice)
tier = (
metadata.get("tier")
- or (user.subscriptionTier or SubscriptionTier.NO_TIER).value
+ or SubscriptionTier(user.subscriptionTier or SubscriptionTier.NO_TIER).value
)
billing_cycle = metadata.get("billing_cycle") or (
await get_user_billing_cycle(user.id) or "monthly"
diff --git a/autogpt_platform/backend/backend/data/credit_subscription_test.py b/autogpt_platform/backend/backend/data/credit_subscription_test.py
index 11c0807837..6fafde5b12 100644
--- a/autogpt_platform/backend/backend/data/credit_subscription_test.py
+++ b/autogpt_platform/backend/backend/data/credit_subscription_test.py
@@ -13,6 +13,8 @@ from prisma.models import User
from backend.data.credit import (
UserCredit,
+ _is_stripe_reconcilable,
+ build_price_to_tier_map,
cancel_stripe_subscription,
create_subscription_checkout,
get_pending_subscription_change,
@@ -52,10 +54,9 @@ async def test_set_subscription_tier_updates_db():
patch("backend.data.credit.get_user_by_id"),
):
await set_subscription_tier("user-1", SubscriptionTier.PRO)
- mock_prisma.return_value.update.assert_awaited_once_with(
- where={"id": "user-1"},
- data={"subscriptionTier": SubscriptionTier.PRO},
- )
+ update_call = mock_prisma.return_value.update.await_args
+ assert update_call.kwargs["where"] == {"id": "user-1"}
+ assert update_call.kwargs["data"]["subscriptionTier"] == SubscriptionTier.PRO
@pytest.mark.asyncio
@@ -321,6 +322,40 @@ async def test_sync_subscription_from_stripe_cancelled():
mock_set.assert_awaited_once_with("user-1", SubscriptionTier.NO_TIER)
+async def test_sync_subscription_from_stripe_past_due_downgrades_to_no_tier():
+ """``past_due`` is NOT active/trialing, so it falls into the non-active else
+ branch: with no OTHER active/trialing sub, the user is revoked to NO_TIER.
+
+ This locks the product decision that an unpaid (past_due) subscription
+ immediately loses its tier rather than coasting until cancellation."""
+ mock_user = _make_user(tier=SubscriptionTier.PRO)
+ stripe_sub = {
+ "id": "sub_pastdue",
+ "customer": "cus_123",
+ "status": "past_due",
+ "items": {"data": [{"price": {"id": "price_pro_monthly"}}]},
+ }
+ empty_list = MagicMock()
+ empty_list.data = []
+ empty_list.has_more = False
+ with (
+ patch(
+ "backend.data.credit.User.prisma",
+ return_value=MagicMock(find_first=AsyncMock(return_value=mock_user)),
+ ),
+ patch(
+ "backend.data.credit.stripe.Subscription.list",
+ return_value=empty_list,
+ ),
+ patch(
+ "backend.data.credit.set_subscription_tier", new_callable=AsyncMock
+ ) as mock_set,
+ ):
+ await sync_subscription_from_stripe(stripe_sub)
+ mock_set.assert_awaited_once_with("user-1", SubscriptionTier.NO_TIER)
+
+
@pytest.mark.asyncio
async def test_sync_subscription_from_stripe_cancelled_applies_no_tier_storage_limit():
"""After unsubscribe takes effect, workspace storage resolves against NO_TIER."""
@@ -337,7 +372,10 @@ async def test_sync_subscription_from_stripe_cancelled_applies_no_tier_storage_l
empty_list.data = []
empty_list.has_more = False
- async def _set_tier(_user_id: str, tier: SubscriptionTier) -> None:
+ async def _set_tier(
+ _user_id: str,
+ tier: SubscriptionTier,
+ ) -> None:
mock_user.subscriptionTier = tier
with (
@@ -4502,3 +4540,85 @@ async def test_modify_stripe_subscription_tier_upgrade_yearly_still_immediate():
_, kwargs = mock_modify.call_args
assert kwargs["proration_behavior"] == "always_invoice"
mock_schedule_create.assert_not_called()
+
+
+def _reconcilable_user(tier: SubscriptionTier, customer_id: str | None) -> MagicMock:
+ user = MagicMock()
+ user.subscription_tier = tier
+ user.stripe_customer_id = customer_id
+ return user
+
+
+def test_is_stripe_reconcilable_payer():
+ # Stripe customer on a paid, non-ENTERPRISE tier -> reconcilable.
+ user = _reconcilable_user(SubscriptionTier.PRO, "cus_1")
+ assert _is_stripe_reconcilable(user) is True
+
+
+def test_is_stripe_reconcilable_enterprise_immune():
+ # ENTERPRISE is never auto-downgraded, even with a Stripe customer.
+ user = _reconcilable_user(SubscriptionTier.ENTERPRISE, "cus_1")
+ assert _is_stripe_reconcilable(user) is False
+
+
+def test_is_stripe_reconcilable_manual_grant_without_customer():
+ # A paid tier with no Stripe customer models a manual/admin grant.
+ user = _reconcilable_user(SubscriptionTier.PRO, None)
+ assert _is_stripe_reconcilable(user) is False
+
+
+def test_is_stripe_reconcilable_no_tier_with_customer():
+ # NO_TIER with a Stripe customer is still reconcilable (a missed-upgrade row).
+ user = _reconcilable_user(SubscriptionTier.NO_TIER, "cus_1")
+ assert _is_stripe_reconcilable(user) is True
+
+
+def test_is_stripe_reconcilable_free_user():
+ user = _reconcilable_user(SubscriptionTier.NO_TIER, None)
+ assert _is_stripe_reconcilable(user) is False
+
+
+async def test_build_price_to_tier_map_includes_monthly_and_yearly():
+ """Every priceable tier's monthly AND yearly price ID must map back to that
+ tier, so a yearly plan resolves to the same tier as its monthly twin."""
+
+ async def mock_price_id(
+ tier: SubscriptionTier, billing_cycle: str = "monthly"
+ ) -> str | None:
+ return f"price_{tier.value.lower()}_{billing_cycle}"
+
+ with patch(
+ "backend.data.credit.get_subscription_price_id", side_effect=mock_price_id
+ ):
+ price_to_tier = await build_price_to_tier_map()
+
+ for tier in (
+ SubscriptionTier.BASIC,
+ SubscriptionTier.PRO,
+ SubscriptionTier.MAX,
+ SubscriptionTier.BUSINESS,
+ ):
+ assert price_to_tier[f"price_{tier.value.lower()}_monthly"] == tier
+ assert price_to_tier[f"price_{tier.value.lower()}_yearly"] == tier
+
+
+async def test_build_price_to_tier_map_skips_unconfigured_prices():
+ """A tier/cycle with no configured price ID (None) is simply omitted from
+ the map rather than crashing or mapping an empty key."""
+
+ async def mock_price_id(
+ tier: SubscriptionTier, billing_cycle: str = "monthly"
+ ) -> str | None:
+ # Only PRO monthly is configured.
+ if tier == SubscriptionTier.PRO and billing_cycle == "monthly":
+ return "price_pro_monthly"
+ return None
+
+ with patch(
+ "backend.data.credit.get_subscription_price_id", side_effect=mock_price_id
+ ):
+ price_to_tier = await build_price_to_tier_map()
+
+ assert price_to_tier == {"price_pro_monthly": SubscriptionTier.PRO}
diff --git a/autogpt_platform/backend/backend/data/db_manager.py b/autogpt_platform/backend/backend/data/db_manager.py
index 3b01a04146..ef65b731c7 100644
--- a/autogpt_platform/backend/backend/data/db_manager.py
+++ b/autogpt_platform/backend/backend/data/db_manager.py
@@ -105,6 +105,7 @@ from backend.data.push_subscription import (
get_user_push_subscriptions,
increment_fail_count,
)
+from backend.data.stripe_reconciliation import reconcile_all_stripe_tiers
from backend.data.understanding import (
get_business_understanding,
upsert_business_understanding,
@@ -370,6 +371,9 @@ class DatabaseManager(AppService):
cleanup_failed_subscriptions, name="cleanup_failed_push_subscriptions"
)
+ # ============ Subscription Reconciliation ============ #
+ reconcile_all_stripe_tiers = _(reconcile_all_stripe_tiers)
+
# ============ Platform Linking ============ #
find_server_link_owner = _(platform_linking_db.find_server_link_owner)
find_user_link_owner = _(platform_linking_db.find_user_link_owner)
@@ -615,6 +619,9 @@ class DatabaseManagerAsyncClient(AppServiceClient):
increment_push_fail_count = d.increment_push_fail_count
cleanup_failed_push_subscriptions = d.cleanup_failed_push_subscriptions
+ # ============ Subscription Reconciliation ============ #
+ reconcile_all_stripe_tiers = d.reconcile_all_stripe_tiers
+
# ============ Platform Linking ============ #
find_server_link_owner = d.find_server_link_owner
find_user_link_owner = d.find_user_link_owner
diff --git a/autogpt_platform/backend/backend/data/stripe_reconciliation.py b/autogpt_platform/backend/backend/data/stripe_reconciliation.py
new file mode 100644
index 0000000000..c98b0db591
--- /dev/null
+++ b/autogpt_platform/backend/backend/data/stripe_reconciliation.py
@@ -0,0 +1,281 @@
+"""Periodic Stripe → DB subscription-tier reconciliation sweep.
+
+Webhooks give low-latency tier updates; this sweep is the safety net that makes
+Stripe the eventual source of truth. It pages through every active/trialing
+Stripe subscription once, builds an authoritative ``{customer_id -> tier}`` map,
+then for every reconcilable user (has a Stripe customer, not ENTERPRISE) sets the
+tier from the map (NO_TIER when the customer is absent). Manual grants (no Stripe
+customer) and ENTERPRISE rows are never touched.
+
+Cost: one Stripe ``Subscription.list`` pass (not one call per user). The sweep
+skips users whose tier already matches the map (``target_tier == current_tier``
+in ``_reconcile_one``), so a steady-state run does no DB writes.
+"""
+
+import logging
+
+import stripe
+from fastapi.concurrency import run_in_threadpool
+from prisma.enums import SubscriptionTier
+from prisma.models import User
+from pydantic import BaseModel
+
+from backend.data.credit import (
+ alert_tier_reconciliation_discrepancy,
+ build_price_to_tier_map,
+ log_tier_reconciliation_discrepancy,
+ set_subscription_tier,
+)
+
+logger = logging.getLogger(__name__)
+
+# Cap how many per-user lines are inlined into the Discord ops alert so a mass
+# incident doesn't post a wall of text; the full set is in the logs/PostHog.
+_ALERT_DETAIL_CAP = 25
+
+# Bound the Stripe pagination so a runaway/unexpected dataset can't loop forever.
+# At 100 subs/page this caps a single sweep at 500k subscriptions; if it's ever
+# hit the sweep logs and stops rather than silently truncating without notice.
+_MAX_SUBSCRIPTION_PAGES = 5000
+_PAGE_SIZE = 100
+
+
+class TierDiscrepancy(BaseModel):
+ """One Stripe<->DB tier mismatch the sweep had to correct."""
+
+ user_id: str
+ stripe_customer_id: str | None
+ previous_tier: SubscriptionTier
+ new_tier: SubscriptionTier
+ direction: str
+
+
+class ReconciliationSummary(BaseModel):
+ """Counts produced by one reconciliation sweep."""
+
+ stripe_active_subscriptions: int = 0
+ candidate_users: int = 0
+ upgrades: int = 0
+ downgrades: int = 0
+ unchanged: int = 0
+ errors: int = 0
+ skipped_incomplete: int = 0
+ pagination_capped: bool = False
+ discrepancies: list[TierDiscrepancy] = []
+
+
+async def reconcile_all_stripe_tiers() -> ReconciliationSummary:
+ """Reconcile every reconcilable user against live Stripe subscriptions."""
+ customer_to_tier = await _build_customer_tier_map()
+ summary = ReconciliationSummary(
+ stripe_active_subscriptions=len(customer_to_tier.tiers),
+ pagination_capped=customer_to_tier.capped,
+ )
+ # Match `_is_stripe_reconcilable`: every user with a Stripe customer that is
+ # not on ENTERPRISE. This covers paid payers as well as paid-but-NO_TIER rows
+ # left by a missed upgrade webhook. Manual grants (no customer) and ENTERPRISE
+ # stay excluded.
+ candidates = await User.prisma().find_many(
+ where={
+ "stripeCustomerId": {"not": None},
+ "subscriptionTier": {"not": SubscriptionTier.ENTERPRISE},
+ },
+ )
+ summary.candidate_users = len(candidates)
+ map_complete = not customer_to_tier.capped
+ for user in candidates:
+ await _reconcile_one(user, customer_to_tier.tiers, summary, map_complete)
+ logger.info(
+ "reconcile_all_stripe_tiers: active_subs=%d candidates=%d upgrades=%d"
+ " downgrades=%d unchanged=%d skipped_incomplete=%d errors=%d capped=%s",
+ summary.stripe_active_subscriptions,
+ summary.candidate_users,
+ summary.upgrades,
+ summary.downgrades,
+ summary.unchanged,
+ summary.skipped_incomplete,
+ summary.errors,
+ summary.pagination_capped,
+ )
+ if summary.discrepancies:
+ await _alert_sweep_discrepancies(summary)
+ return summary
+
+
+async def _alert_sweep_discrepancies(summary: ReconciliationSummary) -> None:
+ """Loudly surface that the sweep had to correct tiers.
+
+ A non-empty sweep means Stripe webhooks were dropped or missed — a payments-
+ integrity incident, not a routine correction. Steady state must be ZERO, so
+ any correction pages the ops channel and logs at ERROR (→ Sentry).
+ """
+ lines = "\n".join(
+ f"- {d.direction}: {d.previous_tier.value} → {d.new_tier.value} "
+ f"user={d.user_id} customer={d.stripe_customer_id}"
+ for d in summary.discrepancies[:_ALERT_DETAIL_CAP]
+ )
+ overflow = len(summary.discrepancies) - _ALERT_DETAIL_CAP
+ if overflow > 0:
+ lines += f"\n…and {overflow} more"
+ logger.error(
+ "Stripe tier reconciliation sweep corrected %d discrepancy(ies) "
+ "(%d downgrade, %d upgrade) — Stripe webhooks are likely dropping events; "
+ "steady state must be ZERO.",
+ len(summary.discrepancies),
+ summary.downgrades,
+ summary.upgrades,
+ )
+ await alert_tier_reconciliation_discrepancy(
+ f"🚨 **Stripe tier reconciliation sweep corrected "
+ f"{len(summary.discrepancies)} discrepancy(ies)** "
+ f"({summary.downgrades} downgrade, {summary.upgrades} upgrade).\n"
+ f"Each means a Stripe webhook was likely missed — **investigate the "
+ f"webhook pipeline**; this is a payments-integrity signal, not a routine "
+ f"correction. Steady state must be ZERO.\n{lines}"
+ )
+
+
+async def _reconcile_one(
+ user: User,
+ customer_to_tier: dict[str, SubscriptionTier],
+ summary: ReconciliationSummary,
+ map_complete: bool,
+) -> None:
+ """Set one user's tier from the Stripe map, updating the summary counts."""
+ current_tier = SubscriptionTier(user.subscriptionTier or SubscriptionTier.NO_TIER)
+ target_tier = SubscriptionTier.NO_TIER
+ if user.stripeCustomerId:
+ target_tier = customer_to_tier.get(
+ user.stripeCustomerId, SubscriptionTier.NO_TIER
+ )
+ if target_tier == current_tier:
+ summary.unchanged += 1
+ return
+ # When the Stripe snapshot is incomplete (a failed list page or the
+ # pagination cap), absence from the map is unreliable — the user may sit on
+ # a page we never fetched. Never revoke a tier off a partial snapshot;
+ # upgrades (the customer IS in the map) stay safe.
+ in_map = bool(user.stripeCustomerId) and user.stripeCustomerId in customer_to_tier
+ if not map_complete and not in_map:
+ summary.skipped_incomplete += 1
+ return
+ try:
+ await set_subscription_tier(user.id, target_tier)
+ except Exception:
+ summary.errors += 1
+ logger.exception(
+ "reconcile_all_stripe_tiers: failed to set tier for user %s",
+ user.id[:8],
+ )
+ return
+ direction = log_tier_reconciliation_discrepancy(
+ user_id=user.id,
+ stripe_customer_id=user.stripeCustomerId,
+ previous_tier=current_tier,
+ new_tier=target_tier,
+ via="sweep",
+ )
+ summary.discrepancies.append(
+ TierDiscrepancy(
+ user_id=user.id,
+ stripe_customer_id=user.stripeCustomerId,
+ previous_tier=current_tier,
+ new_tier=target_tier,
+ direction=direction,
+ )
+ )
+ # Reuse the rank-based direction (not a NO_TIER check) so a paid->paid
+ # downgrade (e.g. MAX->PRO) is counted as a downgrade, not an upgrade.
+ if direction == "downgrade":
+ summary.downgrades += 1
+ else:
+ summary.upgrades += 1
+
+
+class _CustomerTierMap(BaseModel):
+ tiers: dict[str, SubscriptionTier]
+ capped: bool
+
+
+async def _build_customer_tier_map() -> _CustomerTierMap:
+ """Page through all active+trialing Stripe subs into a customer→tier map.
+
+ A customer with multiple active subs resolves to their highest tier so a
+ leftover lower-tier sub never downgrades a user mid-upgrade.
+ """
+ price_to_tier = await build_price_to_tier_map()
+ tiers: dict[str, SubscriptionTier] = {}
+ capped = False
+ for status in ("active", "trialing"):
+ page_capped = await _collect_status_page(status, price_to_tier, tiers)
+ capped = capped or page_capped
+ return _CustomerTierMap(tiers=tiers, capped=capped)
+
+
+async def _collect_status_page(
+ status: str,
+ price_to_tier: dict[str, SubscriptionTier],
+ tiers: dict[str, SubscriptionTier],
+) -> bool:
+ """Accumulate one Stripe status's subscriptions into ``tiers``. Returns
+ True if pagination was capped before exhausting the dataset."""
+ starting_after: str | None = None
+ for _ in range(_MAX_SUBSCRIPTION_PAGES):
+ list_kwargs: dict = {"status": status, "limit": _PAGE_SIZE}
+ if starting_after:
+ list_kwargs["starting_after"] = starting_after
+ try:
+ subs = await run_in_threadpool(stripe.Subscription.list, **list_kwargs)
+ except stripe.StripeError:
+ # A Stripe outage/rate-limit must not abort the whole sweep. Stop
+ # this status and flag the run incomplete so we don't downgrade users
+ # off a partial map (treated like the pagination cap below).
+ logger.exception(
+ "reconcile_all_stripe_tiers: Stripe list failed for status=%s;"
+ " reconciliation is incomplete this run",
+ status,
+ )
+ return True
+ for sub in subs.data:
+ _record_subscription(sub, price_to_tier, tiers)
+ if not subs.has_more or not subs.data:
+ return False
+ starting_after = subs.data[-1].id
+ logger.warning(
+ "reconcile_all_stripe_tiers: hit %d-page cap for status=%s; remaining"
+ " subscriptions not reconciled this run",
+ _MAX_SUBSCRIPTION_PAGES,
+ status,
+ )
+ return True
+
+
+def _record_subscription(
+ sub: stripe.Subscription,
+ price_to_tier: dict[str, SubscriptionTier],
+ tiers: dict[str, SubscriptionTier],
+) -> None:
+ """Map one subscription's customer to its tier, keeping the highest tier."""
+ customer = sub.get("customer")
+ if not isinstance(customer, str) or not customer:
+ return
+ items = sub.get("items", {}).get("data", [])
+ if not items:
+ return
+ price_id = items[0].get("price", {}).get("id", "")
+ tier = price_to_tier.get(price_id) if price_id else None
+ if tier is None:
+ return
+ existing = tiers.get(customer)
+ if existing is None or _TIER_RANK[tier] > _TIER_RANK[existing]:
+ tiers[customer] = tier
+
+
+_TIER_RANK: dict[SubscriptionTier, int] = {
+ SubscriptionTier.NO_TIER: 0,
+ SubscriptionTier.BASIC: 1,
+ SubscriptionTier.PRO: 2,
+ SubscriptionTier.MAX: 3,
+ SubscriptionTier.BUSINESS: 4,
+ SubscriptionTier.ENTERPRISE: 5,
+}
diff --git a/autogpt_platform/backend/backend/data/stripe_reconciliation_test.py b/autogpt_platform/backend/backend/data/stripe_reconciliation_test.py
new file mode 100644
index 0000000000..0a6949b53b
--- /dev/null
+++ b/autogpt_platform/backend/backend/data/stripe_reconciliation_test.py
@@ -0,0 +1,472 @@
+"""Tests for the periodic Stripe → DB tier reconciliation sweep."""
+
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+import pytest_mock
+import stripe
+from prisma.enums import SubscriptionTier
+
+from backend.data.stripe_reconciliation import (
+ ReconciliationSummary,
+ _collect_status_page,
+ _record_subscription,
+ reconcile_all_stripe_tiers,
+)
+
+
+class _SubDict(dict):
+ """A subscription mapping that also exposes ``.id`` as an attribute, mirroring
+ Stripe's StripeObject (dict-like .get() AND attribute access on the id used
+ by the pagination cursor ``subs.data[-1].id``)."""
+
+ @property
+ def id(self) -> str:
+ return self["id"]
+
+
+def _sub(customer: str, price_id: str) -> dict:
+ return _SubDict(
+ {
+ "id": f"sub_{customer}",
+ "customer": customer,
+ "items": {"data": [{"price": {"id": price_id}}]},
+ }
+ )
+
+
+def _candidate(
+ user_id: str,
+ customer_id: str | None,
+ tier: SubscriptionTier,
+) -> MagicMock:
+ user = MagicMock()
+ user.id = user_id
+ user.stripeCustomerId = customer_id
+ user.subscriptionTier = tier
+ return user
+
+
+def _patch_stripe_pages(
+ mocker: pytest_mock.MockFixture, by_status: dict[str, list[dict]]
+) -> None:
+ """Make stripe.Subscription.list return one page per status."""
+
+ def _list(*, status: str, limit: int, starting_after: str | None = None):
+ page = MagicMock()
+ page.data = by_status.get(status, [])
+ page.has_more = False
+ return page
+
+ mocker.patch(
+ "backend.data.stripe_reconciliation.stripe.Subscription.list",
+ side_effect=_list,
+ )
+
+
[email protected](autouse=True)
+def mock_alert(mocker: pytest_mock.MockFixture) -> AsyncMock:
+ """Patch the Discord ops alert for every test so none hits the network."""
+ return mocker.patch(
+ "backend.data.stripe_reconciliation.alert_tier_reconciliation_discrepancy",
+ new_callable=AsyncMock,
+ )
+
+
+async def test_sweep_upgrades_downgrades_and_skips_unchanged(
+ mocker: pytest_mock.MockFixture,
+ mock_alert: AsyncMock,
+) -> None:
+ mocker.patch(
+ "backend.data.stripe_reconciliation.build_price_to_tier_map",
+ new_callable=AsyncMock,
+ return_value={"price_pro": SubscriptionTier.PRO},
+ )
+ _patch_stripe_pages(
+ mocker,
+ {"active": [_sub("cus_keep", "price_pro"), _sub("cus_up", "price_pro")]},
+ )
+ candidates = [
+ # already PRO with active PRO sub -> unchanged
+ _candidate("u_keep", "cus_keep", SubscriptionTier.PRO),
+ # NO_TIER with active PRO sub -> upgrade
+ _candidate("u_up", "cus_up", SubscriptionTier.NO_TIER),
+ # PRO with no active sub -> downgrade
+ _candidate("u_down", "cus_gone", SubscriptionTier.PRO),
+ ]
+ mocker.patch(
+ "backend.data.stripe_reconciliation.User.prisma",
+ return_value=MagicMock(find_many=AsyncMock(return_value=candidates)),
+ )
+ set_tier = mocker.patch(
+ "backend.data.stripe_reconciliation.set_subscription_tier",
+ new_callable=AsyncMock,
+ )
+
+ summary = await reconcile_all_stripe_tiers()
+
+ assert summary.upgrades == 1
+ assert summary.downgrades == 1
+ assert summary.unchanged == 1
+ assert summary.errors == 0
+ set_tier.assert_any_await("u_up", SubscriptionTier.PRO)
+ set_tier.assert_any_await("u_down", SubscriptionTier.NO_TIER)
+ # Each correction is recorded, and the sweep alerts ops exactly once (not
+ # per-user) with the discrepancy counts.
+ assert {d.direction for d in summary.discrepancies} == {"upgrade", "downgrade"}
+ assert len(summary.discrepancies) == 2
+ mock_alert.assert_awaited_once()
+ alert_msg = mock_alert.await_args.args[0]
+ assert "2 discrepancy" in alert_msg
+ assert "1 downgrade" in alert_msg and "1 upgrade" in alert_msg
+
+
+async def test_sweep_counts_paid_to_paid_downgrade_as_downgrade(
+ mocker: pytest_mock.MockFixture,
+ mock_alert: AsyncMock,
+) -> None:
+ """MAX -> PRO is a downgrade even though the target isn't NO_TIER."""
+ mocker.patch(
+ "backend.data.stripe_reconciliation.build_price_to_tier_map",
+ new_callable=AsyncMock,
+ return_value={"price_pro": SubscriptionTier.PRO},
+ )
+ _patch_stripe_pages(mocker, {"active": [_sub("cus_x", "price_pro")]})
+ mocker.patch(
+ "backend.data.stripe_reconciliation.User.prisma",
+ return_value=MagicMock(
+ find_many=AsyncMock(
+ return_value=[_candidate("u_x", "cus_x", SubscriptionTier.MAX)]
+ )
+ ),
+ )
+ mocker.patch(
+ "backend.data.stripe_reconciliation.set_subscription_tier",
+ new_callable=AsyncMock,
+ )
+
+ summary = await reconcile_all_stripe_tiers()
+
+ assert summary.downgrades == 1
+ assert summary.upgrades == 0
+ assert summary.discrepancies[0].direction == "downgrade"
+
+
+async def test_sweep_no_discrepancies_does_not_alert(
+ mocker: pytest_mock.MockFixture,
+ mock_alert: AsyncMock,
+) -> None:
+ """Steady state (every candidate already correct) must stay silent."""
+ mocker.patch(
+ "backend.data.stripe_reconciliation.build_price_to_tier_map",
+ new_callable=AsyncMock,
+ return_value={"price_pro": SubscriptionTier.PRO},
+ )
+ _patch_stripe_pages(mocker, {"active": [_sub("cus_keep", "price_pro")]})
+ mocker.patch(
+ "backend.data.stripe_reconciliation.User.prisma",
+ return_value=MagicMock(
+ find_many=AsyncMock(
+ return_value=[_candidate("u_keep", "cus_keep", SubscriptionTier.PRO)]
+ )
+ ),
+ )
+ mocker.patch(
+ "backend.data.stripe_reconciliation.set_subscription_tier",
+ new_callable=AsyncMock,
+ )
+
+ summary = await reconcile_all_stripe_tiers()
+
+ assert summary.unchanged == 1
+ assert summary.discrepancies == []
+ mock_alert.assert_not_awaited()
+
+
+async def test_sweep_queries_reconcilable_users(
+ mocker: pytest_mock.MockFixture,
+) -> None:
+ """Candidates mirror `_is_stripe_reconcilable`: every user with a Stripe
+ customer that is not on ENTERPRISE."""
+ mocker.patch(
+ "backend.data.stripe_reconciliation.build_price_to_tier_map",
+ new_callable=AsyncMock,
+ return_value={},
+ )
+ _patch_stripe_pages(mocker, {})
+ find_many = AsyncMock(return_value=[])
+ mocker.patch(
+ "backend.data.stripe_reconciliation.User.prisma",
+ return_value=MagicMock(find_many=find_many),
+ )
+ mocker.patch(
+ "backend.data.stripe_reconciliation.set_subscription_tier",
+ new_callable=AsyncMock,
+ )
+
+ await reconcile_all_stripe_tiers()
+
+ find_many.assert_awaited_once_with(
+ where={
+ "stripeCustomerId": {"not": None},
+ "subscriptionTier": {"not": SubscriptionTier.ENTERPRISE},
+ },
+ )
+
+
+async def test_sweep_incomplete_map_skips_downgrades(
+ mocker: pytest_mock.MockFixture,
+ mock_alert: AsyncMock,
+) -> None:
+ """A failed/partial Stripe snapshot must never downgrade an absent user."""
+ mocker.patch(
+ "backend.data.stripe_reconciliation.build_price_to_tier_map",
+ new_callable=AsyncMock,
+ return_value={"price_pro": SubscriptionTier.PRO},
+ )
+ # Stripe list fails -> _collect_status_page returns capped -> map incomplete.
+ mocker.patch(
+ "backend.data.stripe_reconciliation.stripe.Subscription.list",
+ side_effect=stripe.StripeError("rate limited"),
+ )
+ candidates = [_candidate("u_down", "cus_gone", SubscriptionTier.PRO)]
+ mocker.patch(
+ "backend.data.stripe_reconciliation.User.prisma",
+ return_value=MagicMock(find_many=AsyncMock(return_value=candidates)),
+ )
+ set_tier = mocker.patch(
+ "backend.data.stripe_reconciliation.set_subscription_tier",
+ new_callable=AsyncMock,
+ )
+
+ summary = await reconcile_all_stripe_tiers()
+
+ assert summary.pagination_capped is True
+ assert summary.skipped_incomplete == 1
+ assert summary.downgrades == 0
+ set_tier.assert_not_called()
+ mock_alert.assert_not_awaited()
+
+
+async def test_sweep_counts_errors_without_aborting(
+ mocker: pytest_mock.MockFixture,
+) -> None:
+ mocker.patch(
+ "backend.data.stripe_reconciliation.build_price_to_tier_map",
+ new_callable=AsyncMock,
+ return_value={"price_pro": SubscriptionTier.PRO},
+ )
+ _patch_stripe_pages(mocker, {"active": [_sub("cus_ok", "price_pro")]})
+ candidates = [
+ _candidate("u_err", "cus_gone", SubscriptionTier.PRO),
+ _candidate("u_ok", "cus_ok", SubscriptionTier.NO_TIER),
+ ]
+ mocker.patch(
+ "backend.data.stripe_reconciliation.User.prisma",
+ return_value=MagicMock(find_many=AsyncMock(return_value=candidates)),
+ )
+ mocker.patch(
+ "backend.data.stripe_reconciliation.set_subscription_tier",
+ new_callable=AsyncMock,
+ side_effect=[RuntimeError("db down"), None],
+ )
+
+ summary = await reconcile_all_stripe_tiers()
+
+ assert summary.errors == 1
+ assert summary.upgrades == 1
+
+
+def test_record_subscription_keeps_highest_tier() -> None:
+ tiers: dict[str, SubscriptionTier] = {}
+ price_to_tier = {
+ "price_basic": SubscriptionTier.BASIC,
+ "price_pro": SubscriptionTier.PRO,
+ }
+ _record_subscription(_sub("cus_x", "price_basic"), price_to_tier, tiers)
+ _record_subscription(_sub("cus_x", "price_pro"), price_to_tier, tiers)
+ assert tiers["cus_x"] == SubscriptionTier.PRO
+ # A subsequent lower-tier sub must not clobber the higher tier already seen.
+ _record_subscription(_sub("cus_x", "price_basic"), price_to_tier, tiers)
+ assert tiers["cus_x"] == SubscriptionTier.PRO
+
+
+def test_record_subscription_ignores_unknown_price() -> None:
+ tiers: dict[str, SubscriptionTier] = {}
+ _record_subscription(_sub("cus_y", "price_unknown"), {}, tiers)
+ assert "cus_y" not in tiers
+
+
+def test_record_subscription_skips_missing_customer() -> None:
+ tiers: dict[str, SubscriptionTier] = {}
+ price_to_tier = {"price_pro": SubscriptionTier.PRO}
+ # customer None and empty string are both ignored without crashing.
+ _record_subscription(
+ {
+ "id": "s1",
+ "customer": None,
+ "items": {"data": [{"price": {"id": "price_pro"}}]},
+ },
+ price_to_tier,
+ tiers,
+ )
+ _record_subscription(
+ {
+ "id": "s2",
+ "customer": "",
+ "items": {"data": [{"price": {"id": "price_pro"}}]},
+ },
+ price_to_tier,
+ tiers,
+ )
+ assert tiers == {}
+
+
+def test_record_subscription_skips_missing_items() -> None:
+ tiers: dict[str, SubscriptionTier] = {}
+ price_to_tier = {"price_pro": SubscriptionTier.PRO}
+ # Missing 'items' entirely, and an empty items list, are both skipped.
+ _record_subscription({"id": "s1", "customer": "cus_a"}, price_to_tier, tiers)
+ _record_subscription(
+ {"id": "s2", "customer": "cus_b", "items": {"data": []}}, price_to_tier, tiers
+ )
+ assert "cus_a" not in tiers
+ assert "cus_b" not in tiers
+
+
+def test_record_subscription_skips_missing_price_id() -> None:
+ tiers: dict[str, SubscriptionTier] = {}
+ price_to_tier = {"price_pro": SubscriptionTier.PRO}
+ # Price object with no/None id resolves to no tier -> customer not added.
+ _record_subscription(
+ {"id": "s1", "customer": "cus_a", "items": {"data": [{"price": {}}]}},
+ price_to_tier,
+ tiers,
+ )
+ _record_subscription(
+ {"id": "s2", "customer": "cus_b", "items": {"data": [{"price": {"id": ""}}]}},
+ price_to_tier,
+ tiers,
+ )
+ assert tiers == {}
+
+
+def _page(data: list[dict], has_more: bool) -> MagicMock:
+ page = MagicMock()
+ page.data = data
+ page.has_more = has_more
+ return page
+
+
+async def test_collect_status_page_follows_pagination(
+ mocker: pytest_mock.MockFixture,
+) -> None:
+ """Multiple pages are followed via starting_after = last item id until
+ has_more=False, accumulating every page's subscriptions into the map."""
+ pages = [
+ _page([_sub("cus_a", "price_basic")], has_more=True),
+ _page([_sub("cus_b", "price_pro")], has_more=False),
+ ]
+ seen_starting_after: list[str | None] = []
+
+ def _list(*, status: str, limit: int, starting_after: str | None = None):
+ seen_starting_after.append(starting_after)
+ return pages.pop(0)
+
+ mocker.patch(
+ "backend.data.stripe_reconciliation.stripe.Subscription.list",
+ side_effect=_list,
+ )
+ price_to_tier = {
+ "price_basic": SubscriptionTier.BASIC,
+ "price_pro": SubscriptionTier.PRO,
+ }
+ tiers: dict[str, SubscriptionTier] = {}
+
+ capped = await _collect_status_page("active", price_to_tier, tiers)
+
+ assert capped is False
+ assert tiers == {"cus_a": SubscriptionTier.BASIC, "cus_b": SubscriptionTier.PRO}
+ # First call has no cursor; second passes the first page's last item id.
+ assert seen_starting_after == [None, "sub_cus_a"]
+
+
+async def test_collect_status_page_highest_tier_wins_across_pages(
+ mocker: pytest_mock.MockFixture,
+) -> None:
+ """A customer appearing with different tiers on different pages resolves to
+ the highest tier regardless of which page it appeared on first."""
+ price_to_tier = {
+ "price_basic": SubscriptionTier.BASIC,
+ "price_pro": SubscriptionTier.PRO,
+ }
+
+ def _run(first_price: str, second_price: str) -> dict[str, SubscriptionTier]:
+ pages = [
+ _page([_sub("cus_c", first_price)], has_more=True),
+ _page([_sub("cus_c2", second_price)], has_more=False),
+ ]
+ # Reuse the same customer id across both pages.
+ pages[0].data[0]["customer"] = "cus_c"
+ pages[1].data[0]["customer"] = "cus_c"
+ return pages
+
+ for first, second in (("price_basic", "price_pro"), ("price_pro", "price_basic")):
+ pages = _run(first, second)
+ mocker.patch(
+ "backend.data.stripe_reconciliation.stripe.Subscription.list",
+ side_effect=lambda *, status, limit, starting_after=None: pages.pop(0),
+ )
+ tiers: dict[str, SubscriptionTier] = {}
+ await _collect_status_page("active", price_to_tier, tiers)
+ assert tiers == {"cus_c": SubscriptionTier.PRO}
+
+
+async def test_collect_status_page_stops_at_cap(
+ mocker: pytest_mock.MockFixture,
+) -> None:
+ """When Stripe never stops returning has_more=True, the loop bails at the
+ page cap and reports capped=True rather than looping forever."""
+ mocker.patch("backend.data.stripe_reconciliation._MAX_SUBSCRIPTION_PAGES", 3)
+ call_count = {"n": 0}
+
+ def _list(*, status: str, limit: int, starting_after: str | None = None):
+ call_count["n"] += 1
+ return _page([_sub(f"cus_{call_count['n']}", "price_pro")], has_more=True)
+
+ mocker.patch(
+ "backend.data.stripe_reconciliation.stripe.Subscription.list",
+ side_effect=_list,
+ )
+ tiers: dict[str, SubscriptionTier] = {}
+
+ capped = await _collect_status_page(
+ "active", {"price_pro": SubscriptionTier.PRO}, tiers
+ )
+
+ assert capped is True
+ # Stopped exactly at the (patched) cap, not beyond.
+ assert call_count["n"] == 3
+
+
+def test_summary_defaults_to_zero() -> None:
+ assert ReconciliationSummary().model_dump() == {
+ "stripe_active_subscriptions": 0,
+ "candidate_users": 0,
+ "upgrades": 0,
+ "downgrades": 0,
+ "unchanged": 0,
+ "errors": 0,
+ "skipped_incomplete": 0,
+ "pagination_capped": False,
+ "discrepancies": [],
+ }
diff --git a/autogpt_platform/backend/backend/executor/scheduler.py b/autogpt_platform/backend/backend/executor/scheduler.py
index 5b9dfadeeb..592b14e3fc 100644
--- a/autogpt_platform/backend/backend/executor/scheduler.py
+++ b/autogpt_platform/backend/backend/executor/scheduler.py
@@ -95,6 +95,9 @@ config = Config()
# Timeout constants
SCHEDULER_OPERATION_TIMEOUT_SECONDS = 300 # 5 minutes for scheduler operations
+# The Stripe tier sweep pages through every active subscription, so it needs a
+# generous ceiling relative to the per-op default.
+STRIPE_RECONCILE_TIMEOUT_SECONDS = 1800 # 30 minutes
def job_listener(event):
@@ -448,6 +451,16 @@ def cleanup_platform_link_tokens():
run_async(_cleanup())
+def reconcile_stripe_tiers():
+ """Reconcile all STRIPE-sourced user tiers against live Stripe state."""
+
+ async def _reconcile():
+ db = get_database_manager_async_client()
+ return await db.reconcile_all_stripe_tiers()
+
+ run_async(_reconcile(), timeout=STRIPE_RECONCILE_TIMEOUT_SECONDS)
+
+
def execution_accuracy_alerts():
"""Check execution accuracy and send alerts if drops are detected."""
return report_execution_accuracy_alerts()
@@ -959,6 +972,19 @@ class Scheduler(AppService):
jobstore=Jobstores.EXECUTION.value,
)
+ # Stripe Subscription Tier Reconciliation - configurable interval
+ # Safety net for missed/lost Stripe webhooks: makes Stripe the
+ # eventual source of truth for STRIPE-sourced tiers (incl. downgrades).
+ self.scheduler.add_job(
+ reconcile_stripe_tiers,
+ id="reconcile_stripe_tiers",
+ trigger="interval",
+ replace_existing=True,
+ max_instances=1, # Prevent overlapping sweeps
+ seconds=config.stripe_tier_reconcile_interval_hours * 3600,
+ jobstore=Jobstores.EXECUTION.value,
+ )
+
# Execution Accuracy Monitoring - configurable interval
self.scheduler.add_job(
execution_accuracy_alerts,
diff --git a/autogpt_platform/backend/backend/executor/scheduler_unit_test.py b/autogpt_platform/backend/backend/executor/scheduler_unit_test.py
index 1af876e79e..a24f7cac68 100644
--- a/autogpt_platform/backend/backend/executor/scheduler_unit_test.py
+++ b/autogpt_platform/backend/backend/executor/scheduler_unit_test.py
@@ -18,12 +18,14 @@ from backend.executor.scheduler import (
CopilotTurnJobInfo,
GraphExecutionJobArgs,
GraphExecutionJobInfo,
+ Scheduler,
_build_trigger,
_execute_copilot_turn,
_job_to_info,
_next_run_time_iso,
_reschedule_one_shot_after_cap,
_self_delete_copilot_turn_schedule,
+ reconcile_stripe_tiers,
)
_SCHEDULER_PATH = "backend.executor.scheduler"
@@ -415,3 +417,60 @@ def test_copilot_turn_args_cap_retry_count_defaults_to_zero():
run_at=datetime.now(tz=timezone.utc),
)
assert args.cap_retry_count == 0
+
+
+# ---------------------------------------------------------------------------
+# System-job registration — the Stripe tier reconciliation sweep
+# ---------------------------------------------------------------------------
+
+
+def _registered_jobs(monkeypatch, interval_hours: int) -> list:
+ """Drive ``Scheduler.run_service`` with every heavy dependency stubbed and
+ a mock APScheduler, returning the list of ``add_job`` mock calls."""
+ monkeypatch.setattr(
+ f"{_SCHEDULER_PATH}.config.stripe_tier_reconcile_interval_hours",
+ interval_hours,
+ )
+ mock_scheduler = MagicMock()
+ with (
+ patch(f"{_SCHEDULER_PATH}.BackgroundScheduler", return_value=mock_scheduler),
+ patch(f"{_SCHEDULER_PATH}.load_dotenv"),
+ patch(f"{_SCHEDULER_PATH}.asyncio.new_event_loop", return_value=MagicMock()),
+ patch(f"{_SCHEDULER_PATH}.threading.Thread", return_value=MagicMock()),
+ patch(f"{_SCHEDULER_PATH}.create_engine", return_value=MagicMock()),
+ patch(f"{_SCHEDULER_PATH}.SQLAlchemyJobStore", return_value=MagicMock()),
+ patch(f"{_SCHEDULER_PATH}.MemoryJobStore", return_value=MagicMock()),
+ patch(
+ f"{_SCHEDULER_PATH}._extract_schema_from_url",
+ return_value=("public", "sqlite://"),
+ ),
+ patch(f"{_SCHEDULER_PATH}.ensure_embeddings_coverage", return_value=None),
+ # super().run_service() blocks forever keeping the service alive; no-op it.
+ patch("backend.util.service.AppService.run_service", return_value=None),
+ ):
+ Scheduler(register_system_tasks=True).run_service()
+ return mock_scheduler.add_job.call_args_list
+
+
+def test_reconcile_stripe_tiers_job_registered_with_interval_and_single_instance(
+ monkeypatch,
+):
+ """The sweep must be registered as an interval job keyed off the configured
+ interval setting and capped to a single concurrent instance."""
+ calls = _registered_jobs(monkeypatch, interval_hours=6)
+
+ matches = [c for c in calls if c.args and c.args[0] is reconcile_stripe_tiers]
+ assert len(matches) == 1
+ call = matches[0]
+ assert call.kwargs["id"] == "reconcile_stripe_tiers"
+ assert call.kwargs["trigger"] == "interval"
+ assert call.kwargs["max_instances"] == 1
+ # 6 hours -> 6 * 3600 seconds, driven by the config setting.
+ assert call.kwargs["seconds"] == 6 * 3600
+
+
+def test_reconcile_stripe_tiers_interval_follows_config_setting(monkeypatch):
+ """Changing the configured interval changes the registered ``seconds``."""
+ calls = _registered_jobs(monkeypatch, interval_hours=12)
+ match = next(c for c in calls if c.args and c.args[0] is reconcile_stripe_tiers)
+ assert match.kwargs["seconds"] == 12 * 3600
diff --git a/autogpt_platform/backend/backend/util/settings.py b/autogpt_platform/backend/backend/util/settings.py
index e27cbeb0c3..17e68227c7 100644
--- a/autogpt_platform/backend/backend/util/settings.py
+++ b/autogpt_platform/backend/backend/util/settings.py
@@ -464,6 +464,16 @@ class Config(UpdateTrackingModel["Config"], BaseSettings):
description="Hours between platform link token cleanup runs (1-24 hours)",
)
+ stripe_tier_reconcile_interval_hours: int = Field(
+ default=6,
+ ge=1,
+ le=168,
+ description=(
+ "Hours between periodic Stripe subscription-tier reconciliation "
+ "sweeps (1-168 hours)"
+ ),
+ )
+
upload_file_size_limit_mb: int = Field(
default=256,
ge=1,