About Subscriptions
Learn about Stash Subscriptions - a recurring billing system for games that enables battle passes, VIP memberships, and premium tiers with automatic renewals and flexible billing periods.
Stash Subscriptions is a recurring billing system for games that handles automatic renewals, grace periods, and subscription lifecycle management. Players subscribe to plans and get continuous access to premium content until they cancel or their subscription expires.
Integration requirement: Your app or game must provide in-app subscription management. Users need to be able to:
- View their active subscription and next billing date
- Cancel their subscription
- Reactivate a canceled subscription before it expires
This is required to maintain compliance. See the Integration guide for implementation details.
Use cases
Battle passes
Recurring offers that automatically renew each season. Players subscribe once and get continuous access to premium rewards, challenges, and exclusive content without needing to repurchase each period.
VIP memberships
Create tiered VIP memberships with monthly or annual billing. Members get ongoing benefits like bonus currency, exclusive items, priority queue access, or ad-free experiences.
Premium subscriptions
Sell premium game access or content subscriptions. Players pay a recurring fee for access to premium servers, extended content, or enhanced gameplay features.
Key concepts
Plans
A Plan defines what players subscribe to. Each plan has:
- A unique identifier (e.g.,
monthly_premium,annual_vip) - A billing period (e.g., 1 month, 1 year)
- Pricing in multiple currencies
- Optional trial period
Plans are configured in Stash Studio and retrieved via the Plans API.
Subscriptions
A Subscription is an instance of a player subscribing to a plan. It tracks:
- Current status (
trialing,active,past_due,canceled,expired) - Billing dates and next renewal
- Whether cancellation is scheduled
Price locking
When a player subscribes, their price is locked. If you later change the plan's price, existing subscribers continue paying their original rate until they cancel and resubscribe, however you can indicate if you don't want to honor grandfathered prices.
Grace periods
If a renewal payment fails, the subscription enters past_due status. During the grace period, the player retains access while Stash retries the payment. If all retries fail, the subscription expires.
The default grace period is 48 hours with payment retries at 24h and 48h. Grace period duration and retry schedule can be configured based on your needs.
Subscription lifecycle
Subscriptions move through these statuses:
| Status | Description |
|---|---|
trialing | Subscription is in free trial period |
active | Subscription is active and user has access |
past_due | Payment failed, retrying during grace period |
canceled | User canceled, access continues until period end |
expired | Subscription ended, no more access |
See the Subscription Flow guide for details on state transitions and lifecycle events.
How is this guide?