Skip to content

fix(billing): keep Stripe subscriptions in sync with tenants - #1760

Merged
mattwoberts merged 2 commits into
mainfrom
fix/stripe-subscription-sync
Nov 4, 2026
Merged

mattwoberts merged 2 commits into
mainfrom
fix/stripe-subscription-sync

Conversation

@mattwoberts

@mattwoberts mattwoberts commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Fixes #1740.

Problem

After setup-mode Checkout, the webhook creates the subscription itself. If the first off-session charge is declined or needs 3-D Secure, the subscription comes back incomplete and we stored nothing. If the customer later paid the open invoice, the subscription went active and was billed every period, but the tenant stayed on Free and "Manage billing" couldn't find it. Stripe doesn't retry that first charge, so the old comment's assumption ("Stripe will keep retrying and eventually fire subscription.deleted") was wrong.

The same review turned up other ways billing could get out of sync with tenants:

  • Wrong downgrade: customer.subscription.deleted downgraded the tenant for any subscription with its tenant_id, including a duplicate, while the real one was still being paid.
  • Duplicate subscription on resend: the idempotency key (session.ID) only lasts 24h, but Stripe retries webhooks for 3 days and the Dashboard can resend them for 15. A late redelivery created and charged a second subscription.
  • Orphaned subscription: two completed Checkout sessions for one tenant (e.g. a stale tab) created two subscriptions. The second overwrote the stored customer, so the first kept billing and couldn't be reached from the portal.

Changes

  • Handle customer.subscription.updated when previous_attributes.status is incomplete. The handler re-fetches the subscription so late or out-of-order events act on its current state, then activates the tenant the same way checkout does.
  • CancelStripeSubscription only clears the stored subscription and downgrades when the deleted subscription matches it (Result reports whether it did).
  • The setup-checkout handler reuses a subscription already on the session's customer. Every Checkout session creates its own customer (CustomerCreation=always), so any subscription found there came from an earlier delivery of the same event.
  • A tenant whose stored subscription is still live (not canceled, incomplete_expired or missing at Stripe) never gets a second one. No new subscription is created (the card is saved but nothing is charged), and an already-charged one isn't activated. Both cases are logged at error level for a manual refund.

Deploy

Failed-payment settings are already compatible: retries leave the subscription past_due, then cancel it. That fires deleted, which downgrades the tenant.

Testing

  • Sandbox, with a test clock: paying an incomplete subscription's invoice fires customer.subscription.updated with previous status incomplete. Expiry to incomplete_expired fires only updated, never deleted.
  • End to end (local server + stripe listen, sandbox):
    • An incomplete subscription that is paid later activates the tenant.
    • Cancelling a duplicate subscription is ignored.
    • Cancelling the real subscription downgrades the tenant.
  • Automated: new handler tests in app/handlers/webhooks/stripe_test.go (fake Stripe API, signed payloads) and a DB test for the cancel guard. The [BUG] Stripe: a subscription created incomplete is never activated when its first invoice is paid later #1740 test fails on main.
  • Lint is clean and the full Go test suite passes.

🤖 Generated with Claude Code

mattwoberts and others added 2 commits November 4, 2026 20:19
- Activate the tenant when a subscription created `incomplete` is paid
  later (customer.subscription.updated, previous status incomplete).
  Re-fetch the subscription so late/out-of-order events act on its
  current state. Fixes #1740.
- Only downgrade on customer.subscription.deleted when the deleted
  subscription is the tenant's stored one.
- Reuse a subscription already on the Checkout customer instead of
  creating another: the idempotency key expires after 24h but webhooks
  are retried for 3 days and can be resent for 15.
- Never create or activate a second live subscription for a tenant;
  log it for manual refund instead of orphaning the first.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ed checkout

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mattwoberts
mattwoberts added this pull request to the merge queue Nov 4, 2026
Merged via the queue into main with commit a0d3d49 Nov 4, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[BUG] Stripe: a subscription created incomplete is never activated when its first invoice is paid later

1 participant