Docs

Subscription lifecycle

How apps model recurring relationships, renewals, portable membership tier changes, cancellation, and app-specific subscription policy.

Compatible with the closed-beta ATM app APIs and versioned ATM event headers. Check atm-api-version on every webhook or XRPC receiver event.

Relationship model

A subscription is the durable relationship between payer, recipient, and app. Renewal invoices are payment rows. ATM never changes the paid relationship, proof, or entitlements merely because a tier change was requested. The exact paid upgrade invoice or paid target renewal is what authorizes the new tier.

subscriptions

payerDid or guest email scope
recipientDid
appDid
current amount
status

payments

first invoice
renewal invoice
refund row state
subscription change records

app state

benefits
tiers
entitlement rows
membership or SaaS UI

First payment

1
App
Creates a subscription checkout envelope with default or per-checkout policy metadata.
2
ATM
Creates the recurring billing session and visible subscription relationship.
3
Buyer
Completes the first payment on hosted checkout.
4
ATM
Emits payment.completed and subscription.updated.
5
App
Enables the subscription benefit or entitlement state idempotently.

Renewals

Renewals should show up as payments because money moved. The subscription card should continue to represent one relationship, not a new subscription for every invoice.

Renewal succeeds	Emit payment.completed for the invoice and keep subscription status active.
Payment fails	Emit subscription.updated with the mapped status and let the app decide whether benefits enter a grace period.
Dashboard display	Show the current monthly amount on the subscription and each settled invoice in payments.

Tier and amount changes

Membership apps can preview an exact portable tier change, send the supporter to ATM for confirmation, and reconcile the durable change by opaque id. Upgrades charge the full target tier without credit and apply only after that invoice is paid. Downgrades and lateral moves are scheduled for the current paid-period boundary and apply only after the target renewal invoice is paid.

Preview	Call previewSubscriptionChange with fresh payer proof, expected revision, and exact target program, tier, and price refs.
Confirm	Create a short-lived hosted ATM session. Only the matching payer can confirm; apps cannot confirm on a supporter's behalf.
Reconcile	Consume subscription.change-updated or call getSubscriptionChange, fencing stale revisions and granting benefits only at applied.
Still unavailable	Same-tier pledge changes, pay-what-you-want targets, cadence or currency changes, and creator bulk repricing remain disabled.

Cancellation

Cancel through ATM-native subscription management when possible.
Emit subscription.canceled to the originating app.
Keep historical payment rows, receipts, proof state, and app order history resolvable.
Stop future renewals and remove or downgrade benefits according to app policy.
Do not delete the subscription relationship solely to hide it from the current list.

App policies

Apps can choose the subscription model that fits what they sell. The ATM setting is the environment default guardrail; checkout envelopes can override it when a particular creator membership, recurring product, add-on, or app-owned plan needs different duplicate-subscription behavior.

Single relationship	One active subscription per payer, seller, app, and environment; a tier change versions that relationship without creating a second checkout subscription.
Independent recurring products	Allow multiple active subscriptions when each product or add-on should stand alone.
Tiered membership	Use the single-relationship rule for tiers that should upgrade/downgrade, or override specific products when they are independent.
Multiple seats	A subscription can represent quantity or seat count when the app models seats in its own product state.
Limited offers	Use app policy plus ATM catalog/discount refs; keep private eligibility and counters off protocol.