Subscription lifecycle
How apps model recurring relationships, renewals, amount 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. Amount changes update the relationship and produce new payment rows only when money actually moves.
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. |
Amount changes
Use ATM-native subscription management so app state, processor state, and attested-network proof state stay aligned. The buyer should see a single subscription whose amount changed, not a cancel and recreate flow.
| Increase | Update the processor subscription and app-visible subscription amount; next payment row reflects the new charge when it settles. |
|---|---|
| Decrease | Apply app and processor policy for timing/proration, then emit subscription.updated with previousAmount. |
| Proof alignment | ATM may supersede recurring attestation state behind the scenes while keeping the user-facing subscription stable. |
| App UX | Show the new amount after confirmation and wait for events before changing benefits that depend on payment settlement. |
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; amount changes adjust the current relationship. |
|---|---|
| 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. |