Stripe Billing skill for Codex

Done well means: your database mirrors each Stripe subscription from webhooks, access is granted from that mirror (never from a redirect), plan changes preview their proration before the customer confirms, and a full billing cycle (trial, renewal, failed payment, recovery, cancellation) has been simulated with a test clock.

Before writing code

1. Read AGENTS.md and find the existing stripe client, webhook route, user/account model and any plan or entitlement columns.
2. Note the pinned API version. Since 2025-03-31.basil, current_period_start and current_period_end live on subscription items (sub.items.data[0].current_period_end), not on the subscription. Older code reading sub.current_period_end breaks after an upgrade.
3. Decide the billing unit with the user: per account, per seat, or metered. It drives the data model and cannot be changed cheaply later.
4. Live-mode actions (cancelling, refunding, migrating real customers between prices, changing portal configuration) need explicit user confirmation.

Data model

Store per customer account: stripe_customer_id (create one Customer per account, once), stripe_subscription_id, status, price_id, current_period_end, cancel_at_period_end, and a derived entitlement (plan tier, seat count). Keep Prices in config keyed by plan and interval: PRICES.pro.monthly = 'price_...'.

Grant access from status:

Subscription status	Access	Notes
trialing, active	Yes
past_due	Yes, with a banner	Smart Retries are running; decide a grace period
incomplete	No	First payment needs action (3DS) or failed
incomplete_expired, canceled	No	Terminal
unpaid	No	Retries exhausted, invoices left open
paused	No	Trial ended without a payment method, or paused collection

Start a subscription

const session = await stripe.checkout.sessions.create(
  {
    mode: "subscription",
    customer: account.stripeCustomerId,        // create the Customer first and reuse it
    line_items: [{ price: PRICES.pro.monthly, quantity: seats }],
    subscription_data: {
      trial_period_days: 14,
      metadata: { accountId: account.id },
    },
    client_reference_id: account.id,
    success_url: `${APP_URL}/billing?session_id={CHECKOUT_SESSION_ID}`,
    cancel_url: `${APP_URL}/pricing`,
  },
  { idempotencyKey: `sub-checkout-${account.id}-${PRICES.pro.monthly}` },
);

Block a second Checkout while the account already has a non-terminal subscription, or customers end up paying twice.

Sync from webhooks

Handle these and upsert the mirror by subscription ID; re-fetch the subscription from the API inside the handler instead of trusting event order:

• customer.subscription.created / updated / deleted
• invoice.paid (extend access, record the period)
• invoice.payment_failed (notify, show banner)
• invoice.payment_action_required (send the hosted invoice link for 3DS)
• customer.subscription.trial_will_end (three days before trial end)

async function syncSubscription(subId: string) {
  const sub = await stripe.subscriptions.retrieve(subId);
  const item = sub.items.data[0];
  await db.accounts.update({
    where: { stripeCustomerId: sub.customer as string },
    data: {
      stripeSubscriptionId: sub.id,
      status: sub.status,
      priceId: item.price.id,
      seats: item.quantity ?? 1,
      currentPeriodEnd: new Date(item.current_period_end * 1000),
      cancelAtPeriodEnd: sub.cancel_at_period_end,
    },
  });
}

For the full event-to-action table, including invoice-level edge cases and ordering, read references/webhook-state-machine.md when wiring the handler or debugging drift.

Webhook signature verification is identical to one-time payments; see $stripe-payments.

Plan changes and proration

Change	Default	Setting
Upgrade (more expensive or more seats)	Charge the difference now	proration_behavior: 'always_invoice'
Downgrade	Apply at renewal, no credit	Subscription Schedule, or store intent and switch on invoice.upcoming
Quantity change, prorated on next invoice	Accrue proration items	proration_behavior: 'create_prorations' (the API default)
Interval change (monthly to yearly)	Bill immediately, reset anchor	billing_cycle_anchor: 'now' plus always_invoice

// Preview before confirming: show the customer the exact amount
const preview = await stripe.invoices.createPreview({
  customer: account.stripeCustomerId,
  subscription: sub.id,
  subscription_details: {
    items: [{ id: sub.items.data[0].id, price: PRICES.business.monthly }],
    proration_behavior: "always_invoice",
  },
});
// After the customer confirms in the UI:
await stripe.subscriptions.update(sub.id, {
  items: [{ id: sub.items.data[0].id, price: PRICES.business.monthly }],
  proration_behavior: "always_invoice",
  payment_behavior: "pending_if_incomplete", // keep the old plan if the charge fails
});

Always pass the existing item id when swapping a price. Passing only price adds a second item and bills both.

Cancellation

• Default to cancel_at_period_end: true (customer keeps access until period end). Immediate cancellation with stripe.subscriptions.cancel(id) should be a deliberate, confirmed choice.
• Offer reactivation by setting cancel_at_period_end: false before the period ends.

Customer portal

const portal = await stripe.billingPortal.sessions.create({
  customer: account.stripeCustomerId,
  return_url: `${APP_URL}/billing`,
});

Configure allowed actions (cancel, switch plans, update payment method, invoice history) in the Dashboard or via billingPortal.configurations. Portal changes fire the same subscription webhooks, so the mirror stays correct without extra code.

Usage-based billing

Create a Meter, attach a metered Price to it, then report usage:

await stripe.billing.meterEvents.create({
  event_name: "api_requests",
  payload: { stripe_customer_id: account.stripeCustomerId, value: "120" },
  identifier: `usage-${account.id}-${batchId}`, // dedupes retries
});

Aggregate locally and send batches; do not send one meter event per API call. Legacy usage records were removed in the basil API versions; migrate old usage_records code to meters.

Dunning

• Enable Smart Retries and failed-payment emails in Billing settings, and decide the final action after retries (cancel, mark unpaid, or leave past due).
• On invoice.payment_failed, show an in-app banner with a portal link; do not cut access on the first failure.

Gotchas

• Creating a new Customer per checkout: duplicate customers, split history, broken portal.
• Reading subscription.current_period_end on a basil-or-later API version: it is undefined.
• Granting access on checkout.session.completed alone: the subscription can still be incomplete. Check the subscription status.
• Trial without collecting a card: set trial_settings.end_behavior.missing_payment_method deliberately (cancel, pause or create_invoice).
• Timezones: periods are Unix seconds UTC. Convert once, at the boundary.
• Changing a Price’s amount is impossible; create a new Price and migrate subscriptions on purpose, with user approval for live customers.

Verification with test clocks

const clock = await stripe.testHelpers.testClocks.create({ frozen_time: Math.floor(Date.now() / 1000) });
// create a Customer with test_clock: clock.id, subscribe it, then advance:
await stripe.testHelpers.testClocks.advance(clock.id, { frozen_time: nowPlus(15, "days") });

Run the cycle: trial ends and converts, renewal succeeds, switch the payment method to pm_card_chargeCustomerFail and advance to see past_due, recover, then cancel at period end. After each step, compare the database row with stripe subscriptions retrieve <id>.

Report template

**Plans:** pro/business x monthly/yearly (Price IDs in config/billing.ts)
**Mirror:** accounts.status, price_id, seats, current_period_end (from subscription items)
**Webhooks handled:** customer.subscription.*, invoice.paid, invoice.payment_failed, invoice.payment_action_required
**Proration:** upgrades always_invoice with preview; downgrades at renewal
**Test clock run:** trial -> active -> past_due -> active -> canceled, mirror matched at each step
**Needs user:** portal configuration, Smart Retries policy, live migration of existing customers