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
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:
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-2612Permit 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:
- When a cycle is due, the subscriber appears in your collectable list.
- You send
USDC.permit(...)the first time, to put the buyer’s allowance on-chain, thenUSDC.transferFrom(owner, spender, amount)for the cycle. Your wallet pays the gas for both. - Xenarch verifies the USDC
Transferon Base and books the cycle once. Submitting the same cycle twice does not book it twice.
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 (statusfailed) 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. Setbilling_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:
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/subscriberslists the subscribers of your links. Filter bylink_id,statusormode.GET /v1/subscribers/export.csvexports them. - Buyers: a buyer who signs in to dash.xenarch.dev with the wallet they paid with sees their own subscriptions across all their linked wallets. The API endpoint is
GET /v1/me/subscriptions.
active, failed, exhausted, cancelled) send a subscription.status_changed webhook. See Webhooks.