How to allow a user to change a subscription plan

How it works

• When choosing a new plan, a refund is made to the user’s balance for the unused period of the current subscription.
• Payment for the new subscription plan is made entirely from the user’s balance. If their balance is insufficient, an additional payment is made by any of the payment methods allowed in the project.
• When changing the plan, funds are debited immediately after payment is confirmed, even if the project is configured to change the plan from the next billing period.

• If the currency of the new plan is different from the currency of the current plan, the purchase of the new plan will be done with a currency conversion.

• the user already has an active subscription with the plan that the current plan is changing to
• the subscription that the user wants to change is not in the Active status
• the subscription plan that the user wants to change is of the Lifetime plan type: such a subscription can only be canceled within the specified refund period

How to get it

1. Open your project in Publisher Account.
2. Click Subscriptions in the sidebar and go to the Settings section.
3. In the Changing plan section, set the Ability to choose a different plan toggle to On.
4. Plan changes are allowed from the next period by default. To allow changing the plan in the current period, select Now. If you select this option, the plan changes immediately after payment is confirmed.
5. To allow plan changes more than once a day, set the toggle Ability to choose a different plan several times on the same day to On.
6. When opening the payment interface, use:
   • server-side Create token API call
   • client-side API call for getting a link to open a payment UI if you use Xsolla Login in your project

Opening the payment UI via the server-side Create token API call

1. Get a token to open the payment UI by passing the following to the method:
   • change_plan value in the purchase.subscription.operation parameter.
   • ID of the new plan in the purchase.subscription.plan_id parameter.
   • Subscription-based product ID in the purchase.subscription.product_id parameter if you are using subscription-based products. To get it, contact your Customer Success Manager or email to csm@xsolla.com.
2. Open the payment interface in one of the following ways:
   • Pay Station Embed script
   • Iframe
   • New window

Opening the payment UI on the subscription management page using the client-side API call

If Xsolla Login is configured in your project, you can use the client-side API call to get a link to open the payment interface. The link returned in the response allows you to open the payment UI on the subscription management page, where users can select an active subscription and change it.

To do this, on the client side of your application, implement receiving a link to the payment interface using an HTTP POST request: https://subscriptions.xsolla.com​/api/user/v1/projects/{project_id}/subscriptions/manage. The request must contain an Authorization: Bearer <client_user_jwt> header, where <client_user_jwt> is user’s JSON Web Token (JWT) — a unique, Base64-encoded token encoded according to the Base64 standard. To get the token:

• Use the Register new user and Auth by username and password API calls if your application uses login and password authorization.
• Use the Auth via social network API call if your application uses authorization through social networks.

Pass additional parameters for customization if needed.

Request body parameters:

curl -X 'POST' \
'https://subscriptions.xsolla.com/api/user/v1/projects/{project_id}/subscriptions/manage?country=RU  ' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer client_user_jwt'
{
  "settings": {
    "ui": {
      "size": "large",
      "theme": "string",
      "version": "desktop",
      "desktop": {
        "header": {
          "is_visible": true,
          "visible_logo": true,
          "visible_name": true,
          "type": "compact",
          "close_button": true
        }
      },
      "mobile": {
        "mode": "saved_accounts",
        "footer": {
          "is_visible": true
        },
        "header": {
          "close_button": true
        }
      },
      "license_url": "string",
      "mode": "user_account",
      "user_account": {
        "history": {
          "enable": true,
          "order": 1
        },
        "payment_accounts": {
          "enable": true,
          "order": 1
        },
        "info": {
          "enable": true,
          "order": 1
        },
        "subscriptions": {
          "enable": true,
          "order": 1
        }
      }
    },
    "currency": "str",
    "locale": "st",
    "external_id": "string",
    "payment_method": 1,
    "return_url": "string",
    "redirect_policy": {
      "redirect_conditions": "none",
      "delay": 0,
      "status_for_manual_redirection": "none",
      "redirect_button_caption": "string"
    }
  }
}

Response example:

{
  "link_to_ps": "https://secure.xsolla.com/paystation2/?access_token=<access_token>"
}