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

Create Plan

Request

Creates a subscription plan.

Security
basicAuth
Path
project_idintegerrequired

Project ID.

Bodyapplication/jsonrequired
project_idinteger

Project ID.

nameobjectrequired

Plan name. Value consists of pairs "localization":"plan name".

name.​enstring

English.

name.​rustring

Russian.

name.​csstring

Czech.

name.​arstring

Arabic.

name.​bgstring

Bulgarian.

name.​cnstring

Chinese (Simplified).

name.​twstring

Chinese (Traditional).

name.​frstring

French.

name.​destring

German.

name.​hestring

Hebrew.

name.​itstring

Italian.

name.​kostring

Korean.

name.​plstring

Polish.

name.​ptstring

Portuguese.

name.​rostring

Romanian.

name.​esstring

Spanish.

name.​thstring

Thai.

name.​trstring

Turkish.

name.​vistring

Vietnamese.

name.​jastring

Japanese.

chargeobjectrequired

Billing details.

charge.​periodobjectrequired

Billing period.

charge.​period.​valueintegerrequired

Number of time units. The value depends on the type parameter and can be:
- from 1 to 366, if type is day
- from 1 to 12, if type is month
- 0 if type is lifetime

charge.​period.​typestringrequired

Time unit. Can be day, month or lifetime.

Enum"day""month""lifetime"
charge.​amountnumber(float)

Billing amount.

charge.​currencystring

Currency of the purchase. Three-letter currency code per ISO 4217.

charge.​pricesArray of objects

List of prices in different currencies.

idinteger

Subscription plan ID.

external_idstring

Plan external ID (32 characters).

descriptionobject

Plan description. Value consists of pairs "localization":"plan description".

group_idstring or null

Group ID the plan is linked to.

expirationobject

Subscription expiration details.

trialobject

Trial period details.

grace_periodobject

Grace period details.

billing_retryobject

Billing retry details.

refund_periodinteger or null

Period of time that user can refund the payment for a subscription plan (in days).

tagsArray of strings

Plan tags.

statusobject
curl -i -X POST \
  -u <username>:<password> \
  'https://xsolla.redocly.app/_mock/api/subscriptions/projects/{project_id}/subscriptions/plans' \
  -H 'Content-Type: application/json' \
  -d '{
    "charge": {
      "amount": 10,
      "currency": "USD",
      "period": {
        "type": "month",
        "value": 1
      },
      "prices": [
        {
          "amount": 8,
          "currency": "EUR",
          "setup_fee": 1.5
        },
        {
          "amount": 1000,
          "currency": "JPY",
          "setup_fee": 2.5
        }
      ]
    },
    "description": {
      "en": "2x more experience!"
    },
    "expiration": {
      "type": "day",
      "value": null
    },
    "external_id": "exp",
    "grace_period": {
      "type": "day",
      "value": 2
    },
    "billing_retry": {
      "value": 1
    },
    "refund_period": null,
    "name": {
      "en": "Experience boost"
    },
    "status": {
      "value": "active"
    },
    "trial": {
      "type": "day",
      "value": 7
    }
  }'

Responses

Сreated.

Bodyapplication/json
external_idstring
plan_idinteger
Response
application/json
{
  "external_id": "exp",
  "plan_id": 241082
}

Get Plans

Request

Lists all subscription plans.

Security
basicAuth
Path
project_idintegerrequired

Project ID.

Query
plan_idinteger

Subscription plan ID.

limitintegerrequired

Limit for the number of elements on the page.

offsetinteger

Number of the element from which the list is generated (the count starts from 0).

external_idstring

Plan external ID (32 characters).

group_idstring

Group ID the plans are linked to.

product_idinteger

Product ID the plans are linked to.

querystring

Search query (searches name.en (default locale)).

curl -i -X GET \
  -u <username>:<password> \
  'https://xsolla.redocly.app/_mock/api/subscriptions/projects/{project_id}/subscriptions/plans?plan_id=0&limit=0&offset=0&external_id=string&group_id=string&product_id=0&query=string'

Responses

OK.

Bodyapplication/jsonArray [
project_idinteger

Project ID.

nameobject

Plan name. Value consists of pairs "localization":"plan name".

chargeobject

Billing details.

idinteger

Subscription plan ID.

external_idstring

Plan external ID (32 characters).

descriptionobject

Plan description. Value consists of pairs "localization":"plan description".

group_idstring or null

Group ID the plan is linked to.

expirationobject

Subscription expiration details.

trialobject

Trial period details.

grace_periodobject

Grace period details.

billing_retryobject

Billing retry details.

refund_periodinteger or null

Period of time that user can refund the payment for a subscription plan (in days).

tagsArray of strings

Plan tags.

statusobject
localized_namestring

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

]
Response
application/json
[
  {
    "charge": { … },
    "description": { … },
    "expiration": { … },
    "external_id": "3b355320",
    "grace_period": { … },
    "billing_retry": { … },
    "refund_period": null,
    "group_id": null,
    "id": 241037,
    "localized_name": "Platinum VIP",
    "name": { … },
    "project_id": 40797,
    "status": { … },
    "tags": [],
    "trial": { … }
  },
  {
    "charge": { … },
    "description": { … },
    "expiration": { … },
    "external_id": "0fe1b6fc",
    "grace_period": { … },
    "billing_retry": { … },
    "refund_period": null,
    "group_id": null,
    "id": 241038,
    "localized_name": "Gold Status",
    "name": { … },
    "project_id": 40797,
    "status": { … },
    "tags": [],
    "trial": { … }
  }
]

Update Plan

Request

Updates subscription plan parameters.

Security
basicAuth
Path
project_idintegerrequired

Project ID.

plan_idintegerrequired

Plan ID.

Bodyapplication/jsonrequired
nameobject

Plan name. Value consists of pairs "localization":"plan name".

chargeobject

Billing details.

external_idstring

Plan external ID (32 characters).

descriptionobject

Plan description. Value consists of pairs "localization":"plan description".

group_idstring

Group ID the plan is linked to.

expirationobject

Subscription expiration details.

trialobject

Trial period details. If this parameter is not passed, the default values (0 days) are used.

grace_periodobject

Grace period details.

billing_retryobject

Billing retry details.

refund_periodinteger or null

Period of time that user can refund the payment for a subscription plan (in days).

tagsArray of strings

Plan tags.

statusobject
curl -i -X PUT \
  -u <username>:<password> \
  'https://xsolla.redocly.app/_mock/api/subscriptions/projects/{project_id}/subscriptions/plans/{plan_id}' \
  -H 'Content-Type: application/json' \
  -d '{
    "charge": {
      "amount": 20,
      "currency": "USD",
      "period": {
        "type": "month",
        "value": 1
      },
      "prices": [
        {
          "amount": 17,
          "currency": "EUR",
          "setup_fee": 1.5
        },
        {
          "amount": 2000,
          "currency": "JPY",
          "setup_fee": 2.5
        }
      ]
    },
    "description": {
      "en": "3x more experience!"
    },
    "expiration": {
      "type": "day",
      "value": null
    },
    "external_id": "exp",
    "grace_period": {
      "type": "day",
      "value": 2
    },
    "billing_retry": {
      "value": 1
    },
    "refund_period": null,
    "name": {
      "en": "Experience boost"
    },
    "tags": [],
    "trial": {
      "type": "day",
      "value": 7
    }
  }'

Responses

OK.

Bodyapplication/json
Response
application/json
{
  "charge": {
    "amount": 20,
    "currency": "USD",
    "period": { … },
    "prices": [ … ]
  },
  "description": {
    "en": "3x more experience!"
  },
  "expiration": {
    "type": "day",
    "value": 0
  },
  "external_id": "exp",
  "grace_period": {
    "type": "day",
    "value": 2
  },
  "billing_retry": {
    "value": 1
  },
  "refund_period": null,
  "group_id": null,
  "id": 241082,
  "localized_name": "Experience boost",
  "name": {
    "en": "Experience boost"
  },
  "project_id": 40797,
  "status": {
    "value": "active"
  },
  "tags": [],
  "trial": {
    "type": "day",
    "value": 7
  },
  "type": "all"
}

Products

Operations

Subscription management

Operations

Payments

Operations

Promotions

Operations

Coupons

Operations

Subscription management

Operations