Subscriptions and plans

A plan is a price that repeats: weekly, monthly, yearly, or any cadence you choose. Your customer approves it once at checkout, and every renewal after that settles to your wallet automatically, with no card on file, bank mandate, or customer action on renewal day. This page covers creating plans, how the on-chain authorization protects both sides, and what happens when a renewal fails.

How do I create a plan?

Go to Dashboard → Plans → New plan and set:

• Name: the product your customer is buying ("Pro", "Coaching Monthly").
• Price: in USDC, minimum 1.00 USDC per period.
• Billing interval: weekly, bi-weekly, monthly, yearly, or custom: every N days, from 1 to 365.
• Description (optional): shown to the customer at checkout.

Publishing takes one confirmation. Gas is sponsored, so you never need SOL. The plan gets a hosted checkout link you can share anywhere; the Plans table shows each plan with its price, interval, status, and a Share link action. Developers can create the same plans via the API.

Fixed price or usage-based?

A plan can charge a fixed price every period (the default above), or it can be usage-based: instead of a flat amount, it bills the customer's metered usage each period. On the New plan form, choose Usage-based, pick a meter, set a price per unit, and set a per-period cap, the most that can ever be pulled in one period. The customer approves that cap once at checkout; from then on Soca prices their usage at the end of each period and pulls exactly that, never more than the cap, with no signature and no invoice. There is no charge at signup, and a period with no usage costs nothing.

This is the same subscription authorization described below, the cap simply becomes a ceiling the usage charge sits under rather than a fixed amount. See Usage-based billing for meters, pricing models, and the full picture.

How does the customer authorization work?

When a customer subscribes, they sign a single on-chain authorization, a capped allowance that lets the plan pull its renewal payments. The cap is exactly what makes it safe to approve:

• Capped at the plan price. The authorization can never pull more than the amount the customer saw at checkout. For a usage-based plan, that amount is the per-period cap, and the actual charge is the usage priced under it.
• One charge per billing period, maximum. A monthly plan can charge once a month. The chain itself enforces the cadence.
• Only to your wallet. The funds can move to the plan's settlement destination and nowhere else.
• Revocable at any time. The customer can cancel the authorization on-chain whenever they choose; you are notified and the subscription ends cleanly.

These are on-chain rules, not policies: neither Soca nor you can exceed them. A subscriber paying with their Soca account gets the 1% checkout discount on subscription payments, like any other Soca payment. You still receive the same net on every charge — Soca covers that discount out of its own fee, not yours.

What happens on renewal day?

Nothing, from your customer's point of view, and that is the feature. Renewals execute automatically under the standing authorization, with no signature, click, or reminder required from the customer. The charge settles to your wallet, appears in Payments, and the dashboard's upcoming-collections list shows what is due to renew and when.

What happens when a renewal payment fails?

Soca runs recovery for you. When a renewal fails, most often because the customer's balance is briefly low, the subscription enters dunning. An automatic retry ladder attempts the charge again at 24 hours, then 48 hours, then 48 hours more, for up to four attempts in total. Recoverable failures often self-heal the moment funds arrive in the customer's wallet.

• Access is maintained during grace. While retries are running, the customer keeps whatever the plan grants, including Discord and Telegram access, so a briefly-late payment never punishes a good customer.
• Dashboard → Recovery shows every failing renewal: the customer, the amount at risk, the failure reason, which retry attempt is next and when, plus your overall recovered vs lost rate.
• Some failures need the customer. If the authorization was revoked or needs renewal, retries cannot fix it; Recovery flags these as needing customer action so you can reach out.
• If all retries are exhausted, the subscription is marked lost, access is revoked, and (for developers) a subscription.dunning_exhausted webhook fires.

How do I see my subscribers and recurring revenue?

Each plan's detail page lists its members and their status; the Plans page totals your active plans and average price, and the dashboard home tracks recurring collections as they settle. Because every renewal is a real settled payment, your recurring revenue numbers are money that actually arrived, not bookings waiting on a payout.

Plans can settle to a specific named wallet via purpose routing. Tag a wallet "Subscriptions" and recurring revenue lands there, separated from the rest.