Get started

Integration flow

To integrate Subscriptions:

  1. Register an Xsolla Publisher Account.
  2. Set up a plan.
  3. Set up webhooks.
  4. Get a token.
  5. Configure the UI opening flow.

How it works

Step 1 — Get a token for opening payment UI

Step 2 — Make a purchase

Step 3 — Make a payment

User flow


Subscription plan
Billing conditions (billing amount, currency, and frequency) in terms of which a user gets their access to the service. Setting up a plan is a required integration step.
Subscription-based product
A service or a set of services provided to a user when they purchase the subscription. Product creation is necessary if you set up the sale of separate subscriptions for different services or if you want to give a user the ability to get several subscriptions at the same time. An example of a subscription product is a streamer or influencer channel.


A combination of the product and the chosen plan. A subscription is created when a user selects a subscription plan and gets access to a service. The number of subscriptions a user can get at the same time depends on the number of products in the project. Subscription conditions (billing period, cost, and others) correspond to the conditions of the selected plan. Conditions of the existing subscription are not changed if conditions of the plan were changed after subscription had been created.


Product: Access to the game

  • Subscription plan Silver: $10 per 1 month
  • Subscription plan Gold: $100 per 1 year

A user can select one of the following subscriptions:

  • Subscription 1: Access to the game with the $10/month plan
  • Subscription 2: Access to the game with the $100/year plan


Product 1: Access to the game1

Product 2: Access to the game2

  • Subscription plan: $10 per 1 month

A user can get two subscriptions simultaneously:

  • Subscription 1: Access to the game1 with the $10/month plan
  • Subscription 2: Access to the game2 with the $10/month plan

If the subscription-based product is not set up, the user can get only one subscription at a time. To get several subscriptions simultaneously, you need to set up products.
Group of plans
A set of plans that have the same value of the group_id parameter. Creating a group of plans is necessary if you want to:
  • limit the number of plans you can choose to subscribe to a product
  • let the user switch to another plan from the group
You can choose not to create groups if:
  • no products are created in your project
  • multiple products are created in your project and a subscription to each of the products can be sold with any of the project plans
  • One plan can belong only to one group.
  • One group can be used for many products.
  • One product can be created based on only one group.
  • By default, plans are created with the group_id: null parameter and included in the general group.
Trial period
The period when the user can try out the subscription without paying for it. Features:
  • When a subscription with a trial period is purchased, a billing account is created, and an authorization payment is made. There is a small amount charged from the user’s account and, then, refunded. When payment is charged, a payment webhook is not sent to the webhook URL.
  • After the end of the trial period, the full cost of the subscription plan is charged and Payment and Updated subscription webhooks are sent to the webhook URL. If the payment for the subscription is unsuccessful the Canceled Subscription webhook is sent. The trial period is not included in the plan’s validity period and its duration is calculated separately.
  • A trial period can be added as a bonus to a promotion.
  • Grace period
    A grace period is the period of time that defines the length of time the user can access the game after the subscription expires. Features:
    • A grace period is supported only by subscriptions with the one-time payment type. Payment for auto-renewing subscriptions is processed automatically.
    • You can change the length of the grace period in Publisher Account.
    • The system sends payment reminders every day until the user pays for the subscription or the grace period ends.
    • The user pays the full subscription price. The number of days the user spends in the grace period is removed from the main billing period, as these days are included in the main subscription.
    • If the value in the Grace period field in the plan settings is 0, the plan has no grace period.
    Retry period
    The period when attempts to charge from the saved payment account are made. Configurable only for subscriptions with the automatic renewal type and is activated after the failed money withdrawal. Features:
    • The system tries to withdraw money from the payment account once a day.
    • The system will try to withdraw money until the subscription is renewed, canceled by a user, or canceled after the number of billing retries exceeds.
    • If this setting is active, the user will have access to the subscription until the number of billing retries exceeds.
    • If the subscription is renewed by a user, the number of days the system has spent on the billing attempts (one day per attempt) is removed from the main billing period, as these days are included in the main subscription.
    Auto payment
    A subscription renewal type that automatically charges your saved billing account. No user action is required. If the billing account has not been saved, a subscription with an automatic payment type switches to the Non renewing status.
    One-time payment
    A subscription renewal type when charges are made by the user with the payment link received by email. Used if the user selects a payment method that does not support automatic payments.

    Subscription statuses

    A subscription can have one of the following statuses:

    • Active. Primary status. The subscription is created and activated after the first successful payment. Further charges are only possible for active subscriptions.

    You cannot create a subscription manually using the API — this can only be done automatically upon making a purchase.

    • Canceled. The subscription has been canceled with immediate effect due to one of the following reasons:
      • Status changed via an API method or from the Xsolla Publisher Account.
      • Canceled by the user.
      • Expired, if an expiration date was set in the parameters.
      • Maximum number of charging attempts exceeded. This is three by default; please contact your Account Manager to change it.
      • User not found in the game.
      • User account deleted.

    When a subscription is canceled, the last payment can be refunded. This option is available for both the partner and the user.

    • Non renewing. Subscription renewal canceled. The subscription will last until the current billing cycle ends before the status changes to Canceled. A renewal can be canceled due to one of the following reasons:
      • Status changed via an API method or from Publisher Account.
      • Canceled by user via email link.
      • User account deleted.

    Was this article helpful?
    Thank you!
    Is there anything we can improve? Message
    We’re sorry to hear that
    Please explain why this article wasn’t helpful to you. Message
    Thank you for your feedback!
    We’ll review your message and use it to help us improve your experience.
    Rate this page
    Rate this page
    Is there anything we can improve?

    Don’t want to answer

    Thank you for your feedback!

    Continue reading

    Last updated: March 23, 2021

    Found a typo or other text error? Select the text and press Ctrl+Enter.

    Report a problem
    We always review our content. Your feedback helps us improve it.
    Provide an email so we can follow up
    Thank you for your feedback!