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
- support feed rows
- membership UI
First payment
- 1
App
Creates a subscription checkout envelope with app 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 support 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. Supper's reference model is simple support: one active support subscription per payer, recipient, and app.
| Simple support | One active subscription; amount changes adjust the current relationship. |
|---|---|
| Tiered membership | One active subscription per benefit tier or product policy, with app-owned benefit rules. |
| Multiple seats | A subscription can represent a quantity or seat count when the app config supports it. |
| Limited offers | Use app policy plus ATM catalog/discount refs; keep private eligibility and counters off protocol. |