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

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

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