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.

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.

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".

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. Prompt them to register before starting a subscription.

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":
        # Prompt the player to register, then re-try.
        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.

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.

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

Revenue estimate

Jest's economics model splits revenue between the publisher, the platform, and publishers who bring users in to the platform.

Subscription revenue is recognized on each successful billing cycle, not at signup. Final revenue will be reported via the developer console (details coming soon).