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.

Copy
Full screen
Small screen
Request Example:
  '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'

Copy
Full screen
Small screen
Response Example:
{
  "items": [
    {
      "id": 13371337,
      "plan_id": 66053,
      "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": 5,
        "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.
    3. Go to the Webhooks section.
    4. Set the Webhooks toggle to On.
    5. In the Webhook URL field, specify the URL to receive webhooks.
    6. A secret key to sign project webhooks is generated by default. If you want to generate a new secret key, click the refresh icon.
    7. Click Save settings.

  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 payment in Sandbox mode or test subscription renewal, set a 0 value.)

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

Your progress
Thank you for your feedback!
Last updated: May 12, 2022

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!