# Tempo subscription \[Recurring billing]
The `subscription` intent enables recurring stablecoin payments on Tempo with reusable access authorization.
Use subscriptions when access has a fixed price per billing period: paid plans, premium API tiers, recurring MCP tool access, and usage bundles that renew on a schedule.
## Why subscriptions matter
Charges work well for one-time purchases. Sessions work well when usage changes inside a request. Subscriptions cover the third common pattern: the client authorizes recurring access once, and the server bills each period without asking the client to sign every request.
A Tempo subscription uses a key authorization. The client authorizes a scoped access key to transfer a fixed amount of a specific TIP-20 token to a specific recipient once per period until `subscriptionExpires`. The server stores the active subscription record and returns Receipts on later requests without another Credential while the current period is paid.
## Choosing a payment method
| | **Charge** | **Session** | **Subscription** New |
|---|---|---|---|
| **Pattern** | One-time payment | Pay-as-you-go usage | Recurring access |
| **Client action** | Sign each paid transfer | Open channel and sign vouchers | Authorize an access key once |
| **Server hot path** | Verify and broadcast transfer | Verify voucher signatures | Resolve active subscription |
| **Best for** | Single API calls and purchases | LLM tokens, bytes, streamed usage | Plans, recurring API access, memberships |
| **Renewal** | None | Top up channel as needed | Bill each day or week |
## Flow
>Server: Protected request
Server-->>Client: 402 subscription Challenge
Note over Client: Authorize access key
Client->>Server: Retry with Credential
Server->>Tempo: Transfer first period
Tempo-->>Server: Transaction hash
Server-->>Client: 200 OK + Receipt
Client->>Server: Later request
Server-->>Client: 200 OK + Receipt
`}
/>
## Activation
The first request activates the subscription. The server resolves the request to a stable lookup key, such as `user:123:plan:pro`, and includes an access key in the Challenge. The client signs a `keyAuthorization` Credential that binds:
* `amount`
* `currency`
* `periodCount`
* `periodUnit`
* `recipient`
* `subscriptionExpires`
* `accessKey`
The server verifies the Credential, charges the first period, stores a `SubscriptionRecord`, and returns a Receipt with a `subscriptionId`.
## Access reuse
After activation, future requests do not need another Credential while the subscription is active and current. The server calls `resolve`, finds the subscription record for the route or user, validates that it still matches the request terms, and returns a Receipt.
>Server: Request protected resource
Server->>Store: Lookup active subscription by resolved key
Store-->>Server: SubscriptionRecord
Server->>Server: Check expiry, request binding, paid period
Server-->>Client: 200 OK + Receipt
`}
/>
## Renewals
When the next billing period starts, the server renews the subscription before granting access. The SDK uses an atomic store lock so concurrent requests do not charge the same period twice. If one request is already renewing, another request receives `409` with `Retry-After: 1`.
>Store: Lock renewal period
RequestB->>Store: Try same renewal
Store-->>RequestB: In flight
RequestA->>Tempo: Transfer period payment
Tempo-->>RequestA: Transaction hash
RequestA->>Store: Commit renewed record
RequestA-->>RequestA: 200 OK + Receipt
RequestB-->>RequestB: 409 Retry-After
`}
/>
You can renew in the request path with `renew`, or run renewals from a background worker with [`tempo.renewSubscription`](/sdk/typescript/server/Method.tempo.renewSubscription).
## Receipts
Subscription Receipts confirm activation or renewal. The `reference` field is the Tempo transaction hash for the period payment.
| Field | Description |
|---|---|
| `externalId` | Optional app-defined reference |
| `method` | Always `"tempo"` |
| `reference` | Tempo transaction hash |
| `status` | Always `"success"` |
| `subscriptionId` | Server-issued subscription identifier |
| `timestamp` | Receipt timestamp |
## Integration
### Server
Register `tempo.subscription()` explicitly. The `tempo()` convenience helper registers charge and session intents, but it doesn't register subscriptions.
```ts twoslash
import { Mppx, Store, tempo } from 'mppx/server'
const store = Store.memory()
const mppx = Mppx.create({
methods: [
tempo.subscription({
amount: '1.00',
currency: '0x20c0000000000000000000000000000000000000',
periodCount: '1',
periodUnit: 'week',
recipient: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
resolve: async ({ input }) => {
const userId = input.headers.get('X-User-Id')
return userId ? { key: `user:${userId}:plan:pro` } : null
},
store,
subscriptionExpires: '2027-01-01T00:00:00.000Z',
}),
],
})
export async function handler(request: Request) {
const result = await mppx.tempo.subscription({})(request)
if (result.status === 402) return result.challenge
const response = result.withReceipt(Response.json({ plan: 'pro' }))
console.log(response.status)
// @log: 200
return response
}
```
:::warning
Use a durable atomic store such as Redis, Upstash, or Cloudflare KV for production. `Store.memory()` is for local development.
:::
### Client
Register `tempo.subscription()` on the client. The SDK signs the access-key authorization and retries the request after the server returns a subscription Challenge.
```ts twoslash
import { Mppx, tempo } from 'mppx/client'
import { privateKeyToAccount } from 'viem/accounts'
const account = privateKeyToAccount('0xabc…123')
Mppx.create({
methods: [tempo.subscription({ account })],
})
const response = await fetch('https://api.example.com/pro')
console.log(response.status)
// @log: 200
```
## Advanced options
### Custom activation
Pass `activate` when your application owns settlement and record creation. The SDK still verifies the `keyAuthorization` Credential and validates the returned Receipt and subscription record.
### Custom access keys
Pass `accessKey` or return `accessKey` from `resolve` when you want to use an existing access key. Omit it for the recommended path: the server generates and stores one access key per resolved subscription key.
### Background renewal
Use [`tempo.renewSubscription`](/sdk/typescript/server/Method.tempo.renewSubscription) from a cron job when you want billing to happen before the next user request.
## Related