SuperAPI AI Directory

checkout

Coding & development

View repository

Updated 10-16 06:09

About this skill

Autumn Checkout Guide

When to Use This Skill

  • Debugging Autumn checkout creation, retrieval, preview, or confirmation
  • Understanding why billing.attach returned an Autumn checkout URL
  • Working on server/src/internal/checkouts/
  • Changing how checkout previews are rendered or confirmed
  • Determining whether a flow should use autumn_checkout, stripe_checkout, or no checkout
  • Explaining the attach confirmation flow to another agent quickly

Core Concept

Autumn checkout is not a separate billing engine. It is a thin confirmation layer around the existing V2 attach action.

  • attach() still does the normal setup -> compute -> evaluate flow
  • If the attach context resolves to checkoutMode === "autumn_checkout", Autumn does not execute billing immediately
  • Instead, it stores a lightweight checkout object containing the original attach params
  • Public checkout routes later re-run attach from those stored params to build a fresh preview or to execute billing on confirm

This means the checkout does not persist a frozen billing plan. It persists the request, then recomputes from current state.

Entry Point

Main path:

  1. server/src/internal/billing/v2/actions/attach/attach.ts
  2. server/src/internal/billing/v2/actions/attach/createAutumnCheckout.ts
  3. server/src/internal/billing/v2/utils/billingPlan/billingPlanToAutumnCheckout.ts
  4. server/src/internal/checkouts/middleware/checkoutMiddleware.ts
  5. server/src/internal/checkouts/handlers/handleGetCheckout.ts
  6. server/src/internal/checkouts/handlers/handlePreviewCheckout.ts
  7. server/src/internal/checkouts/handlers/handleConfirmCheckout.ts

Attach -> Autumn Checkout

attach() follows the normal V2 pipeline first:

const billingContext = await setupAttachBillingContext(...)
const autumnBillingPlan = computeAttachPlan(...)
const stripeBillingPlan = await evaluateStripeBillingPlan(...)
await handleAttachV2Errors(...)

After that, the branch is simple:

if (billingContext.checkoutMode === "autumn_checkout" && !skipAutumnCheckout) {
  return await createAutumnCheckout(...)
}

return await executeBillingPlan(...)

Important consequences:

  • Autumn checkout is decided after the billing plan exists
  • Validation already ran before the checkout is created
  • skipAutumnCheckout: true is the escape hatch used by confirm so the second attach call executes billing instead of creating another checkout

What Gets Stored

billingPlanToAutumnCheckout() builds a Checkout record with:

  • id
  • org_id
  • env
  • internal_customer_id
  • customer_id
  • action: "attach"
  • params
  • params_version
  • status: "pending"
  • created_at
  • expires_at

Storage model:

  • Cache is the primary store via setCheckoutCache()
  • Postgres is written as audit/backup via checkoutRepo.insert()
  • TTL is 24 hours in cache, and expires_at is also set on the DB record

The returned billing response uses checkoutToUrl() so the caller gets /c/:checkout_id as payment_url.

Public Checkout Flow

Router + Middleware

server/src/internal/checkouts/checkoutRouter.ts exposes:

  • GET /:checkout_id
  • POST /:checkout_id/preview
  • POST /:checkout_id/confirm

checkoutMiddleware does the shared setup:

  • Rate limits by checkout ID
  • Loads checkout from cache first
  • Falls back to DB only to determine that the checkout exists but is unavailable
  • Rejects completed or expired checkouts
  • Marks expired DB records as expired
  • Rehydrates public request context with the checkout's org, env, and features

Key behavior: if cache is missing, the middleware does not rebuild the checkout from DB. It throws unavailable after checking DB for audit state.

GET /checkouts/:checkout_id

handleGetCheckout.ts:

  • Only supports CheckoutAction.Attach
  • Casts checkout.params back to AttachParamsV1
  • Calls billingActions.attach({ preview: true })
  • Recomputes the current billing plan from the stored params
  • Converts that plan into an attach preview response for the UI

The checkout page therefore renders current computed pricing, not a persisted snapshot from creation time.

POST /checkouts/:checkout_id/preview

handlePreviewCheckout.ts is the same idea as GET, but it merges updated feature_quantities into the stored params before re-running preview attach.

Use this when debugging quantity edits in checkout UI.

POST /checkouts/:checkout_id/confirm

handleConfirmCheckout.ts:

  1. Validates action === "attach"
  2. Validates status === "pending"
  3. Re-runs attach({ preview: false, skipAutumnCheckout: true })
  4. Executes the real billing plan
  5. Deletes the cache entry so the checkout is one-time-use
  6. Marks the DB row as completed
  7. Returns success metadata including invoice_id

Important error behavior:

  • Cache is deleted only after successful execution
  • On failure, the checkout stays pending and cached so the user can retry
  • Non-RecaseError failures are wrapped as internal checkout failures

Checkout Mode Decision Tree

The decision lives in server/src/internal/billing/v2/actions/attach/setup/setupAttachCheckoutMode.ts.

Possible outputs:

  • null
  • "stripe_checkout"
  • "autumn_checkout"

redirect_mode: "never"

Always returns null.

No checkout URL is returned, even if one would otherwise be required.

First Pass: Should Stripe Checkout Be Required?

Stripe checkout is chosen when Autumn cannot or should not bill directly:

  • Customer has no payment method and product is one-off
  • Customer has no payment method, product is paid recurring, and customer does not already have a Stripe subscription
  • Exception: if that first paid recurring product starts with a trial and cardRequired === false, it returns null instead of Stripe checkout

Two important suppressors:

  • If a payment method already exists, this pass returns null
  • If invoiceMode is enabled, this pass returns null

Second Pass: Forced Redirects (redirect_mode: "always")

If the first pass returned null and redirect_mode === "always", Autumn forces a redirect-style flow:

  • One-off product -> "stripe_checkout"
  • Paid recurring product with no existing Stripe subscription -> "stripe_checkout"
  • Everything else -> "autumn_checkout"

When Autumn Checkout Applies

Autumn checkout is the fallback for redirect_mode: "always" when Stripe checkout is not required.

In practice, that means cases like:

  • Customer already has a payment method, and you still want a confirmation page before applying attach
  • Customer is changing an existing recurring subscription and you want a redirect/confirmation UX
  • Customer is attaching something that is neither one-off nor the first paid recurring subscription, and Stripe checkout is unnecessary
  • Invoice mode is enabled, redirect_mode is "always", and you still want the user to land on an Autumn confirmation page
  • Free-product attaches with redirect_mode: "always" also land here

The important mental model:

  • stripe_checkout means Stripe still needs to collect payment details or own the checkout UX
  • autumn_checkout means Autumn already has enough context to bill, but the API caller requested a confirmation step

What Autumn Checkout Does Not Do

  • It does not support arbitrary billing actions today; handlers currently accept only CheckoutAction.Attach
  • It does not store a frozen billingPlan
  • It does not bypass normal attach validation
  • It does not delete the DB row on success; it marks it completed and removes the cache entry
  • It does not recover a missing cache entry by restoring from DB

Debugging Checklist

If a checkout link appears unexpectedly:

  • Check params.redirect_mode
  • Check whether setupAttachCheckoutMode() saw a payment method
  • Check whether the product is one-off, free, or paid recurring
  • Check whether the customer already has a Stripe subscription
  • Check whether invoice mode or a no-card-required trial suppressed Stripe checkout

If the checkout preview looks different from the original attach response:

  • Remember GET /checkouts/:id recomputes attach from stored params
  • Compare customer state between creation time and retrieval time
  • Check whether feature quantities were changed via preview

If confirmation creates a second checkout instead of charging:

  • Confirm the code path uses skipAutumnCheckout: true

If a valid-looking checkout URL says unavailable:

  • Check whether the cache entry expired or was deleted
  • Check DB status for completed or expired
  • Remember DB is audit/backup, not a recovery source for public use

Current Scope

The data model allows CheckoutAction.UpdateSubscription, but the public handlers currently only support attach.

If you extend Autumn checkout beyond attach, update:

  • checkout creation
  • public handlers
  • preview/response shaping
  • middleware assumptions
  • any skill docs that still describe attach-only behavior