Skip to content
/
Set Rewards

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

Review Promotion

Request

You need to review a promotion before activating it. This method returns the list of errors, if any.

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.

promotion_idintegerrequired

Promotion ID.

curl -i -X GET \
  -u <username>:<password> \
  'https://xsolla.redocly.app/_mock/api/subscriptions/merchants/{merchant_id}/promotions/{promotion_id}/review'

Responses

OK.

Bodyapplication/jsonArray [
componentstring
messagestring
]
Response
application/json
[
  {
    "component": "rewards",
    "message": "Please select a reward"
  }
]

Set Rewards

Request

Sets the rewards for a promotion. If the promotion is read-only (read_only = true), you cannot update the rewards.

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.

promotion_idintegerrequired

Promotion ID.

Bodyapplication/jsonrequired
purchaseobject

Set the reward for the whole purchase.

purchase.​discount_percentnumber(float)

Discount percentage.

packageobject

Set the reward for a virtual currency package.

package.​bonus_percentnumber(float)

Reward as a percentage of the package amount.

package.​bonus_amountnumber(float)

Reward as an absolute quantity of the virtual currency.

itemobject

Set the reward for specific virtual items.

item.​discountArray of objects

Discounts for specific virtual items.

item.​discount[].​localized_namestring

Plan name in default language (en), replicates name.en value.

item.​discount[].​skustring

Item SKU.

item.​discount[].​discount_percentnumber(float)

Discount percentage.

item.​discount[].​max_amountnumber(integer)

Maximum number of items to apply the promotion to.

item.​bonusArray of objects

Extra virtual items given as a bonus.

item.​bonus[].​idinteger
item.​bonus[].​localized_namestring

Plan name in default language (en), replicates name.en value.

item.​bonus[].​skustring

Item SKU.

item.​bonus[].​quantityinteger

Number of virtual items given as a bonus.

subscriptionobject

Sets the reward for a subscription.

subscription.​trial_daysinteger

Trial period in days.

curl -i -X PUT \
  -u <username>:<password> \
  'https://xsolla.redocly.app/_mock/api/subscriptions/merchants/{merchant_id}/promotions/{promotion_id}/rewards' \
  -H 'Content-Type: application/json' \
  -d '{
    "item": {
      "bonus": [
        {
          "quantity": 2,
          "sku": "1234"
        }
      ],
      "discount": [
        {
          "discount_percent": 5,
          "max_amount": 10,
          "sku": "1234"
        }
      ]
    },
    "package": {
      "bonus_amount": 5,
      "bonus_percent": 5
    },
    "purchase": {
      "discount_percent": 10
    },
    "subscription": {
      "trial_days": 30
    }
  }'

Responses

No content.

Get Rewards

Request

Gets the list of rewards associated with a promotion.

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.

promotion_idintegerrequired

Promotion ID.

curl -i -X GET \
  -u <username>:<password> \
  'https://xsolla.redocly.app/_mock/api/subscriptions/merchants/{merchant_id}/promotions/{promotion_id}/rewards'

Responses

OK.

Bodyapplication/json
idinteger
purchaseobject

Set the reward for the whole purchase.

purchase.​discount_percentnumber(float)

Discount percentage.

packageobject

Set the reward for a virtual currency package.

package.​bonus_percentnumber(float)

Reward as a percentage of the package amount.

package.​bonus_amountnumber(float)

Reward as an absolute quantity of the virtual currency.

itemobject

Set the reward for specific virtual items.

item.​discountArray of objects

Discounts for specific virtual items.

item.​discount[].​localized_namestring

Plan name in default language (en), replicates name.en value.

item.​discount[].​skustring

Item SKU.

item.​discount[].​discount_percentnumber(float)

Discount percentage.

item.​discount[].​max_amountnumber(integer)

Maximum number of items to apply the promotion to.

item.​bonusArray of objects

Extra virtual items given as a bonus.

item.​bonus[].​idinteger
item.​bonus[].​localized_namestring

Plan name in default language (en), replicates name.en value.

item.​bonus[].​skustring

Item SKU.

item.​bonus[].​quantityinteger

Number of virtual items given as a bonus.

subscriptionobject

Sets the reward for a subscription.

subscription.​trial_daysinteger

Trial period in days.

Response
application/json
{
  "id": 17840,
  "item": {
    "bonus": [ … ],
    "discount": [ … ]
  },
  "package": {
    "bonus_amount": 5,
    "bonus_percent": 5
  },
  "purchase": {
    "discount_percent": 10
  },
  "subscription": {
    "trial_days": 30
  }
}

Coupons

Operations

Subscription management

Operations