AddThisFeature

Paddle Subscription Checkout

Sell subscriptions through Paddle with entitlements granted only by verified events.

involved Payments & Finance

What it adds

A Paddle-backed subscription purchase and lifecycle flow where local access follows verified server events and prices stay under server control.

What your agent is told to do

5
  1. 1

    Hold the catalogue mapping on the server: which local plan corresponds to which provider offering, at which price and currency. The client passes a plan identifier and nothing about money.

  2. 2

    Carry an account or workspace reference into the checkout so the subscription that comes back can be attached to the right tenant without matching on email address.

  3. 3

    Grant access only from verified server-side events, and store the event identifier so a retried delivery changes nothing a second time.

  4. 4

    Project the subscription's status onto a single local access record that every permission check in the app reads, so entitlement is answered from one place rather than recomputed per screen.

  5. 5

    This brief owns the whole lifecycle for this provider: purchase, renewal, change, and revocation. If a Stripe or Lemon Squeezy brief is also applied, they must write into the same local access record rather than each keeping their own.

Edge cases it handles

8
  • The checkout's own completion callback in the browser proves only that the browser saw a success screen. Never grant an entitlement from it; show a pending state and let the verified server event do the granting.
  • A completed checkout must map to exactly one account. If the reference is missing or points at an account that no longer exists, quarantine the event for an operator rather than matching on a name or an email that may belong to someone else.
  • Provider events are retried until acknowledged and can arrive out of order. Verify them, deduplicate on their identifier, and refuse to apply one older than the state already recorded.
  • Trials, pauses, cancellations effective at period end, refunds, and past-due states each imply different access. A cancellation scheduled for the end of the term must not revoke access today, and a past-due account must not keep access forever.
  • Prices, currencies, and tax-inclusive totals must come from trusted server configuration. Tax-inclusive display means the amount shown differs by region, and letting the client choose the price makes that impossible to reconcile.
  • Invoices and receipts must reflect the tax treatment actually applied, and the app should link to the provider's own document rather than reproducing figures that may not match.
  • When the provider is unreachable, keep existing subscribers working on the last known access record. An inability to check is not evidence of non-payment.
  • A user who upgrades or downgrades mid-term will see a proration the app did not calculate. Show the provider's figure rather than an estimate that will disagree with the invoice.

Definition of done

9
  • Plan, price, and currency come from server configuration and are never accepted from the client.
  • Access is granted only by verified server events, never by a client-side checkout callback.
  • Each subscription resolves to exactly one account, and unmatched events are quarantined for review.
  • Duplicate and out-of-order events leave local state correct.
  • Trials, pauses, cancellations, refunds, and past-due each produce a defined access outcome.
  • All permission checks read one local access record.
  • A provider outage preserves existing subscriber access.
  • 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.