AddThisFeature

Stripe Customer and Subscription Sync

Keep local billing state matching Stripe as subscriptions, invoices, and plans change.

involved Payments & Finance

What it adds

A verified event pipeline that projects Stripe customer, subscription, and invoice state onto the app's own access records, with reconciliation for anything the pipeline missed.

What your agent is told to do

5
  1. 1

    Define one local projection of billing state per account: which plan, which status, which period it runs to, and whether access is currently allowed. Every entitlement check in the app reads that projection and nothing else.

  2. 2

    Verify every incoming event as genuinely from the provider before acting on it, and record its identifier so a replay is recognised and ignored. Providers retry on any non-success response, so handlers must be safe to run repeatedly.

  3. 3

    Store a timestamp or version with the projection and refuse to apply an event that is older than what has already been written. Events arrive out of order, and a stale cancellation overwriting a fresh renewal locks a paying customer out.

  4. 4

    Build a reconciliation pass that reads current state from the provider for a given account and repairs the projection, and make it runnable for one account or for all of them. Every event pipeline eventually misses something.

  5. 5

    First-payment checkout flow is owned by the Stripe Checkout brief. This brief owns everything after: renewals, plan changes, invoices, and access revocation. One event handler, in this brief, and the checkout brief defers to it.

Edge cases it handles

8
  • Verified provider events are the authority over local guesses, but they do not arrive in order. Apply them by their own sequence or timestamp rather than by arrival, or a late event will undo a newer one.
  • The same event will be delivered more than once. Persist processed event identifiers and make each handler produce the same result on the second run as on the first, including the ones that create invoices or send email.
  • A billing customer must resolve to exactly one tenant. If an event arrives for a customer nobody owns, park it for an operator to look at rather than attaching it to a plausible-looking account.
  • Trials, paused subscriptions, scheduled plan changes, cancellations that take effect at period end, and past-due delinquency are all distinct states with different access consequences. Cancelled-but-still-paid-until must keep access; past-due must not silently keep it forever.
  • Drift will happen. Provide a repair or backfill path that can rebuild an account's projection from the provider's current state, and log what it changed so an operator can see what the pipeline missed.
  • A handler that fails partway through must not leave the projection half-updated. Write the change atomically, and if the event cannot be processed, return a failure so the provider retries rather than swallowing it.
  • When the provider is unreachable, existing access must continue on the last known projection rather than being revoked. Never treat an inability to check as evidence of non-payment.
  • Downgrades and revocations affect what the user can see and do. Decide what happens to data over the new plan's limits, and tell the user before it becomes unreachable.

Definition of done

9
  • Every entitlement check in the app reads a single local billing projection.
  • Unverified events are rejected and duplicate deliveries produce no repeated side effects.
  • Out-of-order events cannot overwrite newer state.
  • Trials, pauses, scheduled changes, cancellations, and delinquency each map to a defined access outcome.
  • A reconciliation pass repairs an account's projection from provider state and reports what it corrected.
  • Events for an unmapped customer are quarantined for review rather than guessed at.
  • A provider outage preserves existing access rather than revoking it.
  • The feature matches the existing design system.
  • No existing functionality is broken.

Related features

How it works

  1. 1

    Copy the link

    Grab the Markdown instruction URL for this feature.

  2. 2

    Give it to your AI

    Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.

  3. 3

    It inspects, then implements

    Your agent reads your existing app first, then adds the feature to fit it.

Works with your stack

These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.

Need it tighter than that? Customize the feature and tell it exactly what you're running.