Subscriptions

Beta

Subscriptions are in beta. The API, payload shapes, and Developer Console UI may change without notice. Contact the Jest team before shipping a subscription to production, and keep an eye on What's new for breaking changes.

The Jest platform allows developers to sell recurring subscriptions to their games using the payment SDK methods. Subscriptions complement one-off product purchases and are a good fit for things like ad removal, premium tiers, or access to additional content.

As with one-off purchases, Jest handles the entire checkout and recurring billing with the player via popular digital wallets (Apple Pay, Google Wallet, card on file). Your game is responsible for reading the player's current entitlement and unlocking the relevant features.

Subscriptions on Jest via digital wallets

How subscriptions differ from products

Unlike one-off product purchases, subscriptions:

• Are tied to the player's wallet, not a single transaction. The wallet is what's billed on the recurring schedule.
• Don't require a complete step. The platform manages the billing lifecycle; your game only needs to read the wallet's current entitlement on startup (and after begin_subscription succeeds) and unlock features accordingly.
• Are only available to registered users. Guests must register before they can subscribe.
• Are returned alongside their current status (active or inactive), so the same response tells your game both what's on offer and what the player already has.

Subscription lifecycle

A subscription represents an ongoing entitlement granted to a wallet for as long as billing succeeds.

1. On startup, call get_subscriptions() to read the catalog and the wallet's current entitlement.
2. Unlock subscription-gated features based on each subscription's status.
3. If the player chooses to subscribe to an inactive offering, call begin_subscription(sku).
4. If checkout succeeds, the SDK returns the now-active subscription. Apply the entitlement in your game.
5. Cancellations, expirations, and renewals are handled by the platform; the next call to get_subscriptions() will reflect the updated status.

warning

Every subscription SKU is an independent product — the platform does not relate SKUs that unlock the same thing (e.g. a monthly and a yearly cadence of one tier). Once a player has an active subscription, your game must not offer other subscriptions that grant the same entitlements: hide or disable those offers, or the player could end up paying for both.

Happy path (new subscriber)

Returning subscriber (startup reconciliation)

On every startup, your game should re-read get_subscriptions() and apply the resulting entitlements. This is how you reflect cancellations, expiries, and renewals that happened while the player was away.

Free trials

A subscription can offer a free trial, configured per-product in the Developer Console (see Manage subscriptions). Trials are handled entirely by the platform — you don't run the trial yourself.

What this means for your game:

• During the trial the subscription's status is "active", exactly like a paid subscription. Read status and unlock features as usual; don't special-case trials.
• A trial is granted only to wallets that have never subscribed to that product before. Returning subscribers are billed immediately. begin_subscription applies the trial automatically when the player is eligible.
• At the end of the trial the platform charges the player and recurring billing continues. If the player cancels during the trial, the entitlement stays "active" until the trial ends, after which the next get_subscriptions() reflects "inactive".

trial_eligible — showing the right call to action

JestSubscription includes a trial_eligible flag so your subscribe CTA can promise a trial only when the player will actually get one. It is true when the product has a trial configured and the wallet has never subscribed to it before; otherwise it is false (no trial configured, the player already used it, or they are currently entitled).

Use it to pick the copy on an "inactive" offer — for example "Start free trial" when trial_eligible is true, versus "Reactivate" or "Subscribe for $9.99/mo" when it is false. It does not change what begin_subscription does; the platform still applies the trial only to eligible wallets. Treat trial_eligible as display-only and don't gate entitlement on it.

Introductory offers

A subscription can offer an introductory price — a discounted price for the first N months, configured per-product in the Developer Console (see Manage subscriptions). Like trials, intro offers are handled entirely by the platform: eligible players pay the discounted price for the configured months and then transition to the standard price automatically.

What this means for your game:

• JestSubscription carries the offer as a nullable intro_offer field (JestSubscriptionIntroOffer): the discounted price and the duration_periods (billing periods) it applies for.
• intro_offer is non-null only when an intro offer is configured and the wallet has never subscribed to that product before — the same rule as trial_eligible. If it's there, the player will get it; use it to advertise the offer ("$4.99/mo for the first 3 months, then $9.99/mo") and treat it as display-only.
• It is also always null for sandbox users, so intro offers never show up while you test with a sandbox account.
• A subscription can have both a free trial and an intro offer. The discount window is measured from signup, trial included, but trials are capped at 14 days, so the subscriber still receives every configured discounted month after the trial ends.

Intro offers apply only to a wallet's first subscription to a product, so they can't be used to win back a cancelling subscriber. Subscribing that player to a second SKU leaves the original subscription running and bills them for both — begin_subscription only rejects checkout for a SKU the player is already entitled to. For cancel flows, use a retention discount (see Retention discounts), which applies to the subscription the player already has.

Retention discounts

A subscription can also configure a retention discount — a discounted price a current subscriber can claim once, configured per-product in the Developer Console next to the intro offer. It exists so your game can run its own retention flow when a player asks to cancel: instead of losing the subscriber, offer them the discount.

How it works:

• While a player is entitled and still eligible, JestSubscription carries the offer as retention_offer, a Dictionary with price and durationPeriods keys (empty when none available). Use it to phrase your pitch ("stay for $4.99/mo for the next 3 months?") and to decide whether a pitch is possible at all.
• If the player accepts, call claim_retention_offer(sku). The discount is applied to their existing subscription instantly — no checkout, no new product. Their next durationPeriods renewals bill at the discounted price, then the standard price returns automatically.
• Each player can claim a subscription's retention discount once, and not during a free trial or while an introductory offer window is still running. When ineligible retention_offer is empty and the call returns error not_eligible. Repeating the call for a subscription the player already claimed re-confirms the same discount and returns success — safe to retry after an error.
• Sandbox users never receive one: retention_offer stays empty however they subscribed, and claim_retention_offer returns not_eligible. Test the flow in mock mode instead.
• If the player declines, fall through to cancel_subscription as usual.

var payment = JestSDK.payment
var list_result = await payment.get_subscriptions()

var sub: JestSubscription = null
for s in list_result.subscriptions:
    if s.sku == "premium":
        sub = s
        break

# Player tapped "cancel" in your UI:
if sub != null and not sub.retention_offer.is_empty():
    # Show your pitch:
    if await player_accepts_retention_offer(sub.retention_offer):
        var result = await payment.claim_retention_offer("premium")
        if result.status == JestSubscriptionResult.Status.ERROR:
            # Claiming again is safe, so offer a retry instead of cancelling a player who chose to stay.
            show_retention_claim_error(result.error)

        # On success, result.subscription reflects the post-claim state.
        return

await payment.cancel_subscription("premium")

How to use the SDK

Payload shapes

Where the SDK references JestSubscription, it contains:

Property	Type	Description
sku	String	The subscription's SKU, configured in the Developer Console.
display_name	String	Suitable for display in your game's UI.
display_description	String	Optional short description. Empty string when not set.
price	float	The subscription price in the currency specified in currency.
currency	String	The currency (ISO 4217 code) the price is in.
billing_period	String	"weekly", "monthly", or "yearly".
status	String	"active" or "inactive".
trial_eligible	bool	Whether the wallet can still start this subscription's free trial.
intro_offer	JestSubscriptionIntroOffer	Discounted price for the first billing periods, or null if none is configured or the wallet has already subscribed to this product before.
retention_offer	Dictionary	Retention discount claimable once via claim_retention_offer. Empty when none available. Keys: price (float), durationPeriods (int).
sandbox	bool	true only for sandbox users and in the simulator; false otherwise.

Where the SDK references JestSubscriptionIntroOffer, it contains:

Property	Type	Description
price	float	The discounted price, in the currency specified in the subscription's currency.
duration_periods	int	Number of billing periods the discounted price applies, measured from signup.

A status of "active" means the player's wallet currently has the entitlement and should have access to whatever the subscription unlocks. "inactive" means they don't have it (either never subscribed, or it has expired/been cancelled).

Set up subscriptions

Set up and price subscriptions using the Jest Developer Console.

For more information, see Manage subscriptions.

List subscriptions (get_subscriptions)

To retrieve the subscriptions available to the player along with their current entitlement, call get_subscriptions.

var payment = JestSDK.payment
var result = await payment.get_subscriptions()

if not result.ok:
    print("Failed to load subscriptions: %s" % result.error)
    return

for subscription in result.subscriptions:
    if subscription.status == "active":
        unlock_features_for(subscription.sku)

The result is a JestSubscriptionsResult with:

Property	Note
ok	true on success. On failure, error is populated and the lists are empty.
subscriptions	The array of JestSubscription objects (see Payload shapes).
signed	A signed JWT carrying the same subscriptions array. See below.

note

For guest players, get_subscriptions returns an empty subscriptions array and an empty signed string. Subscriptions are only available to registered users.

Displaying prices

The way subscription prices are displayed should be based on the price, currency, and billing_period. currency is an ISO 4217 code which can be used to select the correct currency symbol or formatting.

Start a subscription (begin_subscription)

Call begin_subscription with the sku of a subscription returned by get_subscriptions().

The method returns a JestSubscriptionResult with one of the following outcomes. In mock mode, you can simulate each outcome using the JestSDK debug menu.

Success

• status == JestSubscriptionResult.Status.SUCCESS with subscription and subscription_signed populated. Checkout completed successfully. The returned subscription is now "active" for the player's wallet.

Cancellation

• status == JestSubscriptionResult.Status.CANCELED The player closed or abandoned the checkout flow.

Error

• status == JestSubscriptionResult.Status.ERROR with error containing one of:
  • internal_error - A transient error occurred. Your game may retry.
  • invalid_subscription - The requested sku is not available. Do not retry with the same sku. If this persists and the subscription configuration appears correct, contact support.
  • already_subscribed - The player's wallet already has an active entitlement for this subscription. Refresh the wallet's state via get_subscriptions().
  • guest_not_allowed - The player is a guest. The platform automatically shows a signup gate before returning this error, so your game does not need to prompt for registration — handle the error gracefully.

var payment = JestSDK.payment
var list_result = await payment.get_subscriptions()

var premium: JestSubscription = null
for s in list_result.subscriptions:
    if s.sku == "premium_monthly":
        premium = s
        break

if premium == null or premium.status == "active":
    # Already entitled, or offering not available; nothing to do.
    return

var begin_result = await payment.begin_subscription(premium.sku)

if begin_result.status == JestSubscriptionResult.Status.CANCELED:
    # Handle cancellation with UI feedback
    return

if begin_result.status == JestSubscriptionResult.Status.ERROR:
    if begin_result.error == "guest_not_allowed":
        # The platform already showed a signup gate; no need to prompt.
        return
    if begin_result.error == "already_subscribed":
        # Re-read entitlement state and unlock features.
        return
    # internal_error / invalid_subscription: handle with UI feedback
    return

# status == SUCCESS
var subscription = begin_result.subscription
var subscription_signed = begin_result.subscription_signed
unlock_features_for(subscription.sku)

tip

After a successful begin_subscription, prefer using the returned subscription (or, better, subscription_signed) to unlock features immediately. The next get_subscriptions() call will return the same "active" status.

Cancel a subscription (cancel_subscription)

Call cancel_subscription with the sku of an active subscription. The platform opens a confirmation dialog with the player; if the player confirms, the subscription is cancelled at the end of the current billing period (the player retains the entitlement until then).

The method returns a JestCancelSubscriptionResult with one of:

Success

• status == JestCancelSubscriptionResult.Status.SUCCESS The player confirmed the cancellation. The subscription will remain "active" until the end of the current billing period, then transition to "inactive" on the next get_subscriptions() call.

Cancellation

• status == JestCancelSubscriptionResult.Status.CANCELED The player dismissed the confirmation dialog without cancelling the subscription. No change is made.

Error

• status == JestCancelSubscriptionResult.Status.ERROR with error containing one of:
  • internal_error - A transient error occurred. Your game may retry.
  • not_found - The requested sku does not correspond to a known subscription. Do not retry with the same sku.
  • not_active - The player's wallet does not have an active entitlement for this subscription. Refresh state via get_subscriptions().
  • guest_not_allowed - The player is a guest. Guests cannot have subscriptions to cancel.

var payment = JestSDK.payment
var result = await payment.cancel_subscription("premium_monthly")

if result.status == JestCancelSubscriptionResult.Status.CANCELED:
    # Player dismissed the confirmation dialog; nothing to do.
    return

if result.status == JestCancelSubscriptionResult.Status.ERROR:
    print("Cancel failed: %s" % result.error)
    return

# status == SUCCESS
# The subscription will lapse at the end of the current billing period.
# Re-read get_subscriptions() the next time you need authoritative state.

note

Cancellation only schedules the subscription to lapse at the end of the current billing period. The entitlement remains "active" until then, and your game should continue to unlock the relevant features for the remainder of the period.

Claim a retention offer (claim_retention_offer)

Call claim_retention_offer with the sku of a subscription the player currently holds, when its retention_offer is non-empty (see Retention discounts). The discount is applied to their existing subscription instantly — no checkout.

The method returns a JestSubscriptionResult (the same result type as begin_subscription) with one of:

Success

• status == JestSubscriptionResult.Status.SUCCESS with subscription and subscription_signed populated. The discount was applied. The returned subscription reflects the post-claim state (retention_offer is now empty).

Error

• status == JestSubscriptionResult.Status.ERROR with error containing one of:
  • internal_error - A transient error occurred. Your game may retry.
  • not_eligible - The player's wallet cannot claim this subscription's retention discount (already claimed, not entitled, or an introductory offer window is still running). Refresh state via get_subscriptions().
  • guest_not_allowed - The player is a guest. Guests cannot have subscriptions to claim a discount on.

var payment = JestSDK.payment
var result = await payment.claim_retention_offer("premium_monthly")

if result.status == JestSubscriptionResult.Status.ERROR:
    print("Claim retention offer failed: %s" % result.error)
    return

# status == SUCCESS
# result.subscription reflects the post-claim state.

Signed subscription data (JWT)

The begin_subscription and get_subscriptions methods return subscription data in two forms:

1. As objects (subscription / subscriptions) for convenience.
2. As signed tokens (subscription_signed / signed) in the form of a signed JSON Web Token (JWT).

The data inside the signed token is equivalent to the plain object. For critical actions such as unlocking paid content or applying entitlements server-side, you must only trust the signed token after verifying its signature.

For server-side verification examples and details, see the HTML5 SDK Subscriptions documentation.

warning

Failure to verify the signed token can leave your game vulnerable to exploitation. Players can otherwise spoof an "active" status without paying.

Testing

When using a sandbox user, the Stripe checkout flow still needs to be completed — the player goes through the same checkout UI as a normal player — but the order total is $0 and no real charge is made. Once checkout is completed, the resulting subscription is treated as "active" for the duration of a normal billing period, so you can test the subscribed and unsubscribed flows end-to-end without spending real money.

If the subscription configures a free trial, a sandbox user receives it on their first subscribe (at $0, with no payment method required), so you can test the trial flow too.

Every JestSubscription returned to a sandbox user carries sandbox = true, including inside the signed token, so your backend can tell a test subscription from a paying one. price stays as configured — only the amount actually billed is $0 — so the flag is the only reliable signal here. intro_offer is null and retention_offer is empty for a sandbox user, since a checkout already forced to $0 carries no discount; test those flows with a real player, or in the Simulator. Grant the entitlement as usual, and keep sandbox subscribers out of revenue reporting.

In mock mode, you can simulate each begin_subscription and cancel_subscription outcome (success, cancel, errors), each claim_retention_offer outcome (success, errors), and toggle the wallet's entitlement on each subscription SKU via the JestSDK debug menu.