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:

• When authorizing by login and password use the Register new user and Auth by username and password API calls.
• When authorizing through social networks use the Auth via social network API calls.

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.

-X 'GET' \
  'https://subscriptions.xsolla.com/api/user/v1/projects/{projectId}/subscriptions?locale=ru&limit=5&offset=5 ' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer client_user_jwt'

Response example:

{
  "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 https://example.com 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.

2. Implement processing of the following types of webhooks in your application:
   • To purchase and renew a subscription:
     • User Validation
     • Payment
     • Created Subscription
     • Updated Subscription
   • To cancel a subscription: Canceled Subscription
   • To refund: Refund

3. Test webhooks:
   1. In Publisher Account > Project settings > Webhooks, go to the Subscriptions tab.

2. 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.)

3. Click Test.
4. 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.

4. 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.

Useful links

Integration flow