Skip to content
/
Update Subscription

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

Get Subscription

Request

Gets a specific subscription details by ID.

Security
basicAuth
Path
project_idintegerrequired

Project ID.

subscription_idintegerrequired

Subscription ID.

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

Responses

OK.

Bodyapplication/json
idinteger

Subscription ID

planobject
userobject
productobject or null
charge_amountnumber(float)

Billing amount.

currencystring

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

date_createstring(datetime)

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

date_endstring(datetime)

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

date_last_chargestring or null(datetime)

Last subscription charge date in the YYYY-MM-DD’T’HH:MM:SS format per ISO 8601.

date_next_chargestring or null(datetime)

Next subscription charge date in the YYYY-MM-DD’T’HH:MM:SS format per ISO 8601.

statusstring

Status

Enum"new""active""canceled""non_renewing""freeze"
commentstring

Reason for changing subscription status

Response
application/json
{
  "charge_amount": 0.03,
  "comment": "The subscription was not extended in due time\r",
  "currency": "USD",
  "date_create": "2018-09-21T16:54:59+03:00",
  "date_end": "2019-02-06T12:43:04+03:00",
  "date_last_charge": "2018-09-21T16:55:05+03:00",
  "date_next_charge": "2018-09-21T16:55:05+03:00",
  "id": 249579,
  "plan": {
    "external_id": "lowcost",
    "id": 601
  },
  "product": {
    "id": 123456
  },
  "status": "canceled",
  "user": {
    "id": "user1",
    "name": "John Smith"
  }
}

Update Subscription

Request

Updates a subscription by either changing its status (active, canceled, or non_renewing) or postponing the next billing date.

Security
basicAuth
Path
project_idintegerrequired

Project ID.

user_idstringrequired

User ID.

subscription_idintegerrequired

Subscription ID.

Bodyapplication/jsonrequired
statusstring

Status.

Enum"active""canceled""non_renewing"
cancel_subscription_paymentboolean

Setting to true will refund the last payment made for this subscription. Only works together with setting the status to canceled.

timeshiftobject

Billing postponement.

xsolla_networkobject
curl -i -X PUT \
  -u <username>:<password> \
  'https://xsolla.redocly.app/_mock/api/subscriptions/projects/{project_id}/users/{user_id}/subscriptions/{subscription_id}' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "active"
  }'

Responses

OK.

Bodyapplication/json
Response
application/json
{
  "charge_amount": 0.03,
  "currency": "USD",
  "date_create": "2018-09-21T16:54:59+03:00",
  "date_end": null,
  "date_last_charge": "2018-09-21T16:55:05+03:00",
  "date_next_charge": "2018-09-21T16:55:05+03:00",
  "id": 24953579,
  "plan": {
    "charge": { … },
    "description": null,
    "expiration": { … },
    "external_id": "lowcost",
    "grace_period": { … },
    "billing_retry": { … },
    "refund_period": null,
    "group_id": "newPlans",
    "id": 66001,
    "localized_name": null,
    "name": null,
    "project_id": 18404,
    "status": { … },
    "tags": null,
    "trial": { … },
    "type": "all"
  },
  "product": null,
  "status": "active",
  "user": {
    "id": "jb1",
    "name": "J.Black"
  }
}

Get Subscriptions

Request

Lists all recurrent subscriptions.

Notice

This API method can’t be used under a high load. The maximum load is 20 requests per minute.

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.

Query
offsetinteger

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

limitintegerrequired

Limit for the number of elements on the page.

user_idstring

User ID.

project_id[]Array of integers

List of project IDs.

plan_id[]Array of integers

List of subscription plan IDs.

product_id[]Array of integers

List of product IDs the plans are linked to.

group_id[]Array of strings

List of group IDs the plans are linked to.

status[]Array of strings

Status.

Items Enum"active""canceled""non_renewing"
datetime_fromstring(datetime)

Sample date. Use this to find subscriptions created later than the request.

datetime_tostring(datetime)

Sample date. Use this to find subscriptions created later than the request.

curl -i -X GET \
  -u <username>:<password> \
  'https://xsolla.redocly.app/_mock/api/subscriptions/merchants/{merchant_id}/subscriptions?offset=0&limit=0&user_id=string&project_id%5B%5D=0&plan_id%5B%5D=0&product_id%5B%5D=0&group_id%5B%5D=string&status%5B%5D=active&datetime_from=string&datetime_to=string'

Responses

OK.

Bodyapplication/jsonArray [
idinteger

Subscription ID

planobject
userobject
productobject or null
charge_amountnumber(float)

Billing amount.

currencystring

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

date_createstring(datetime)

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

date_endstring(datetime)

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

date_last_chargestring or null(datetime)

Last subscription charge date in the YYYY-MM-DD’T’HH:MM:SS format per ISO 8601.

date_next_chargestring or null(datetime)

Next subscription charge date in the YYYY-MM-DD’T’HH:MM:SS format per ISO 8601.

statusstring

Status

Enum"new""active""canceled""non_renewing""freeze"
commentstring

Reason for changing subscription status

]
Response
application/json
[
  {
    "id": 45,
    "status": "canceled",
    "user": { … },
    "charge_amount": 0.03,
    "currency": "USD",
    "date_create": "2013-09-05T15:27:47+04:00",
    "date_end": "2014-02-06T11:32:48+04:00",
    "date_last_charge": null,
    "date_next_charge": null,
    "plan": { … },
    "product": { … }
  }
]

Payments

Operations

Promotions

Operations

Coupons

Operations

Subscription management

Operations