> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xenarch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscriptions

> Recurring USDC payments on Base: reminder mode emails a fresh link each cycle, permit mode uses one EIP-2612 signature that you collect against.

A subscription is a pay link with `kind` set to `subscription`. Its `amount` is the price per cycle and its `type` is the cadence: `per_day`, `per_week`, `per_month` or `per_year`. Each buyer who signs up becomes a subscriber with their own `subscription_id`.

Every subscription renews in one of two modes, set with the `renewal` param.

| | Reminder mode | Permit mode |
| - | - | - |
| `renewal` | `reminder` (default for subscriptions) | `permit` |
| Buyer action per cycle | Pays a fresh link from an email | None after signup |
| Buyer action at signup | Pays the first cycle | Signs one EIP-2612 permit. No money moves at signup. |
| How each cycle is paid | The buyer pays at the hosted checkout | You pull it from the buyer's allowance with a transaction from your wallet |
| Daily cadence | Not available | Available |

## Reminder mode

Before each renewal Xenarch emails the buyer a signed renewal link. The buyer opens it and pays the next cycle on the hosted checkout, the same way as the first payment. The email goes out:

| Cadence | Email sent before renewal |
| - | - |
| `per_week` | 1 day |
| `per_month` | 3 days |
| `per_year` | 30 days |

The API rejects a reminder subscription with `type` set to `per_day`. Use permit mode for daily billing.

## Permit mode

At signup the buyer gives an email address and signs one EIP-2612 `Permit` for USDC on Base. The permit names the buyer as `owner`, your receiving wallet (the link's `to`) as `spender`, a cumulative cap as `value`, and a `deadline`. For a flat-price plan the cap is the cycle price times the number of cycles the buyer authorizes. The USDC contract enforces the cap: once the total drawn reaches it, further transfers revert. You can never pull more than the buyer signed for.

No money moves at signup. The first cycle is due at signup, or when the trial ends if the link has one, and you collect it like every later cycle.

Collection is your action, from your own wallet:

1. When a cycle is due, the subscriber appears in your collectable list.
2. You send `USDC.permit(...)` the first time, to put the buyer's allowance on-chain, then `USDC.transferFrom(owner, spender, amount)` for the cycle. Your wallet pays the gas for both.
3. Xenarch verifies the USDC `Transfer` on Base and books the cycle once. Submitting the same cycle twice does not book it twice.

You can collect from the dashboard (Subscribers, then Collect), from the CLI, or through the API:

```bash theme={null}
npx xenarch collect list            # permit and metered subscriptions due now
npx xenarch collect permit <subscription_id> --confirm
```

```bash theme={null}
# Due permit cycles for your links
curl https://api.xenarch.dev/v1/subscribers/permit/collectable \
  -H "Authorization: Bearer xm_live_..."

# Record a transferFrom you already sent
curl -X POST https://api.xenarch.dev/v1/subscribers/<subscription_id>/permit/collect \
  -H "Authorization: Bearer xm_live_..." \
  -H "Content-Type: application/json" \
  -d '{"tx_hash": "0x..."}'
```

Xenarch never sends these transactions. Its hourly permit sweep only sends email: a digest of collectable subscribers to you, and a notice to the buyer to renew the authorization when two cycles' worth of allowance remain.

### Failed collections

When a due buyer cannot be charged (balance too low or allowance revoked), Xenarch emails the buyer to top up, at most once every 3 days. After 5 such strikes the subscription is suspended (status `failed`) and you are notified. Suspension is a status in Xenarch. It does not touch the buyer's on-chain permit. You can also suspend and unsuspend a subscriber yourself with `POST /v1/subscribers/{subscription_id}/suspend` and `/unsuspend`.

## Metered billing

A subscription can bill per unit of usage instead of a flat amount per cycle. Set `billing_model` to `per_unit`, `per_unit_quantity_source` to `metered_usage`, a `per_unit_unit_price` and a `per_unit_billing_threshold`. Metered billing requires `renewal` set to `permit`, and a `per_unit_spending_cap` requires a `per_unit_cap_period`. See `GET /v1/links/schema` for every `per_unit_*` field.

Report usage as it happens. The endpoint authenticates with the link's `webhook_secret`, so a reporting service needs no session:

```bash theme={null}
curl -X POST https://api.xenarch.dev/v1/links/<link_id>/usage \
  -H "Authorization: Bearer whsec_..." \
  -H "Content-Type: application/json" \
  -d '{"subscription_id": "<subscription_id>", "units": "1", "idempotency_key": "call-8f2c"}'
```

```ts theme={null}
import { createXenarch } from "@xenarch/sdk";

const sdk = createXenarch();
await sdk.merchant.usage.report(
  linkId,
  { subscriptionId, units: 1, idempotencyKey: "call-8f2c" },
  { secret: webhookSecret },
);
```

`units` is a positive increment, not a running total. A report whose `idempotency_key` was already recorded for that subscription changes nothing and returns `"deduped": true`. Every 10 minutes Xenarch books a charge against the buyer's permit allowance for each subscriber whose accrued usage crossed the billing threshold, and sends a `charge.booked` webhook. You settle booked charges on-chain with `transferFrom` from your wallet (`xenarch collect metered <subscription_id>`), and Xenarch sends `charge.settled`.

## Subscriber views

* You: `GET /v1/subscribers` lists the subscribers of your links. Filter by `link_id`, `status` or `mode`. `GET /v1/subscribers/export.csv` exports them.
* Buyers: a buyer who signs in to [dash.xenarch.dev](https://dash.xenarch.dev/agent/subscriptions) with the wallet they paid with sees their own subscriptions across all their linked wallets. The API endpoint is `GET /v1/me/subscriptions`.

Subscription status changes (`active`, `failed`, `exhausted`, `cancelled`) send a `subscription.status_changed` webhook. See [Webhooks](https://docs.xenarch.com/payments/webhooks.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.