stripe-billing

Stripe billing

Stripe holds the money. Your database holds the entitlement. Every serious billing defect is one fact living in two systems that stopped agreeing — a price, a quantity, a period, a refunded total.

Stripe's API is not where integrations fail. Failures happen at the seam: the callback that arrived twice, the renewal that granted a month of product for a $0.40 proration invoice, the upgrade that charged the card and then failed to write the row.

This skill is that seam. For which Stripe primitive to use, the official stripe-best-practices skill is the authority and wins any disagreement; for lookups, stripe-docs. Examples are TypeScript; the rules are language-neutral.

Deep material, loaded on demand:

Read	When
references/stripe-agent-toolchain.md	starting from nothing, or about to guess an API shape — CLI, MCP, skills index, key handling
references/webhook-events.md	writing or reviewing the handler — event catalogue, payload shapes, ordering, failure semantics
references/subscription-lifecycle.md	implementing checkout, verify, renewal, seats, plan change, trials, clawback
references/cancellation-and-retention.md	implementing cancel or reactivation, or offering a coupon at the cancel step
references/price-integrity.md	pricing lives in more than one file, or an advertised price must be proved against Stripe
references/testing-and-local-dev.md	local webhooks and mocks, and the shipped fixtures/ — the suite, already written
references/provider-concentration.md	growing revenue, opening a second market, separating involuntary churn, or if the payment account is limited

---

Start with Stripe's own tooling

Stripe ships its own MCP server, CLI and agent skills; the API moves monthly, so reach for them first. This skill owns the seams they do not: which signal is the payment, what the redirect proves, and where money gets counted twice. Commands in references/stripe-agent-toolchain.md.

The two ledgers

   browser                  your server                    Stripe
      │  choose plan ──────────►│
      │                         │  create checkout session ──►│
      │◄──────── url ───────────│◄──── session + hosted page ─│
      │  pays on Stripe's page ─┼────────────────────────────►│
      │◄─ redirect (proves nothing) ────────────────────────  │
      │                         │◄──── webhook (at-least-once)│
      │                         │  write entitlement          │
      │                         │◄──── webhook (again, later) │
                                 └── nightly: reconcile ─────►│

Amounts, tax, invoices, dunning and payment methods are Stripe's. Who may use what, how many seats and what credit was granted are yours. The link between them is ids, and nothing else.

One home per fact. Copy an amount out of Stripe into your code and you own the drift — silently, because checkout sends a price id and Stripe holds the number. A wrong amount never fails a request; it is only ever shown to customers. See references/price-integrity.md.

---

The client

let client: Stripe | null = null;

export function getStripe(): Stripe {
  if (!client) {
    const key = process.env.STRIPE_SECRET_KEY;
    if (!key) throw new Error("STRIPE_SECRET_KEY is not set");
    // Pin checked 2026-08-30 — 2026-08-26.dahlia was already newer. Confirm
    // against Stripe's changelog before pinning; this line goes stale monthly.
    client = new Stripe(key, { apiVersion: "2026-07-29.dahlia", maxNetworkRetries: 2 });
  }
  return client;
}

• Lazy, not module-level. A new Stripe(...) at import time crashes every build step that imports the module without a key.
• Pin apiVersion. Unpinned, response shapes change on Stripe's schedule rather than yours. Upgrades are a task (stripe:upgrade-stripe), not a deploy-day surprise.
• maxNetworkRetries, never a hand-rolled loop. The SDK generates an idempotency key per request, which is the only thing that makes retrying a write safe. A loop around subscriptions.create buys two subscriptions for one intent. For deliberate retries, pass your own stable { idempotencyKey }.

---

Products, prices, two modes

Checkout takes a price; your code should speak product. Prices are replaced when you reprice; products are stable.

• One Product per plan a customer can choose. Several Prices on one Product only for variants of the same plan (monthly vs annual, per currency). Tiers sharing a Product make every invoice line read the same name and destroy the product-id → plan mapping the rest of your code depends on.
• Pin price ids in configuration, keep prices.list({ active: true }) as the fallback. After a reprice a product has two active prices, in an order nobody promised.
• Validation allowlists need ids from both modes. Your database holds rows written in test and rows written in live; a webhook checking "do we sell this" against only the current mode rejects real history.
• resource_missing almost always means mode mismatch. Catch it and say so, naming the mode and the key prefix — raw, it reads as "product deleted".

---

Get-or-create customer is a race

Two tabs, two requests, two customers, and the second silently owns the subscription the first is charging. Create, then claim the id with a conditional update; if the update matched no row you lost the race, so delete the orphan customer and read the winner's id. Before creating, retrieve the stored id and treat resource_missing or deleted: true as "create a new one" — the normal state after a key rotation. The code is in references/subscription-lifecycle.md.

---

Checkout session

const metadata = { userId, productId, quantity: String(qty) };

await stripe.checkout.sessions.create({
  customer: customerId,
  mode: "subscription",
  line_items: [{ price: priceId, quantity: qty }],
  // Never pass payment_method_types — Stripe picks eligible methods from
  // Dashboard settings; hardcoding ['card'] locks out methods that convert.
  metadata,                                 // reaches checkout.session.completed
  subscription_data: { metadata },          // reaches EVERY later subscription event
  success_url: `${origin}/after?session_id={CHECKOUT_SESSION_ID}`,
  cancel_url: `${origin}/plans`,
});

1. Write metadata twice. Session metadata does not propagate to the subscription. Renewal invoices and every customer.subscription.* event carry the subscription — a year later the session is gone and the only userId you have is the one in subscription_data.metadata.
2. Validate caller-supplied return URLs against your own origin. An endpoint that passes a body-supplied successUrl through is an open redirect wearing a payment flow.
3. Guard duplicates before the money moves, not after: an active subscription to the same product answers 409 with the existing id. A second active subscription for one seat is a refund conversation.

{CHECKOUT_SESSION_ID} is substituted by Stripe, not rendered by you. On 2026-03-25.dahlia+ an integration_identifier label lets you compare flows in the Dashboard (floor checked 2026-08-30 against Stripe's changelog).

Three decisions belong to stripe-best-practices: usage-based billing (Metronome for anything new; Billing Meters is a low-level primitive), tax (automatic_tax collects nothing until a registration exists — enabling it is not compliance), and Connect when money routes to third parties.

---

The webhook is the payment

export async function POST(request: Request) {
  const body = await request.text();                    // RAW — not parsed JSON
  const signature = request.headers.get("stripe-signature");
  if (!signature) return json({ error: "missing signature" }, 400);

  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(body, signature, process.env.STRIPE_WEBHOOK_SECRET!);
  } catch {
    return json({ error: "invalid signature" }, 400);    // no detail — it is an oracle
  }

  const claim = await claimEvent(event.id);              // INSERT on a primary key
  if (claim === "completed") return json({ received: true, duplicate: true });
  if (claim === "in_flight") return json({ error: "in flight" }, 500); // retry later

  try {
    await handle(event);
  } catch {
    await releaseEventClaim(event.id);                   // let the retry back in
    return json({ error: "handler error" }, 500);
  }
  return json({ received: true });
}

• Raw body. Re-serializing a parsed body changes bytes and the signature fails. Disable auto-parsing for this route.
• Exempt this path — and only this path — from CSRF and session auth, by exact match: a prefix match over /api/billing exempts checkout too, which is where the money is.
• Claim before working — a claim is a receipt, not completion. SELECT then INSERT is a race; two deliveries 40 ms apart both credit. The row stays processing until the grant's transaction marks it completed — states, expiry, takeover and release: references/webhook-events.md.
• Answer honestly. 200 handled or duplicate, 400 bad signature, 5xx try again, 200 for types you do not handle. Never 200 on failure to stop retries — that discards a payment quietly.
• Order inside a handler: fallible external calls first, then one transaction — entitlement, dedup marker, completion, outbox rows — then side effects drain from the outbox, each under its own consumer key.

Per-event detail: references/webhook-events.md.

---

The redirect proves a browser

Stripe redirects when the card clears; the webhook lands when it lands. In that window the user is on your success page and your database knows nothing.

Ship a verify endpoint the success page calls: retrieve the session, check metadata.userId equals the caller, check status === "complete" and payment_status !== "unpaid", then perform exactly the writes the webhook would — and let the unique constraint arbitrate. Whoever loses catches the duplicate-key error and reports success.

The ownership check is security-critical: without it, any authenticated user who learns a cs_… id claims someone else's purchase. This is also the only way local development works — but it is a safety net, never the primary path. A user who closes the tab must still get what they paid for.

---

Renewal: billing_reason decides

invoice.paid fires for several different things. Granting product on all of them is the most expensive mistake in this document.

billing_reason	What it is	Grant?
subscription_create	first invoice	no — checkout did it
subscription_cycle	the renewal	yes
subscription_update	mid-cycle proration	no
manual, subscription_threshold	an invoice you or a meter raised	explicitly

A quantity change emits subscription_update immediately. If that path grants, a user who adds and removes a seat four times has been given four months of product for four proration invoices.

Read the period from the subscription item — sub.items.data[0].current_period_start / current_period_end. Recent API versions moved it; code reading the old top-level fields gets undefined and stores an epoch date, with no error.

Guard the grant with a marker (lastGrantedPeriodStart, or an audit row keyed by invoice id) checked inside the same transaction as the grant, so the webhook and the reconciliation job cannot both grant one period.

---

billing_mode — a one-way choice made at creation

Stripe creates every subscription in one of two billing modes. The choice is made at subscriptions.create (or subscription_data on a Checkout session), cannot be reversed, and Stripe recommends flexible for new subscriptions.

It is in the body because it changes arithmetic the next sections teach: under flexible mode a credit proration is computed from the amount originally debited, so one change can emit several credit prorations where classic emitted one. Code that takes [0] of the proration lines breaks quietly in the clawback path — the one place here where a wrong number is money. It also decides which field records a scheduled cancellation. Choosing between the modes is a product decision stripe-best-practices owns.

Seats and proration

• proration_behavior: always_invoice bills now, create_prorations defers to the next invoice, none adjusts nothing — the right choice for a revert. The call, with its compensating revert, is in references/subscription-lifecycle.md.
• payment_behavior: "error_if_incomplete" on upgrades. Without it a declined card leaves the subscription upgraded and unpaid while your database agrees with the upgrade. Catch StripeCardError and answer 402.
• Write ordering: Stripe first, then your database. If the database write fails, revert Stripe with proration_behavior: "none" and log a revert failure loudly — that is the one state a human must fix. The reverse order bills for seats Stripe never sold.
• Cap quantity server-side, floor it at 1. Removing the last seat is a cancellation and goes through that path. Reducing below what is in use is a business decision: answer 409 with what must be released, and let the user choose which.

---

Cancellation, and the offer that deflects it

• At period end is the default — the user keeps what they paid for and status stays active. Under flexible billing_mode a portal cancellation sets cancel_at and leaves cancel_at_period_end false — derive "is cancelling" from both fields, never from the boolean alone.
• Do the teardown in customer.subscription.deleted, never beside the API call, so one path serves your UI, the portal and dunning alike.
• On invoice.payment_failed, mark past_due and notify — do not cancel. Stripe's dunning decides the retries and the terminal state.
• A save offer's eligibility is yours. Stripe cannot answer "was this customer already discounted" — a duration=once discount leaves subscription.discounts at finalization — so track eligibility yourself.

Both, with the code: references/cancellation-and-retention.md.

Refunds arrive cumulative

charge.amount_refunded is the total refunded so far, not this refund. Two partial refunds deliver 4000 then 9000; read as an increment, that claws back $130 against a $90 charge. Compute the increment against a stored total and write it with a compare-and-swap, so a concurrent delivery loses rather than clawing back twice — the code is in references/subscription-lifecycle.md.

A refund belongs either to a one-off payment (find it by payment_intent) or to a subscription invoice (no purchase row — resolve charge.invoice → invoice → subscription). Handle both, or subscription refunds silently leave the customer holding the product.

Reconciliation

Webhooks are best-effort and outages are not hypothetical. Run a job that lists subscriptions with status: "all", creates what is missing, and updates status, period, quantity and price where they differ — sequentially, because each iteration opens a transaction and may call an external API. Any grant it performs reuses the webhook's idempotency marker, or a nightly job becomes a nightly gift.

The guard that matters: mark local rows canceled when Stripe has no such subscription, excluding rows that were never Stripe's. Comped, manual and other-provider plans carry synthetic ids, and cancelling them is a self-inflicted outage. The code, and the "Sync now" button it doubles as, are in references/subscription-lifecycle.md.

Money is minor units: convert once, at the boundary, and compare in integer cents — Math.abs(20.83 - 20.84) > 0.01 is true in floating point.

---

Depending on one provider

One provider for card payments is a single point of failure for revenue, and the decision belongs to the business rather than to this skill. What the code owes it is a seam: keep the charge behind an interface, keep the customer id yours, and never let a Stripe object id be the only key to a paying account. The argument, the migration shapes and the cost are in references/provider-concentration.md.

Local development and the test matrix

Both in references/testing-and-local-dev.md — stripe listen --forward-to, the CLI trigger verbs, the test cards and decline codes, and the clock tricks for renewal and proration. The one thing to know before you get there: the signing secret stripe listen prints is not the dashboard's, and using the wrong one fails verification in a way that reads like a key problem.

Degradation

• Not Claude Code (Cursor, Codex, the skills CLI, the API container): the PreToolUse money gate this pack ships does not exist there — nothing refuses a refund, a payout, a dispute close or a live sk_live_… key on your behalf. Every rule below still holds; it is advice again rather than a precondition, so the authorisation step becomes a human one. Say which you are on before acting on money.
• Installed by copy rather than as a plugin: same loss, same remedy — a plain ~/.claude/skills/ copy carries the doctrine and not hooks/money-gate.js. The README names the categories and how one is signed off; without the hook, that sign-off is a sentence somebody has to actually say.
• No Stripe CLI, no network, or test keys only: webhook signature verification and the local replay loop are the parts that need the binary. State which is missing once, do the rest, and record what could not be verified rather than implying it was.

Before you ship

Not a second checklist — every rule below already has a section above, and a rule with two homes drifts at one of them. These are the four whose failure is money rather than an error page:

1. The webhook is the payment. Never grant on the redirect (§ The webhook is the payment, § The redirect proves a browser).
2. Verify the signature against the raw body. A parsed body fails verification for a reason that reads like a key problem.
3. Every handler is idempotent on event.id. Stripe retries, and a retry that grants twice is a refund conversation.
4. Reconcile on a schedule. A webhook that never arrived leaves a paid customer without access, and nothing in the logs says so (§ Reconciliation).

The full security checklist lives in references/stripe-agent-toolchain.md; every pitfall it used to list is stated where the rule is, which is the only place it can be kept true.