Concept
What a subscription does, in plain terms — recurring flat-fee access without invoices, cards, or chargebacks.
A subscription gates an endpoint on flat-fee access over time. The buyer agrees once to pay $X every Y days. After that, the endpoint serves them without asking for payment again until cancellation.
If you've subscribed to Netflix, Spotify, or any SaaS product, you already know the shape: one signup, recurring charges, cancel any time. The difference is what's underneath — instead of a card on file and a monthly invoice, the subscriber authorizes the recurring charge directly. No card networks, no payment processor, no monthly chargeback window.
Who's involved
Two parties, end-to-end:
- The subscriber — the person (or agent) buying access. They agree to the recurring charge once, at signup.
- The merchant — you, the API operator. You set the price and the period; you collect the charge each period.
No payment processor sits in the middle. No bank holds the funds for two weeks. The merchant collects the fee on a schedule they control, and the subscriber can stop it at any time.
How it differs from per-call payment
Per-call payment (metered pricing) asks the buyer to pay for every individual request. It's pay-as-you-go: cheap if you barely use the API, expensive if you hammer it.
A subscription flips that. The subscriber commits to a period of access up front. Inside that period, requests are free at the point of use. Outside that period, the endpoint stops serving them until they renew.
A rough analogy:
| Model | Buyer pays for... | Best when |
|---|---|---|
| Per call | Each individual request | Variable usage, agents that may use the API once |
| Subscription | A period of access | Predictable usage, products with a clear monthly value |
You can offer both pricing models on the same provider — a metered endpoint and a subscription endpoint can sit side by side. A single endpoint picks one or the other, never both.
Lifecycle
A subscription moves through three stages.
Sign up. The first time a subscriber hits a gated endpoint, they're prompted to subscribe. They agree once. From that moment, the endpoint serves them without further payment prompts.
Active. For the duration of the billing period, the merchant collects the fee on schedule and the subscriber sees only normal API responses. Renewals are automatic — the subscriber doesn't have to do anything.
Cancellation. The subscriber can cancel at any time. The period they already paid for is still honored — access continues until the end of that period. After it ends, the endpoint stops serving them.
If a renewal fails (e.g. the subscriber's account no longer has funds), the endpoint stops serving them on the next request and asks them to subscribe again.
What this model is not
The subscription model in pay.sh is intentionally narrow: one price, one period, one endpoint. It standardizes recurring access and nothing more. Things explicitly not modeled:
- Tiers and upgrades. A subscription is one price for one period length. Switching tiers means cancelling and starting a new one.
- Add-ons and overages. No "extra usage" line items mid-period.
- Free trials and prorations. The first period starts at signup, at full price.
- Calendar months. Periods are measured in fixed days or weeks. "Monthly" means 30 days, not "the calendar month from the 5th to the 5th."
If your product needs any of the above, build the billing logic in your own application — track tiers, plans, and upgrades in your database, and point each subscriber at whichever subscription endpoint matches their current plan.
Next
- YAML specification — declare a subscription endpoint in your provider spec.
- Protocol & internals — the on-chain accounts, the wire-level handshake, the activation transaction, and how renewal works under the hood.