Skip to content

Subscriptions API (2.0)

Overview

  • Version: 2.0
  • Servers: https://api.xsolla.com/merchant/v2/

This API reference describes endpoints for managing subscriptions, coupons, and promotions. To get more information about Subscriptions, see the product guide and the glossary.

Download OpenAPI description
index.json
index.yaml
Languages
Servers
Mock server
https://xsolla.redocly.app/_mock/api/subscriptions/

Token

Operations

Plans

Operations

Products

Operations

Subscription management

Operations

Payments

Operations

Promotions

Operations

Coupons

Operations

Get Coupon

Request

Get coupon details by its code.

Security
basicAuth
Path
project_idintegerrequired

Project ID.

codestringrequired

Coupon code.

curl -i -X GET \
  -u <username>:<password> \
  'https://xsolla.redocly.app/_mock/api/subscriptions/projects/{project_id}/coupons/{code}/details'

Responses

OK.

Bodyapplication/json
keystring

Key of the user attribute.

nameobject

Localized attribute names.

typestring

Key type.

Enum"int""string""enum""date"
list_of_valuesArray of objects

Array of possible values for enum type.

skip_condition_on_nonexistent_keyboolean

Whether to skip the condition if key doesn't exist.

visibleboolean
Response
application/json
{
  "key": "12",
  "list_of_values": [],
  "name": {
    "en": "Level",
    "ru": "Уровень"
  },
  "skip_condition_on_nonexistent_key": true,
  "type": "int",
  "visible": false
}

Redeem Coupon

Request

Redeem a coupon by its code.

Security
basicAuth
Path
project_idintegerrequired

Project ID.

codestringrequired

Coupon code.

Bodyapplication/jsonrequired
user_idstringrequired

User ID.

Example: "1234"
curl -i -X POST \
  -u <username>:<password> \
  'https://xsolla.redocly.app/_mock/api/subscriptions/projects/{project_id}/coupons/{code}/redeem' \
  -H 'Content-Type: application/json' \
  -d '{
    "user_id": "1234"
  }'

Responses

OK.

Bodyapplication/json
campaign_codestring
coupon_codestring
coupon_idinteger
expiration_datestring
is_activeboolean
project_idinteger
redeems_count_for_userinteger
redeems_count_remaininteger
subscription_couponstring or null
virtual_currency_amountinteger
virtual_itemsArray of strings
Response
application/json
{
  "campaign_code": "new_campaign",
  "coupon_code": "ddgf5bn4",
  "coupon_id": 89613996,
  "expiration_date": "2019-12-31T00:00:00+00:00",
  "is_active": true,
  "project_id": 12345,
  "redeems_count_for_user": 10,
  "redeems_count_remain": 20,
  "subscription_coupon": null,
  "virtual_currency_amount": 200,
  "virtual_items": []
}

Create Campaign

Request

Create a new coupon campaign.

Notice

This API call does not contain the project_id path-parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization.

Security
basicAuth
Path
merchant_idintegerrequired

Merchant ID.

Bodyapplication/jsonrequired
campaign_codestringrequired

Campaign name.

project_idintegerrequired

Project ID.

campaign_namesobjectrequired

Object containing localized campaign names.

campaign_names.​enstring

English.

campaign_names.​rustring

Russian.

campaign_names.​csstring

Czech.

campaign_names.​arstring

Arabic.

campaign_names.​bgstring

Bulgarian.

campaign_names.​cnstring

Chinese (Simplified).

campaign_names.​twstring

Chinese (Traditional).

campaign_names.​frstring

French.

campaign_names.​destring

German.

campaign_names.​hestring

Hebrew.

campaign_names.​itstring

Italian.

campaign_names.​kostring

Korean.

campaign_names.​plstring

Polish.

campaign_names.​ptstring

Portuguese.

campaign_names.​rostring

Romanian.

campaign_names.​esstring

Spanish.

campaign_names.​thstring

Thai.

campaign_names.​trstring

Turkish.

campaign_names.​vistring

Vietnamese.

campaign_names.​jastring

Japanese.

expiration_datestring(datetime)

Campaign expiration date in the YYYY-MM-DD’T’HH:MM:SS format per ISO 8601.

virtual_currency_amountnumber(float)

Virtual currency amount in a reward.

virtual_itemsobject

Array of virtual items parameters in a reward.

subscription_couponobject

Object containing subscription parameters in a reward.

redeems_countinteger

Maximum number of coupon redeems. If null is passed, the redeems number is unlimited.

redeems_count_for_userinteger

Maximum number of coupon redeems per user. If null is passed, the redeems number is unlimited.

campaign_redeems_count_for_userinteger

Maximum number of coupon redeems per user within a campaign. If null is passed, the redeems number is unlimited.

curl -i -X POST \
  -u <username>:<password> \
  'https://xsolla.redocly.app/_mock/api/subscriptions/merchants/{merchant_id}/coupon_promotions' \
  -H 'Content-Type: application/json' \
  -d '{
    "campaign_code": "sample_campaign",
    "campaign_names": {
      "en": "Campaign Name",
      "ru": "Название кампании"
    },
    "campaign_redeems_count_for_user": 1,
    "expiration_date": "2019-12-31",
    "project_id": 12345,
    "redeems_count": 10,
    "redeems_count_for_user": 1,
    "subscription_coupon": {
      "plan_id": 123,
      "product_id": 456,
      "trial_period": 30
    },
    "virtual_currency_amount": 200
  }'

Responses

Created.

Bodyapplication/json
idinteger
Example: 9134
Response
application/json
{
  "id": 9134
}

Subscription management

Operations