Create catalog UI

There are three ways to create catalog UI:

Using own interface

When creating a directory in your own interface, you can use:

  • Own data storage and any authorization option. In this case, implement the catalog UI on your side.
  • Your own authorization and the Get Plans server-side method. Implement the catalog UI on your side after getting the list of plans.
  • Xsolla Login and client-side API calls.
Note
You can also use the SDK libraries to implement a catalog in your own interface. Ready-made libraries facilitate integrating Xsolla products into your project by providing out-of-the-box data structures and methods for working with Xsolla API.

Xsolla Login and client-side API calls

To implement a catalog:
  1. Get a list of subscription plans using client methods:
  2. Implement the display of the received list of plans in the interface.

Client-side method to get the subscription plans by products

On the client side of your application, use an HTTP get request to implement getting the list of plans: https://subscriptions.xsolla.com​/api/user/v1/projects/{project_id}/products/{​​productId}/plans.

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:

Specify as the path parameters:
  • projectId — project ID. You can find this parameter in your Publisher Account next to the name of the project.
  • productID — subscription-based product ID. To get it, contact your Customer Success Manager or email to csm@xsolla.com.

Specify as query parameters:
ParameterTypeDescription
plan_id
array of integersPlan ID.
plan_external_id
array of stringsPlan external ID. Can be found in the Publisher Account in the Subscriptions > Subscription plans > your plan section or via the Get Plans API call.
limit
integerLimit for the number of elements on the page. 15 items are displayed by default.
offset
integerNumber of the element from which the list is generated. The count starts from 0 by default.
locale
stringInterface language in two-letter lowercase. Accepts ISO 639-1 values. If this parameter is not passed, the language is determined by the user’s IP address.
Available values:
  • en — English
  • ar — Arabic
  • bg — Bulgarian
  • cn — Chinese (Simplified)
  • cs — Czech
  • de — German
  • es — Spanish
  • fr — French
  • he — Hebrew
  • it — Italian
  • ja — Japanese
  • ko — Korean
  • pl — Polish
  • pt — Portuguese
  • ro — Romanian
  • ru — Russian
  • th — Thai
  • tr — Turkish
  • tw — Chinese (Traditional)
  • vi — Vietnamese
If passed the locale that is not in the Xsolla list, then English locale is used.
country
stringThe two-letter ISO 3166-1 alpha-2 designation is used to identify the user’s country. This parameter affects the choice of locale and currency. If this parameter is not passed, the country is determined by the user’s IP address.
Copy
Full screen
Small screen
    curl -X 'GET' \
    'https://subscriptions.xsolla.com​/api/user/v1/projects/{project_id}/products/{​​productId}/plans?country=RU  ' \
      -H 'accept: application/json' \
      -H 'Authorization: Bearer client_user_jwt'
    
    Copy
    Full screen
    Small screen
    {
      "items": [
        {
          "plan_id": 54321,
          "plan_external_id": "PlanExternalId",
          "plan_group_id": "TestGroupId",
          "plan_type": "all",
          "plan_name": "Localized plan name",
          "plan_description": "Localized plan description",
          "plan_start_date": "2021-04-11T13:51:02+03:00",
          "plan_end_date": "2031-04-11T13:51:02+03:00",
          "trial_period": 7,
          "period": {
            "value": 1,
            "unit": "month"
          },
          "charge": {
            "amount": 4.99,
            "setup_fee": 0.99,
            "currency": "USD"
          },
          "promotion": {
            "promotion_charge_amount": 3.99,
            "promotion_remaining_charges": 3
          }
        }
      ],
      "has_more": false
    }
    

    Client-side method for getting the list of plans

    On the client side of your application, use an HTTP GET request to implement getting the list of plans: https://subscriptions.xsolla.com​/api/user/v1/projects/{project_id}/plans.

    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:

    Specify the project ID as the projectId path parameter. You can find this parameter in your Publisher Account next to the name of the project.

    Specify as query parameters:

    ParameterTypeDescription
    plan_id
    array of integersPlan ID.
    plan_external_id
    array of stringsPlan external ID. Can be found in the Publisher Account in the Subscriptions > Subscription plans > your plan section or via the Get Plans API call.
    limit
    integerLimit for the number of elements on the page. 15 items are displayed by default.
    offset
    integerNumber of the element from which the list is generated. The count starts from 0 by default.
    locale
    stringInterface language in two-letter lowercase. Accepts ISO 639-1 values. If this parameter is not passed, the language is determined by the user’s IP address.
    Available values:
    • en — English
    • ar — Arabic
    • bg — Bulgarian
    • cn — Chinese (Simplified)
    • cs — Czech
    • de — German
    • es — Spanish
    • fr — French
    • he — Hebrew
    • it — Italian
    • ja — Japanese
    • ko — Korean
    • pl — Polish
    • pt — Portuguese
    • ro — Romanian
    • ru — Russian
    • th — Thai
    • tr — Turkish
    • tw — Chinese (Traditional)
    • vi — Vietnamese
    If passed the locale that is not in the Xsolla list, then English locale is used.
    country
    stringThe two-letter ISO 3166-1 alpha-2 designation is used to identify the user’s country. This parameter affects the choice of locale and currency. If this parameter is not passed, the country is determined by the user’s IP address.
    Copy
    Full screen
    Small screen
      curl -X 'GET' \
      'https://subscriptions.xsolla.com​/api/user/v1/projects/{project_id}/plans?country=RU  ' \
        -H 'accept: application/json' \
        -H 'Authorization: Bearer client_user_jwt'
        
      
      Copy
      Full screen
      Small screen
      {
        "items": [
          {
            "plan_id": 54321,
            "plan_external_id": "PlanExternalId",
            "plan_group_id": "TestGroupId",
            "plan_type": "all",
            "plan_name": "Localized plan name",
            "plan_description": "Localized plan description",
            "plan_start_date": "2021-04-11T13:51:02+03:00",
            "plan_end_date": "2031-04-11T13:51:02+03:00",
            "trial_period": 7,
            "period": {
              "value": 1,
              "unit": "month"
            },
            "charge": {
              "amount": 4.99,
              "setup_fee": 0.99,
              "currency": "USD"
            },
            "promotion": {
              "promotion_charge_amount": 3.99,
              "promotion_remaining_charges": 3
            }
          }
        ],
        "has_more": false
      }
      

      Using Xsolla Pay Station

      1. Implement getting the token via the server-side Create token API call. Pass the following parameters in the request:
        • user.id — user ID in your authorization system.
        • user.email — user email. Must be valid according to the RFC 822 protocol.
        • settings.project_id — project ID. You can find this parameter in your Publisher Account next to the name of the project.
      2. Implement opening the payment UI in one of the following ways:
      Copy
      Full screen
      Small screen
      {
          "user": {
              "name": {
                  "value": "j.smith@email.com"
              },
              "id": {
                  "value": "123a345b678c091d"
              }
          },
          "settings": {
              "project_id": 177226
          }
      }
      

      An example of displaying the subscription catalog in the Xsolla Pay Station:

      Using Xsolla Site Builder

      Xsolla Site Builder allows you to create and set up your site for subscription sales. To do this, use the Web Shop template to create a site. You can read more about setting up roles in the Web Shop with user authentication instructions.

      Your progress
      Thank you for your feedback!
      Last updated: January 22, 2024

      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!