Subscriptions

Recurring billing (daily, weekly, monthly, or any custom interval), all settled on-chain in sBTC or STX.

A subscription is an agreement between a recipient and a subscriber: a fixed amount paid on a fixed cadence. The contract tracks when the next payment is due, and either the subscriber or any automation you run can trigger the payment once the interval has passed.

Key differences from a credit-card subscription

Pull vs. push

Traditional subscriptions are pull-based — the merchant charges the customer's saved card. On-chain subscriptions are push-based — each payment requires the subscriber (or a bot acting for them) to broadcast a transaction. This is a deliberate property of non-custodial rails: the merchant can never silently drain a subscriber's wallet.

Subscriber retains full custody. Payments happen when they (or their agent) sign a TX.
Missed payments are possible. Subscriber sees the next due date and is responsible for paying on time.
Cancellation is instant and requires no merchant permission.

Creating a subscription plan

As a merchant, you don't create subscriptions directly — you create a subscription widget that your subscribers can use to opt in.

From the dashboard, go to Widget Generator → Subscribe. Fill in:

Parameter	Type	Description
`Plan name`required	`string`	What the subscriber sees. E.g., "Pro Plan" or "Monthly Sponsor".
`Amount`required	`sats / micro-STX`	Amount charged each interval.
`Interval`required	`daily \| weekly \| biweekly \| monthly \| quarterly \| yearly`	How often the subscription bills.
`Token`required	`sBTC \| STX`	Which token the subscriber pays in.

Copy the generated embed code (or URL) and put it on your pricing page. When a subscriber opens the widget, clicks Subscribe Now, and confirms the transaction, a subscription is created and registered on-chain.

Subscriber experience

After creating the subscription, subscribers use the Customer Portal:

https://sbtc-pay.com/customer/subscriptions

From the portal, a subscriber can:

See all active subscriptions, with next-payment date and amount
Make the next payment when it's due
Pause a subscription (stops the billing clock)
Resume a paused subscription
Cancel a subscription (terminal)

Subscription lifecycle

Status	Type	Description
`Active`	`0`	Currently billing. The contract tracks next-payment-at.
`Paused`	`1`	Temporarily stopped. Resume restarts from where it left off.
`Cancelled`	`2`	Terminal. Cannot be reactivated — subscriber must create a new one.

How payment timing works

The contract counts time in Bitcoin burn blocks (about 10 minutes each on mainnet, 5 minutes on testnet). When a subscription is created:

created-at = current burn block
next-payment-at = current burn block (first payment is due immediately)

Each time a payment goes through:

last-payment-at = the burn block when payment confirmed
next-payment-at = last-payment-at + interval

The contract blocks premature payments — if the subscriber tries to pay before next-payment-at, the transaction reverts with ERR_NOT_DUE_YET.

Why burn blocks, not Stacks blocks?

After the Stacks Nakamoto upgrade, Stacks blocks are fast (~5 seconds). Using them for billing intervals would mean "monthly" actually hits every ~7 hours. Burn blocks match Bitcoin's steady ~10-minute cadence, which gives predictable calendar-time intervals. See Burn-Block Timing for the full explanation.

Pause and resume

A subscriber can pause a subscription at any time. While paused, no payments can be made and the clock doesn't advance. When the subscription is resumed, the contract recalculates the next payment date:

pseudocode

proper-next = last-payment-at + interval-blocks
next-at     = max(current-burn-block, proper-next)

In plain English: "catch up if you're behind, otherwise keep the original schedule." This means a subscriber who pauses mid-period doesn't lose their remaining time.

Cancellation

Cancellation is terminal and requires no merchant approval. Once cancelled, the subscription cannot be reactivated — the subscriber must create a new one if they want to resubscribe. Cancelled subscriptions remain in the dashboard for historical reference.

Dashboard view

As a merchant, go to Subscriptions in the dashboard to see:

Active subscriber count
Monthly recurring revenue (MRR) in sBTC and STX
Per-subscription history: payments made, last payment date, status

Refunding a subscription payment

Individual subscription payments can be refunded like any other payment. See Processing Refunds.