Skip to content
/
Update Plan

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

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

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.

chargeobject

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.

charge.​prices[].​amountnumber(float)required

Billing amount.

charge.​prices[].​currencystringrequired

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

charge.​prices[].​setup_feenumber(float)

One-time setup fee charged as part of the first invoice.

idinteger

Subscription plan ID.

external_idstring

Plan external ID (32 characters).

descriptionobject

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

description.​enstring

English.

description.​rustring

Russian.

description.​csstring

Czech.

description.​arstring

Arabic.

description.​bgstring

Bulgarian.

description.​cnstring

Chinese (Simplified).

description.​twstring

Chinese (Traditional).

description.​frstring

French.

description.​destring

German.

description.​hestring

Hebrew.

description.​itstring

Italian.

description.​kostring

Korean.

description.​plstring

Polish.

description.​ptstring

Portuguese.

description.​rostring

Romanian.

description.​esstring

Spanish.

description.​thstring

Thai.

description.​trstring

Turkish.

description.​vistring

Vietnamese.

description.​jastring

Japanese.

group_idstring or null

Group ID the plan is linked to.

expirationobject

Subscription expiration details.

expiration.​valueinteger or nullrequired

Validity time.

expiration.​typestringrequired

Time unit. Can be day or month.

Enum"day""month"
trialobject

Trial period details.

trial.​valueintegerrequired

Number of time units.

trial.​typestringrequired

Time unit. Can be day.

Value"day"
grace_periodobject

Grace period details.

grace_period.​valueintegerrequired

Number of time units.

grace_period.​typestringrequired

Time unit. Can be day.

Value"day"
billing_retryobject

Billing retry details.

billing_retry.​valueintegerrequired

Number of billing retries.

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
status.​valuestring

Subscription plan status.

Enum"active""disabled"
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".

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.

chargeobject

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.

charge.​prices[].​amountnumber(float)required

Billing amount.

charge.​prices[].​currencystringrequired

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

charge.​prices[].​setup_feenumber(float)

One-time setup fee charged as part of the first invoice.

external_idstring

Plan external ID (32 characters).

descriptionobject

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

description.​enstring

English.

description.​rustring

Russian.

description.​csstring

Czech.

description.​arstring

Arabic.

description.​bgstring

Bulgarian.

description.​cnstring

Chinese (Simplified).

description.​twstring

Chinese (Traditional).

description.​frstring

French.

description.​destring

German.

description.​hestring

Hebrew.

description.​itstring

Italian.

description.​kostring

Korean.

description.​plstring

Polish.

description.​ptstring

Portuguese.

description.​rostring

Romanian.

description.​esstring

Spanish.

description.​thstring

Thai.

description.​trstring

Turkish.

description.​vistring

Vietnamese.

description.​jastring

Japanese.

group_idstring

Group ID the plan is linked to.

expirationobject

Subscription expiration details.

expiration.​valueinteger or nullrequired

Validity time.

expiration.​typestringrequired

Time unit. Can be day or month.

Enum"day""month"
trialobject

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

trial.​valueintegerrequired

Number of time units.

trial.​typestringrequired

Time unit. Can be day.

Value"day"
grace_periodobject

Grace period details.

grace_period.​valueintegerrequired

Number of time units.

grace_period.​typestringrequired

Time unit. Can be day.

Value"day"
billing_retryobject

Billing retry details.

billing_retry.​valueintegerrequired

Number of billing retries.

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
status.​valuestring

Subscription plan status.

Enum"active""disabled"
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"
}

Enable Plan

Request

Enables a subscription plan.

Security
basicAuth
Path
project_idintegerrequired

Project ID.

plan_idintegerrequired

Plan ID.

curl -i -X PATCH \
  -u <username>:<password> \
  'https://xsolla.redocly.app/_mock/api/subscriptions/projects/{project_id}/subscriptions/plans/{plan_id}'

Responses

No content.

Products

Operations

Subscription management

Operations

Payments

Operations

Promotions

Operations

Coupons

Operations

Subscription management

Operations