Bag DocsSubscriptions
How Bag handles recurring billing, trials, dunning, and subscription lifecycle.
Subscriptions
Bag supports recurring billing as part of the Merchant of Record model. Subscriptions handle the full lifecycle — creation, billing, trials, failed payment recovery, and cancellation — with tax compliance built in.
Billing Cycles
| Cycle | Example |
|---|---|
| Daily | Short-term access, metered trials |
| Weekly | Weekly content, digests |
| Monthly | Standard SaaS plans |
| Yearly | Annual discounts |
| Custom | Any interval (e.g., every 2 weeks, quarterly) |
Trial Periods
Offer free trials before the first charge:
- Configurable duration — Days, weeks, or months per plan
- No payment during trial — Customer is not charged until the trial ends
- Auto-conversion — Billing starts automatically when the trial expires
- Cancel without charge — Customers can cancel during the trial at no cost
Payment Methods for Subscriptions
Stablecoin (USDC)
Customers approve a one-time transaction authorization using a smart contract (Permit2). When subscribing to a $10/month plan, the customer approves up to 6 months of payments ($60). Each billing cycle, the amount is auto-withdrawn. Re-approval is required after the approval period expires.
This reduces transaction friction and gas fees while keeping the customer in control of their wallet.
Card
Standard recurring card billing. Card networks handle the recurring authorization, and Bag manages retries on failure.
Failed Payments & Dunning
When a subscription payment fails, Bag automatically retries over a 21-day grace period:
| Retry | Day | Action |
|---|---|---|
| 1 | Day 1 | First retry + customer email notification |
| 2 | Day 4 | Second retry + reminder email |
| 3 | Day 10 | Third retry + warning email |
| 4 | Day 21 | Final retry + last-chance email |
During the grace period, the subscription status is past_due and the customer retains access.
After all retries fail, the subscription is either canceled or kept active with overdue status (configurable per plan).
Subscription Lifecycle
Statuses
| Status | Meaning |
|---|---|
active | Subscription is current, payments up to date |
past_due | Payment failed, in dunning grace period |
canceled | Subscription terminated |
paused | Billing suspended, may retain or revoke access |
Pause & Resume
Customers or merchants can pause a subscription. Billing stops during the pause. Whether the customer retains access during the pause is configurable.
Cancellation
Two modes:
- Immediate — Access ends right away
- End of period — Access continues until the current billing period ends
Plan Changes (Proration)
Upgrades and downgrades mid-cycle use proration:
Example: Customer on $10/month upgrades to $20/month on day 15:
- Credit for unused time: $5
- Charge for remaining time at new rate: $10
- Net charge: $5
Webhook Events
Subscription events are delivered to your registered webhook endpoint:
| Event | When it fires |
|---|---|
subscription.created | New subscription created |
subscription.updated | Plan or details changed |
subscription.renewed | Recurring payment succeeded |
subscription.renewal_due | Upcoming renewal requires action (stablecoin re-approval) |
subscription.past_due | Payment failed, grace period active |
subscription.canceled | Subscription permanently canceled |
Tax Handling
Bag calculates and remits tax on every subscription payment automatically. Tax is recalculated at each renewal based on the customer's current jurisdiction and applicable rates.
What's next
For a step-by-step integration guide with code examples, see the Subscriptions guide.