# Subscriptions
Subscriptions let your server charge a recurring amount after the user approves the plan once. The first request returns an HTTP `402 Payment Required` challenge, and the Tempo Accounts SDK fulfills it from the connected account.
After activation, your server can serve requests during the current billing period without asking for another confirmation. When the next period is due, a worker, cron job, or request handler can collect the next payment.
## Demo
By the end of this guide you'll have a protected articles route, a recurring subscription approval, and a server-side collection path for the next billing period.
} className="flex flex-col gap-3">
Create an account, or use an existing one.
}
action={}
/>
The example uses a 10-second period for local testing. Production plans should use `day` or `week` periods.
## Walkthrough
::::steps
### Connect an Account
Follow the [Connect Accounts](/docs/guides/connect-accounts) guide to set up Wagmi and let the user sign in. Subscriptions activate from the connected account before your server collects future periods.
### Install the Server Dependencies
Install [`mppx`](https://github.com/wevm/mppx) for serving and verifying HTTP `402` payment challenges. This guide uses [Hono](https://hono.dev) on Cloudflare Workers, but the same shape works in other server runtimes.
:::code-group
```bash [npm]
npm i mppx hono
```
```bash [pnpm]
pnpm i mppx hono
```
```bash [bun]
bun i mppx hono
```
:::
### Set Up `mppx`
Configure `tempo.subscription` with the server account, billing currency, resolver, and store. The resolver returns the stable lookup key for the current subscriber.
```ts twoslash [worker/index.ts]
// @noErrors
import { Hono } from 'hono'
import { Store } from 'mppx'
import { Mppx, tempo } from 'mppx/hono'
import { privateKeyToAccount } from 'viem/accounts'
const app = new Hono()
const mppx = Mppx.create({
methods: [
tempo.subscription({
account: privateKeyToAccount(process.env.ACCOUNT_PRIVATE_KEY),
currency: '0x20c0000000000000000000000000000000000000',
feePayer: true,
resolve({ input }) {
const subscriber = input.headers.get('X-Subscriber')
if (!subscriber) return null
return { key: `articles:${subscriber.toLowerCase()}` }
},
store: Store.memory(),
testnet: true,
}),
],
})
```
:::warning\[Use a trusted lookup key]
`X-Subscriber` keeps the example small. In production, derive the lookup key from a server-trusted session, API key, or user record.
:::
:::warning\[Use a durable store]
`Store.memory()` keeps the guide runnable. In production, use a durable store so subscription records and access keys survive deploys, restarts, and worker evictions.
:::
### Gate the Paid Route
Wrap the route with `mppx.subscription`. If there is no active subscription, the middleware returns the payment challenge. After activation or renewal, the route handler runs and the response includes a `Payment-Receipt` header.
```ts twoslash [worker/index.ts]
// @noErrors
app.get(
'/api/articles',
mppx.subscription({
amount: '0.01',
periodCount: 1,
periodUnit: 'day',
subscriptionExpires: '2030-01-01T00:00:00.000Z',
}),
(c) =>
c.json({
articles: [
{ id: 1, title: 'Designing recurring payments' },
{ id: 2, title: 'Collecting subscriptions in workers' },
],
}),
)
```
For local testing, set `periodCount: 10` and `periodUnit: 'dev_second'`. Production plans should use `day` or `week` periods.
### Call the Route from the Client
Use `fetch` normally. The Tempo Accounts SDK handles the `402`, asks the user to approve the subscription, and retries the request with the signed credential.
```tsx twoslash [Articles.tsx]
// @noErrors
import { useMutation } from '@tanstack/react-query'
import { stringify } from 'viem'
export function Articles(props: { address: `0x${string}` }) {
const articles = useMutation({
mutationFn: async () => {
const res = await fetch('/api/articles', {
headers: { 'X-Subscriber': props.address },
})
const body = await res.json()
if (!res.ok) throw new Error(`${res.status}: ${stringify(body)}`)
return body
},
})
return (
)
}
```
### Index Active Subscriptions
A scheduled worker needs subscription IDs to collect. `mppx` renews a known subscription ID; your app database owns enumeration and due-time queries.
You can skip this step when you only collect on the request path. `mppx.subscription` can renew an overdue subscription before serving the protected route.
### Collect from a Schedule
Call `mppx.tempo.subscription.renew` from a cron worker. It returns a receipt when it collects the next period, or `null` when the subscription is already current, missing, inactive, or superseded.
```ts twoslash [worker/index.ts]
// @noErrors
async function collectDueSubscriptions() {
for (const subscriptionId of await database.subscriptions.listDueIds()) {
const result = await mppx.tempo.subscription.renew({ subscriptionId })
if (!result) continue
console.log('collected subscription', {
reference: result.receipt.reference,
subscriptionId,
})
}
}
export default {
fetch: app.fetch,
scheduled(_controller, _env, ctx) {
ctx.waitUntil(collectDueSubscriptions())
},
}
```
Configure the schedule in `wrangler.jsonc`. Choose an interval that is comfortably shorter than the billing period.
```jsonc [wrangler.jsonc]
{
"triggers": {
"crons": ["*/15 * * * *"]
}
}
```
::::
## Best Practices
### Persist Subscription State
Use a durable store for `tempo.subscription`. In-memory storage is only useful for local examples because subscription records and access keys disappear when the process restarts.
```ts twoslash [worker/index.ts]
// @noErrors
const store = createDurableSubscriptionStore(env)
const mppx = Mppx.create({
methods: [
tempo.subscription({
// ...
store,
}),
],
})
```
### Treat `renew` as Idempotent
It is safe for cron to call `renew` early or more than once. A `null` result means no payment was collected, so your scheduler can continue without treating it as an error.
```ts twoslash [worker/index.ts]
// @noErrors
const result = await mppx.tempo.subscription.renew({ subscriptionId })
if (!result) return
await database.subscriptionPayments.insert({
reference: result.receipt.reference,
subscriptionId,
})
```
### Use Server-Trusted Identity
Do not trust client-provided headers for production lookup keys. Resolve subscriptions from the authenticated session, API key, organization ID, or another server-side identity that the user cannot spoof.
```ts twoslash [worker/index.ts]
// @noErrors
tempo.subscription({
// ...
async resolve({ input }) {
const session = await requireSession(input)
return { key: `articles:${session.userId}` }
},
})
```
### Keep Periods Reviewable
Show the amount, currency, period, and expiry before the user approves. Use short periods only for development; production subscriptions should use stable billing periods that match the product terms.
```ts twoslash [worker/index.ts]
// @noErrors
app.get(
'/api/articles',
mppx.subscription({
amount: '10',
periodCount: 1,
periodUnit: 'week',
subscriptionExpires: '2030-01-01T00:00:00.000Z',
}),
handler,
)
```
### Monitor Collection Failures
Record renewal attempts, receipts, and errors. Alert on repeated failures, expired subscriptions, unfunded accounts, and fee payer issues.
```ts twoslash [worker/index.ts]
// @noErrors
try {
await mppx.tempo.subscription.renew({ subscriptionId })
} catch (error) {
await logger.error('subscription renewal failed', {
error,
subscriptionId,
})
throw error
}
```
## Production Checklist
A durable `store` backs `mppx` subscription records.
Your app database stores `subscriptionId`, lookup key, plan, next due time, and status.
Collection runs from cron, a queue, or a worker scheduler.
`renew` returning `null` is handled as nothing due.
The fee payer is configured and its balance is monitored.
Cancellation, expiry, and customer notification flows are in place.
Local-only periods such as `dev_second` stay out of production.
## Next Steps