Autumn Integrate

Integrate

Before using this skill, first load the autumn-concepts skill — it defines the objects these calls operate on — customers, plans, balances, entities.

STRICT RULES

1. Everything is backend. All Autumn calls run in the app's server code with AUTUMN_SECRET_KEY — never in the browser. The frontend gets billing data only through the app's own endpoints.
2. The old frontend layer is deprecated — never use or suggest it: autumnHandler mounts, React hooks (useCustomer, useEntity, AutumnProvider), shadcn components. If an app already uses them, don't rip them out unasked — but build new work backend-only.
3. Resolve the customer before anything else. Every handler that checks, tracks, or attaches must serve a brand-new user: customers.getOrCreate with the app's own stable id (user or org id from auth — whoever pays — never an email). Never assume the customer exists.
4. An error response is a failure. A 4xx/5xx from any Autumn call is never "working" — read the error, fix the call.

Order of operations

Work these in order; each step names what to settle and where the details live. Read the referenced doc before implementing the step — the snippets and parameters are there, not here.

1 — Discover the app. Framework, server entry points, where auth lives, which existing routes handle the actions being billed. Settle the customer id: the app's stable user or org id — whoever pays. If the product bills per workspace/project/seat, those are entities under one customer, not separate customers.

2 — Settle the level. Before writing any flow, ask the user how their plans and features actually work: what does a plan get bought for — the whole account, or each workspace/deployment/seat under it? And where does each feature's balance live — shared across the account, or per unit? The catalog hints (entity-scoped items, license plans) but doesn't decide — a plan can attach per deployment while credit packs stay account-wide. The answers flow through everything: billing.attach takes entityId for entity-level plans, check/track take entityId for entity-scoped balances, billing controls set at the matching level. Mixing levels silently misbills — an account-wide check against a per-seat balance always passes. For entities, entity-scoped balances, when to use which level, read references/feature-entities.md. For plans that attach per entity, read references/entity-plans.md.

3 — Install and connect. autumn-js (or the platform's SDK) + AUTUMN_SECRET_KEY in server env. One shared client in server code. For install, client setup, the end-to-end happy path, read references/setup.md.

4 — Customer creation. customers.getOrCreate where the app knows who the user is — signup/login hook, or lazily in billing handlers. Pass name/email when available. A default (auto-enable) plan attaches on creation — no attach call for the free tier. If step 2 settled anything at entity level, mirror this for entities: when the app creates its unit (a workspace, a deployment, a seat), create the entity then — usually in the same handler, right before the entity-level attach or check that needs it. For getOrCreate parameters, Stripe linking, pre-creating, read references/creating-customers.md. For creating entities, entity parameters, read references/feature-entities.md.

5 — Purchase and plan changes. All through two calls, split by intent (pass entityId when the plan attaches at entity level — step 2):

• billing.attach — getting on a plan, AND upgrades/downgrades within a plan group: attach the new plan; a higher (monthly-normalized) price applies immediately with proration, a lower one schedules for period end. planSchedule overrides. Default attach charges a saved card in place and returns checkout_url only when payment is actually needed — handle both outcomes. Force redirectMode: "always" only when the product wants hosted checkout unconditionally; custom flows preview first. For hosted vs custom checkout, redirectMode, previewAttach, read references/payment-flow.md. For upgrade/downgrade behavior, scheduled downgrades, carry-over on upgrade, read references/subscription-lifecycle.md.
• billing.update — changing the subscription you're on: prepaid quantities (seats), cancelAction (cancel_end_of_cycle / cancel_immediately / uncancel), customization. It never switches plans — that's attach's job. Preview twins exist for both calls — use them wherever the app shows a confirmation screen. For quantities, cancelAction, previewUpdate, prorationBehavior, read references/updating-subscriptions.md.
• When several plans move together — a plan plus its add-on in one purchase, or tied cancellation — use the multi twins: billing.multiAttach (one checkout / one payment covering every plan) and billing.multiUpdate (one atomic call applying a cancelAction per plan). Two sequential attach/update calls mean two checkouts or a half-canceled customer, and concurrent ones trip the per-customer lock.
• Payment snags are response state, not exceptions: required_action (3DS, payment method, failure) plus payment_url — handle the states, surface the URL. For 3DS, payment failures, required_action codes, read references/edge-cases.md.
• For deep parameter detail on attach, update, and the other billing actions (createSchedule, discounts, custom terms), the autumn-billing skill is the reference — it's written for operating billing directly, but its parameter and edge-case knowledge applies when implementing these calls in code.

6 — Check and track. In the billed action's own handler: check before the work, track after it succeeds. Gate on allowed — don't re-derive access from balances. Pass requiredBalance when an action costs more than 1, and entityId when the balance lives on an entity (step 2) — check and track must agree on the level. For the check → act → track pattern, read references/gating.md. For check parameters, allowed semantics, credit systems, entity checks, read references/check.md. For track and setUsage, read references/tracking-usage.md.