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

# Stablecoin Subscriptions

> Recurring stablecoin billing with initial wallet authorization and future automatic renewals.

Stablecoin Subscriptions is StablePay's product for recurring stablecoin billing. It helps merchants manage the full subscription lifecycle: creating subscriptions, completing initial wallet authorization, charging automatically by billing cycle, handling renewal failures and retries, canceling subscriptions, and synchronizing business state through webhooks.

The product is different from [Stablecoin Checkout](/en/product/Stablecoin-Checkout). Checkout is for one-time payments. Subscriptions are for repeat billing. The customer first completes an on-session wallet authorization in StablePay Hosted Checkout. StablePay then creates invoices for each billing cycle and attempts off-session renewal charges using the saved authorization.

## When to use it

Use Stablecoin Subscriptions when you have an ongoing commercial relationship with the customer.

Common fit examples include:

* Monthly or annual SaaS plans.
* Memberships, subscriptions, and paid communities.
* Premium access to software, content, games, or services.
* Retainers, recurring support plans, or account-managed service packages.
* Usage models where access should continue only while billing remains active.

## Try the demo

You can try a demo subscription storefront here:

<Card title="Subscription demo storefront" icon="repeat" href="https://mall.wenfu.shop/subscription">
  Open the demo storefront to see the initial StablePay Subscriptions Checkout authorization flow.
</Card>

For a single customer bill that is not part of a recurring plan, use [Invoicing](/en/product/Invoicing). For one-time checkout, use [Stablecoin Checkout](/en/product/Stablecoin-Checkout).

## Product model

The subscription model is built around initial authorization, billing-cycle invoices, automatic renewal, and webhook-driven entitlement.

| Stage                 | What StablePay handles                                                                | What the merchant should do                                            |
| :-------------------- | :------------------------------------------------------------------------------------ | :--------------------------------------------------------------------- |
| Create subscription   | Creates the subscription and returns a hosted checkout URL for initial authorization. | Store the `subscription_id` and redirect the customer to checkout.     |
| Initial authorization | Customer selects a wallet, authorizes on-chain, and may pay the first period.         | Wait for webhooks. Do not grant final paid access from creation alone. |
| Billing cycle         | Creates an invoice for each period and attempts payment when due.                     | Update local state from invoice and subscription webhooks.             |
| Renewal success       | Payment succeeds, invoice is paid, and subscription remains active.                   | Extend or confirm entitlement and optionally notify the customer.      |
| Renewal failure       | Subscription can enter past\_due and automatic retries begin.                         | Apply grace period, feature limits, or reminder policy.                |
| Cancellation          | Supports immediate cancellation or cancellation at period end.                        | Sync the cancellation state and end entitlement at the correct time.   |

## How it works

1. Your backend creates a subscription for a customer and plan, with amount, billing interval, start mode, and redirect context.
2. StablePay returns a hosted checkout URL for the first authorization or first payment.
3. The customer opens StablePay Hosted Checkout, chooses a wallet, confirms details, signs the authorization, and pays the first invoice if required.
4. StablePay saves the reusable authorization / payment method for future billing cycles.
5. When each billing cycle arrives, StablePay creates an invoice and attempts an off-session renewal charge.
6. StablePay sends webhooks for subscription, invoice, and payment outcomes.
7. Your system grants, extends, restricts, or ends customer access based on webhook events.

## Billing start modes

| Mode                             | Description                                                                                                      | Best for                                                  |
| :------------------------------- | :--------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------- |
| Start now and charge immediately | The first invoice is due during checkout. The subscription becomes active after successful payment.              | Standard paid subscriptions that start today.             |
| Start now and charge later       | The customer only authorizes during checkout, and the first invoice is charged on a future billing date.         | Flows where service starts before first billing.          |
| Trial                            | The customer only authorizes during checkout, and the first invoice is created and charged after the trial ends. | Free trials, delayed conversion, or try-before-pay flows. |

## Retry and dunning

Automatic recovery after a failed renewal is called dunning. Renewal payments can fail because of wallet balance, authorization, network, or compliance conditions. When the latest amount due cannot be charged, StablePay can move the subscription to `past_due`, send webhooks, and apply the default retry strategy.

Default retry timing:

| Retry | Timing                   |
| :---- | :----------------------- |
| 1     | 5 minutes after failure  |
| 2     | 30 minutes after failure |
| 3     | 2 hours after failure    |
| 4     | 20 hours after failure   |

If any retry succeeds, the invoice becomes paid, the subscription can return to `active`, and the next billing cycle continues. If all retries fail, the subscription automatically becomes `canceled` and no new billing cycles are generated.

Merchants should avoid notifying customers on every retry failure. A better pattern is to send one balance or wallet reminder after the first failure, then apply your product policy for grace periods, feature restrictions, or temporary continued access.

## Cancellation

StablePay supports two cancellation patterns:

| Cancellation type    | Behavior                                                                                          | What the merchant should do                                                                            |
| :------------------- | :------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------- |
| Cancel at period end | The current billing period remains valid. The subscription becomes canceled when the period ends. | Show that the subscription will end at period end, then remove entitlement after `current_period_end`. |
| Cancel now           | The subscription ends immediately.                                                                | End entitlement immediately or enter your refund / support workflow.                                   |

Cancel-at-period-end usually updates cancellation fields first, such as `cancel_at_period_end=true`. The subscription is not actually ended until `subscription.canceled` is received. Merchants should not treat `subscription.updated` as final cancellation.

## Webhook events

Webhooks are the source of truth for subscription integrations. Use `subscription.id` and `event_id` for idempotency, and apply the latest object from the webhook payload to avoid state rollback from out-of-order events.

### Subscription events

| Event                             | When it fires                                                                                    | What the merchant should do                                                                  |
| :-------------------------------- | :----------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------- |
| `subscription.created`            | A subscription object is created successfully.                                                   | Create a local pending record and store customer, plan, subscription\_id, and checkout\_url. |
| `subscription.trialing`           | The customer completes initial authorization and the subscription enters trial.                  | Grant trial access and show trial start/end timing plus future auto-charge context.          |
| `subscription.active`             | The subscription enters a renewable state, or recovers from past\_due after a successful retry.  | Grant or restore active entitlement. Use `invoice.paid` to confirm payment for the period.   |
| `subscription.past_due`           | The latest amount due failed to charge and the subscription is retrying.                         | Mark renewal failure, apply grace or restriction policy, and trigger one reminder.           |
| `subscription.updated`            | Mutable subscription fields change, such as cancel-at-period-end settings.                       | Sync cancellation state and show clear period-end cancellation messaging.                    |
| `subscription.canceled`           | The subscription is terminated and will not generate new cycles.                                 | End entitlement or mark access to expire, and stop renewal reminders.                        |
| `subscription.incomplete_expired` | The customer did not complete initial authorization within the valid window, such as 30 minutes. | Mark onboarding failed / expired and allow the customer to start a new subscription.         |

### Invoice and refund events

| Event                    | When it fires                                                  | What the merchant should do                                                            |
| :----------------------- | :------------------------------------------------------------- | :------------------------------------------------------------------------------------- |
| `invoice.created`        | A first-period or renewal invoice is created.                  | Store invoice\_id, amount, currency, and billing period.                               |
| `invoice.paid`           | The invoice is paid successfully.                              | Mark the invoice paid and extend or confirm entitlement.                               |
| `invoice.payment_failed` | First-period payment, renewal payment, or retry attempt fails. | Record failure and apply reminder or access policy based on subscription state.        |
| `refund.created`         | A refund request or refund record is created.                  | Create a local refund record and mark refund processing.                               |
| `refund.succeeded`       | The refund completes successfully.                             | Mark refund succeeded and update order or invoice refund display.                      |
| `refund.failed`          | Refund processing fails.                                       | Mark refund failed and route to support or retry handling based on the failure reason. |

## State model

Key subscription state transitions:

| Transition                                       | Meaning                                                          |
| :----------------------------------------------- | :--------------------------------------------------------------- |
| `incomplete` -> `incomplete_expired`             | Initial authorization was not completed within the valid window. |
| `active` -> `past_due`                           | Renewal charge failed.                                           |
| `past_due` -> `active`                           | Automatic retry succeeded.                                       |
| `past_due` -> `canceled`                         | Retries were exhausted and the system canceled the subscription. |
| `active` / `trialing` / `past_due` -> `canceled` | Customer or merchant canceled immediately or at period end.      |

Do not rely only on frontend redirect results to determine subscription state. Business state should be webhook-driven.

## Launch guidance

### New merchants launching subscriptions

Start with "start now and charge immediately" to validate conversion, customer support load, webhook processing, and reconciliation. Add trial after activation and renewal handling are stable. Add "start now and charge later" only when the business needs aligned billing dates or future first-charge behavior.

### Merchants adding stablecoin billing to existing card subscriptions

Offer StablePay as a parallel subscription payment option instead of replacing existing card subscriptions directly. When a customer chooses to switch, create a new StablePay subscription and set the original card subscription to cancel at period end to avoid charging twice for the same entitlement.

## Payment methods, currency, and networks

Stablecoin Subscriptions currently support creating subscriptions in USD, with stablecoin charging and settlement in USDT / USDC. Subscription flows can support wallets such as MetaMask, Binance Wallet, OKX Wallet, and WalletConnect, and networks such as Ethereum, BNB Smart Chain, and Solana.

StablePay Subscriptions Checkout does not support scan-to-address or copy-address transfer payment. Recurring billing requires the customer to authorize future charges through a supported connected-wallet flow.

Actual availability can vary by merchant configuration, environment, and compliance requirements. For complete coverage, see [Supported Wallets](/en/product/Supported-Wallets), [Supported Networks](/en/product/Supported-Networks), and [Currencies & Auto Currency Conversion](/en/product/Auto-Currency-Conversion).

## Important notes

* Initial wallet authorization is required before automatic renewal charges can occur.
* Subscriptions Checkout supports connected-wallet authorization only and does not support QR/address transfer payment.
* `subscription.created` does not mean the customer has authorized or paid. Grant final paid access from webhook outcomes.
* `subscription.active` means the subscription is in a renewable state, but `invoice.paid` is the more direct signal that money was received for a billing period.
* Refunds happen against payments, not directly against subscription objects.
* Webhooks should be treated as the source of truth for entitlement, service access, and internal billing state.

## Related pages

* [Stablecoin Checkout](/en/product/Stablecoin-Checkout)
* [Invoicing](/en/product/Invoicing)
* [Refunds](/en/product/Refunds)
* [Supported Wallets](/en/product/Supported-Wallets)
* [Supported Networks](/en/product/Supported-Networks)
* [Currencies & Auto Currency Conversion](/en/product/Auto-Currency-Conversion)