Manage subscriptions

Jest allows you to sell recurring subscriptions in your app using the payments SDK methods. Subscriptions are a good fit for ad removal, premium tiers, or recurring access to additional content.

Subscriptions are configured in the Developer Console and then retrieved in your app using JestSDK.payments.getSubscriptions().

To manage subscriptions, open the Developer Console and navigate to:

Apps > Manage > Subscriptions

How subscriptions work

Each subscription represents an ongoing entitlement granted to a user's wallet for as long as billing succeeds.

You define:

• SKU – A unique identifier used in your app code.
• Name – The display name shown during checkout and in your app's UI.
• Description (optional) – A short description shown during checkout.
• Price – The recurring cost in USD.
• Billing period – How often the user is billed (monthly or yearly).
• Free trial (optional) – A trial length in days (up to 14). Leave blank or 0 for no trial. See Free trials.
• Intro offer (optional) – A discounted price for the first N months (monthly subscriptions only). See Introductory offers.

When your app calls:

• getSubscriptions() – The configured subscriptions are returned, each annotated with the user's current entitlement status (active or inactive).
• beginSubscription({ subscriptionSku }) – The user can subscribe to a specific SKU.

For details on the full subscription lifecycle (checkout, entitlement, recovery) and signed-token verification, see the Subscriptions SDK documentation.

Add a subscription

To create a new subscription:

1. Click Create Subscription.
2. Enter:
   • SKU (required)
   • Name (required)
   • Price in USD (required)
   • Billing period (required) – monthly or yearly
   • Description (optional)
   • Free trial in days (optional) – up to 14; leave blank or 0 for no trial
   • Intro offer (optional) – a discounted intro price and a duration in months (1–12); monthly subscriptions only
   • Retention offer (optional) – a discounted price a cancelling subscriber can claim once via your app; monthly subscriptions only. See Retention discounts.
3. Click Create Subscription.

note

The SKU and billing period cannot be changed after creation. If you need to modify either, archive the existing subscription and create a new one.

tip

To offer the same tier at both cadences, create two subscriptions — e.g. premium_monthly billed monthly and premium_yearly billed yearly.

warning

This is by design: the platform treats every subscription SKU as an independent product and does not relate them, even when they unlock the same thing in your app. Entitlement and free-trial eligibility are tracked per SKU, so nothing on the platform side stops a user who subscribed to premium_monthly from also subscribing to premium_yearly — they would be billed for both.

Your app is responsible for not offering a subscription that grants the same entitlements once the user has signed up for one of them. Check each SKU's status via getSubscriptions() and hide or disable the equivalent offers while any one of them is active. If you offer a free trial on a tier, configure it on only one of that tier's SKUs.

Edit a subscription

To update a subscription:

1. Click Edit next to the subscription.
2. Update the name, description, or free-trial length.
3. Save your changes.

note

Price and billing-period changes are not applied to existing subscribers. To change pricing, archive the existing subscription and create a new one at the new price; existing subscribers continue to be billed at the price they signed up for until they cancel or it expires.

note

Free-trial changes apply to future checkouts only. Editing or removing the trial length does not affect users who are already subscribed or currently mid-trial.

Free trials

You can offer a free trial on any subscription by setting a trial length of up to 14 days when you create or edit it. Leave it blank or set it to 0 for no trial.

How trials behave:

• First-time only. A trial is offered only to wallets that have never subscribed to that product before. A user who has subscribed to it previously — even if their subscription has since lapsed — is billed immediately with no trial. The SDK exposes this per-wallet eligibility as a trialEligible flag on each subscription so your app can show a "Start free trial" CTA only when the user will actually get one.
• The entitlement is active during the trial. From your app's perspective the subscription is "active" for the whole trial, so the user has full access. See your SDK's free-trials reference (HTML5, Unity, Godot) for how to read entitlement.
• Billing starts automatically at trial end. The user provides a payment method at checkout, and the platform charges the subscription price when the trial ends. Normal recurring billing continues from there.
• Cancelling during the trial. If the user cancels before the trial ends, they keep the entitlement until the trial period is over and are never charged.

Introductory offers

You can offer new subscribers a discounted price for the start of their subscription — for example, $4.99/mo instead of $9.99/mo for the first 3 months — by setting an intro price and an intro duration in months (1–12) when you create or edit a subscription.

How intro offers behave:

• Monthly subscriptions only. Intro offers cannot be configured on yearly subscriptions.
• Combinable with a free trial. The discount window is measured from signup, trial included, but with trials capped at 14 days the subscriber always receives every configured discounted month after the trial ends.
• First-time only. Like trials, the intro price is offered only to wallets that have never subscribed to that product before. The SDK exposes the offer as a nullable introOffer field (price and durationPeriods) on each subscription, populated only when the user is eligible, so your app can advertise the offer only when the user will actually get it.
• Automatic transition. The user pays the discounted price for the configured number of months, then transitions to the standard price automatically. No action is needed from you or the user.
• The intro price must be at least $0.50 and lower than the standard price. The console validates this when you create or edit the subscription, including when you later change the standard price.
• Changes apply to future checkouts only. Users who subscribed under an intro offer keep the terms they signed up with.

Retention discounts

You can configure a retention discount alongside the intro offer: a discounted price (at least $0.50 and lower than the standard price) and a duration in months (1–12), for monthly subscriptions only. It is never applied automatically — it exists for your app's own cancel flow.

How retention discounts behave:

• Claimed by the app, once per user. While a subscriber is entitled and eligible, the SDK exposes the offer as a nullable retentionOffer field on their subscription; your app applies it with claimRetentionOffer when the user accepts your pitch. Each user can claim it once per subscription, and not during a free trial or while an introductory offer window is still running.
• Same subscription throughout. The discount applies to the user's existing subscription starting at their next renewal; after the configured months the standard price returns automatically. There is no second product to manage and nothing for the user to re-purchase.
• Current terms, grandfathered basis. A claim always grants your current retention price and duration — including for subscribers who joined before you configured or last edited the offer. What's grandfathered is their own standard price: the discount is applied against what they actually pay, and a subscriber is only eligible while the retention price is below it.
• Changes apply to future claims only. Users who already claimed a discount keep the terms it was claimed with.

See Retention discounts in the SDK docs for the app-side recipe.

Archive a subscription

To remove a subscription from sale:

1. Click Archive next to the subscription.

Archived subscriptions:

• Are no longer returned by getSubscriptions() to users who do not currently have an active entitlement for them.
• Cannot be newly subscribed to.
• Continue to be returned (with status: "active") to existing subscribers until their entitlement expires, so your app can keep honoring the entitlement they paid for.

If your app attempts to start checkout for an archived or invalid SKU, beginSubscription will return an invalid_subscription error. See the Subscriptions SDK documentation for error details.

Testing subscriptions

When using a sandbox user, the user still has to complete the Stripe checkout flow, but the order total is $0 and no real charge is made. Once checkout is completed, the entitlement behaves as if the user had subscribed normally, so you can test both the subscribed and unsubscribed flows end-to-end without making real payments.

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

Guests cannot subscribe. If your app targets the beginSubscription call at a guest user, the platform automatically shows a signup gate prompting the user to register, then returns a guest_not_allowed error. Your app does not need to build its own registration prompt — just handle the error gracefully.

See Subscriptions for details on entitlement recovery and best practices.