Get subscription information

If you plan to sell subscriptions in the Web Shop, implement receiving information about actions with subscriptions in one of the following ways:

  • via API (suitable for serverless integration)
  • via webhooks (automatic notifications, suitable for server integration)

Set up via API calls

On the client side of your application, implement getting information about user subscriptions using an HTTP GET request.

Xsolla API uses HTTP access authentication. The request must contain a header Authorization: Bearer <client_user_jwt>, where <client_user_jwt> is a unique token encoded according to the Base64 standard. To get it:

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

  • limit — limit for the number of elements on the page (15 elements are displayed by default).
  • offset — number of the element from which the list is generated (the count starts from 0).
  • locale — interface language (English by default). Accepts values according to the ISO 639-1 standard.
Request example:

Full screen
Small screen
  '​/api/user/v1/projects/{projectId}/subscriptions?locale=ru&limit=5&offset=5 ' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer client_user_jwt'

Response example:

Full screen
Small screen
  "items": [
      "id": 11111111,
      "plan_id": 11111
      "plan_external_id": "TestChangePlanBase",
      "plan_name": "package_recurrent_name_66053",
      "plan_description": "package_recurrent_description_66053",
      "product_id": null,
      "product_external_id": null,
      "product_name": null,
      "product_description": null,
      "status": "active",
      "date_create": "2021-03-11T13:50:11+03:00",
      "date_next_charge": "2031-04-11T13:51:02+03:00",
      "date_last_charge": "2021-03-11T13:51:02+03:00",
      "charge": {
        "amount": "0.2500",
        "currency": "USD"
      "period": {
        "value": 1,
        "unit": "day"
  "has_more": true

Set up via webhooks

  1. Configure parameters for receiving webhooks:
    1. Open your project in Publisher Account.
    2. Click Project settings in the side menu and go to the Webhooks tab.
    3. In the Webhook server field, specify the URL of your server where you want to receive webhooks in the format. You can also specify the URL you find in a tool for testing webhooks.
    4. A secret key to sign project webhooks is generated by default. If you want to generate a new secret key, click the refresh icon.
    5. Click Enable webhooks.

  1. Implement processing of the following types of webhooks in your application:

  1. Test webhooks:
    1. In Publisher Account > Project settings > Webhooks, go to the Subscriptions tab.
    1. To test webhooks, specify values from your project (user ID, invoice ID) to be sent in a request to the webhook URL you provided. In the absence of real values, you can enter arbitrary values. Complete the following form fields:
      • User ID
      • Xsolla Invoice ID
      • Amount
      • Currency
      • Plan ID
      • Subscription product (optional)
      • Invoice ID — internal order number (optional)
      • Trial period (To test subscription purchase in Sandbox mode or test subscription renewal, set a 0 value.)
In Publisher Account, you can only test basic User Validation and Payment webhooks.
    1. Click Test.
    2. Verify that you received a test success message. If your test is successful, your server must respond with:
      • HTTP code 204 without a message body.
      • HTTP code 400 or 500 describing the problem if the specified user was not found or if an invalid signature was passed.
  1. Test receiving the remaining webhooks:
    1. Use sandbox mode to test purchase and renewing a subscription and get the Created Subscription, Updated Subscription, and Canceled Subscription webhooks.
    2. Use live mode to test subscription purchase on real payments and get the Refund, Canceled Subscription webhooks.

Next steps

  1. Set up user authentication.
  2. Test Web Shop in sandbox mode.

Integration flow

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!
Last updated: March 18, 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!