{ "openapi": "3.0.0", "info": { "description": "# Overview\n\n* **Version:** 2.0\n* **Servers**: `https://api.xsolla.com/merchant/v2/`\n\nThis API reference describes endpoints for managing subscriptions, coupons, and promotions.\nTo get more information about Subscriptions, see the [product guide](https://developers.xsolla.com/doc/subscriptions) and the [glossary](https://developers.xsolla.com/doc/subscriptions/integration-guide/get-started/#general_glossary).\n", "title": "Subscriptions API", "version": "2.0" }, "tags": [ { "name": "token", "x-displayName": "Token" }, { "name": "plans", "x-displayName": "Plans" }, { "name": "products", "x-displayName": "Products" }, { "name": "subscriptions", "x-displayName": "Subscription management" }, { "name": "payments", "x-displayName": "Payments" }, { "name": "promotions", "x-displayName": "Promotions" }, { "name": "coupons", "x-displayName": "Coupons" }, { "name": "subscription-management", "x-displayName": "Subscription management" } ], "paths": { "/merchants/{merchant_id}/token": { "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ], "post": { "summary": "Create token", "description": "You can create a token with arbitrary user parameters. You send these parameters when obtaining the token and receive them back after a successful payment. A token can only contain parameters either described in this document or predefined by you.\n\nIf any parameter is sent in the wrong format or has the wrong type, no token will be issued. You will receive a 422 HTTP code with the error description in the JSON body. In `extended_message` you will receive an information what exact parameters have been sent incorrectly.\n
\n

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.

\n
", "tags": [ "token" ], "operationId": "create-token", "x-server": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/token" } ] } } } }, "responses": { "200": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } } }, "example": { "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT" } } } }, "422": { "description": "Unprocessable Entity.", "content": { "application/json": { "schema": { "type": "object", "properties": { "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "extended_message": { "type": "object", "properties": { "global_errors": { "type": "array", "items": { "type": "string" } }, "property_errors": { "type": "object", "description": "Object contains parameter names with error descriptions." } } }, "request_id": { "type": "string" } } }, "example": { "http_status_code": 422, "message": "JSON is not valid against json schema, please check documentation https://developers.xsolla.com/api/v2/getting-started/#api_token_ui", "extended_message": { "global_errors": [], "property_errors": { "purchase.checkout.amount": [ "String value found, but a number is required" ] } }, "request_id": "cd72633" } } } } } } }, "/merchants/{merchant_id}/promotions": { "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ], "post": { "summary": "Create Promotion", "description": "Create a new promotion.\n
\n

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.

\n
", "tags": [ "promotions" ], "operationId": "create-promotion", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "required": [ "project_id", "technical_name" ] }, { "$ref": "#/components/schemas/GetPromotion" } ] }, "example": { "description": { "en": "Promotion with 30% discount", "ru": "Акция со скидкой 30%" }, "label": { "en": "30%", "ru": "30%" }, "name": { "en": "30% discount", "ru": "скидка 30%" }, "project_id": 12345, "technical_name": "Sale promotion" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "Promotion ID." } } }, "example": { "id": 17890 } } } } } }, "get": { "summary": "Get Promotions List", "description": "List of all promotions.\n
\n

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.

\n
", "tags": [ "promotions" ], "operationId": "get-promotions-list", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "example": [ { "datetime": { "from": "2020-02-01T00:00:00+04:00", "to": "2020-11-30T01:28:42+04:00" }, "enabled": true, "id": 17840, "is_active": true, "is_infinite": false, "project": { "id": 12345, "localized_name": "Christmas sale" }, "read_only": false, "technical_name": "christmas" }, { "datetime": null, "enabled": false, "id": 17891, "is_active": false, "is_infinite": true, "project": { "id": 12345, "localized_name": "30% discount" }, "read_only": false, "technical_name": "Sale promotion" } ] } } } } } }, "/merchants/{merchant_id}/promotions/{promotion_id}": { "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ], "get": { "summary": "Get Promotion", "description": "Retrieves a promotion.\n
\n

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.

\n
", "tags": [ "promotions" ], "operationId": "get-promotion", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/promotion-id-path-param" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPromotion" }, "example": { "description": { "en": "Promotion with 30% discount", "ru": "Акция со скидкой 30%" }, "enabled": false, "id": 17890, "label": { "en": "30%", "ru": "30%" }, "name": { "en": "30% discount", "ru": "Скидка 30%" }, "project_id": 40544, "read_only": false, "show_banner": true, "technical_name": "Sale promotion" } } } } } }, "put": { "summary": "Update Promotion", "description": "Updates a promotion. If the promotion is read-only (`read_only` = `true`), you are not allowed to change `project_id` parameter.\n
\n

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.

\n
", "tags": [ "promotions" ], "operationId": "update-promotion", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/promotion-id-path-param" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "required": [ "project_id", "technical_name" ] }, { "$ref": "#/components/schemas/GetPromotion" } ] }, "example": { "description": { "en": "Promotion with 5% discount", "ru": "Акция со скидкой 5%" }, "label": { "en": "5%", "ru": "5%" }, "name": { "en": "5% discount", "ru": "скидка 5%" }, "project_id": 40544, "technical_name": "Sale promotion" } } } }, "responses": { "204": { "description": "No content." } } }, "delete": { "summary": "Delete Promotion", "description": "Deletes a promotion. You can only delete promotions with `enabled` = `false`.\n
\n

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.

\n
", "tags": [ "promotions" ], "operationId": "delete-promotion", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/promotion-id-path-param" } ], "responses": { "204": { "description": "No content." } } } }, "/merchants/{merchant_id}/promotions/{promotion_id}/review": { "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ], "get": { "summary": "Review Promotion", "description": "You need to review a promotion before activating it. This method returns the list of errors, if any.\n
\n

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.

\n
", "tags": [ "promotions" ], "operationId": "review-promotion", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/promotion-id-path-param" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "component": { "type": "string" }, "message": { "type": "string" } } } }, "example": [ { "component": "rewards", "message": "Please select a reward" } ] } } } } } }, "/merchants/{merchant_id}/promotions/{promotion_id}/rewards": { "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ], "put": { "summary": "Set Rewards", "description": "Sets the rewards for a promotion. If the promotion is read-only (`read_only` = `true`), you cannot update the rewards.\n
\n

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.

\n
", "tags": [ "promotions" ], "operationId": "set-rewards", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/promotion-id-path-param" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionReward" }, "example": { "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": { "204": { "description": "No content." } } }, "get": { "summary": "Get Rewards", "description": "Gets the list of rewards associated with a promotion.\n
\n

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.

\n
", "tags": [ "promotions" ], "operationId": "get-rewards", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/promotion-id-path-param" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "id": { "type": "integer" } } }, { "$ref": "#/components/schemas/PromotionReward" } ] }, "example": { "id": 17840, "item": { "bonus": [ { "id": 123456, "localized_name": "T-34-3", "quantity": 2, "sku": "1234" } ], "discount": [ { "discount_percent": 5, "localized_name": "T-34-3", "max_amount": 10, "sku": "1234" } ] }, "package": { "bonus_amount": 5, "bonus_percent": 5 }, "purchase": { "discount_percent": 10 }, "subscription": { "trial_days": 30 } } } } } } } }, "/merchants/{merchant_id}/promotions/{promotion_id}/toggle": { "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ], "put": { "summary": "Toggle Promotion", "description": "Toggles the status of a promotion from `enabled` to `disabled` and vice versa.\n
\n

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.

\n
", "tags": [ "promotions" ], "operationId": "toggle-promotion", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/promotion-id-path-param" } ], "responses": { "204": { "description": "No content." } } } }, "/merchants/{merchant_id}/promotions/{promotion_id}/subject": { "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ], "put": { "summary": "Set Subject", "description": "Sets the subject of a promotion. If the promotion is read-only (`read_only` = `true`), you cannot update the subject. The subject can take the following values: `purchase`, or `items`, or `packages`.\n
\n

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.

\n
", "tags": [ "promotions" ], "operationId": "set-subject", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/promotion-id-path-param" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionSubject" }, "example": { "digital_contents": null, "items": [ { "sku": "1234" } ], "packages": null, "purchase": false, "subscriptions": null } } } }, "responses": { "204": { "description": "No content." } } }, "get": { "summary": "Get Subject", "description": "Gets information on the subject of a promotion.\n
\n

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.

\n
", "tags": [ "promotions" ], "operationId": "get-subject", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/promotion-id-path-param" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PromotionSubject" }, { "type": "object", "properties": { "id": { "type": "integer" } } } ] }, "example": { "digital_contents": null, "id": 178, "items": [ { "id": 1234, "localized_name": "T-34-3", "sku": "1234" } ], "packages": null, "purchase": false, "subscriptions": null } } } } } } }, "/merchants/{merchant_id}/promotions/{promotion_id}/payment_systems": { "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ], "put": { "summary": "Set Payment Systems", "description": "Sets payment systems supported for a promotion. If the list is empty, the promotion will apply to all payment systems. If the promotion is read-only (`read_only` = `true`), you cannot call this method.\n
\n

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.

\n
", "tags": [ "promotions" ], "operationId": "set-payment-systems", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/promotion-id-path-param" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionPaymentSystem" }, "example": { "payment_systems": [ { "id": 24, "name": "PayPal" } ] } } } }, "responses": { "204": { "description": "No content." } } }, "get": { "summary": "Get Payment Systems", "description": "Gets payment systems supported for a promotion. If the list is empty, the promotion will apply to all payment systems.\n
\n

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.

\n
", "tags": [ "promotions" ], "operationId": "get-payment-systems", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/promotion-id-path-param" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "id": { "type": "integer" } } }, { "$ref": "#/components/schemas/PromotionPaymentSystem" } ] }, "example": { "id": 17840, "payment_systems": [ { "id": 27, "name": "Yandex.Money" } ] } } } } } } }, "/merchants/{merchant_id}/promotions/{promotion_id}/periods": { "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ], "put": { "summary": "Set Validity Periods", "description": "Sets date/time ranges when a promotion is valid. If the promotion is read-only (`read_only` = `true`), you cannot edit existing periods, but you can add new ones.\n
\n

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.

\n
", "tags": [ "promotions" ], "operationId": "set-validity-periods", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/promotion-id-path-param" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionPeriod" }, "example": { "periods": [ { "from": "2019-03-02T00:00:00+04:00", "to": "2019-04-02T00:00:00+04:00" } ] } } } }, "responses": { "204": { "description": "No content." } } }, "get": { "summary": "Get Validity Periods", "description": "Gets date/time ranges when a promotion is valid.\n
\n

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.

\n
", "tags": [ "promotions" ], "operationId": "get-validity-periods", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/promotion-id-path-param" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "id": { "type": "integer" } } }, { "$ref": "#/components/schemas/PromotionPeriod" } ] }, "example": { "id": 17840, "periods": [ { "from": "2020-02-01T00:00:00+04:00", "offset": "+04:00", "to": "2020-11-30T01:28:42+04:00" } ] } } } } } } }, "/projects/{project_id}/coupons/{code}/details": { "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ], "get": { "summary": "Get Coupon", "description": "Get coupon details by its code.", "tags": [ "coupons" ], "operationId": "get-coupon", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/code-path-param" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponAttribute" }, "example": { "key": "12", "list_of_values": [], "name": { "en": "Level", "ru": "Уровень" }, "skip_condition_on_nonexistent_key": true, "type": "int", "visible": false } } } } } } }, "/projects/{project_id}/coupons/{code}/redeem": { "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ], "post": { "summary": "Redeem Coupon", "description": "Redeem a coupon by its code.", "tags": [ "coupons" ], "operationId": "redeem-coupon", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/code-path-param" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "user_id" ], "properties": { "user_id": { "type": "string", "description": "User ID.", "example": "1234" } } } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Coupon" }, "example": { "campaign_code": "new_campaign", "coupon_code": "ddgf5bn4", "coupon_id": 89613996, "expiration_date": "2019-12-31T00:00:00+00:00", "is_active": true, "project_id": 12345, "redeems_count_for_user": 10, "redeems_count_remain": 20, "subscription_coupon": null, "virtual_currency_amount": 200, "virtual_items": [] } } } } } } }, "/merchants/{merchant_id}/coupon_promotions": { "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ], "post": { "summary": "Create Campaign", "description": "Create a new coupon campaign.\n
\n

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.

\n
", "tags": [ "coupons" ], "operationId": "create-campaign", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "required": [ "campaign_code", "project_id", "campaign_names" ] }, { "$ref": "#/components/schemas/Campaign" } ] }, "example": { "campaign_code": "sample_campaign", "campaign_names": { "en": "Campaign Name", "ru": "Название кампании" }, "campaign_redeems_count_for_user": 1, "expiration_date": "2019-12-31", "project_id": 12345, "redeems_count": 10, "redeems_count_for_user": 1, "subscription_coupon": { "plan_id": 123, "product_id": 456, "trial_period": 30 }, "virtual_currency_amount": 200 } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "example": 9134 } } } } } } } } }, "/merchants/{merchant_id}/coupon_promotions/{campaign_id}/coupons": { "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ], "post": { "summary": "Add Coupon to Campaign", "description": "Add a coupon code to a coupon campaign.\n
\n

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.

\n
", "tags": [ "coupons" ], "operationId": "add-coupon-to-campaign", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/campaign-id-path-param" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "coupon_code" ], "properties": { "coupon_code": { "type": "string", "description": "Coupon code.", "example": "34bryrb3" } } } } } }, "responses": { "204": { "description": "No content." } } } }, "/merchants/{merchant_id}/promotions/{promotion_id}/coupons": { "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ], "put": { "summary": "Attach Campaign to Promotion", "description": "Attach a coupon campaign to a specific promotion.\n
\n

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.

\n
", "tags": [ "coupons" ], "operationId": "attach-campaign-to-promotion", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/promotion-id-path-param" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "campaigns" ], "properties": { "campaigns": { "type": "array", "items": { "type": "integer" }, "description": "Array of campaigns IDs.", "example": [ 9135 ] } } } } } }, "responses": { "204": { "description": "No content." } } } }, "/projects/{project_id}/subscriptions/plans": { "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ], "post": { "summary": "Create Plan", "description": "Creates a subscription plan.", "tags": [ "plans" ], "operationId": "create-plan", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "required": [ "name", "charge" ] }, { "$ref": "#/components/schemas/SubscriptionsPlan" } ] }, "example": { "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": { "201": { "description": "Сreated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "external_id": { "type": "string" }, "plan_id": { "type": "integer" } } }, "example": { "external_id": "exp", "plan_id": 241082 } } } } } }, "get": { "summary": "Get Plans", "description": "Lists all subscription plans.", "tags": [ "plans" ], "operationId": "get-plans", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/plan-id-query-param" }, { "$ref": "#/components/parameters/limit-query-param" }, { "$ref": "#/components/parameters/offset-query-param" }, { "$ref": "#/components/parameters/external-id-query-param" }, { "$ref": "#/components/parameters/group-id-query-param" }, { "$ref": "#/components/parameters/product-id-query-param" }, { "$ref": "#/components/parameters/query-query-param" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionsPlan" }, { "type": "object", "properties": { "localized_name": { "type": "string", "description": "Plan name in default language (en), replicates name.en value." } } } ] } }, "example": [ { "charge": { "amount": 19.99, "currency": "USD", "period": { "type": "month", "value": 1 }, "prices": [ { "amount": 17.99, "currency": "EUR", "setup_fee": 1.5 }, { "amount": 2000, "currency": "JPY", "setup_fee": 2.5 } ] }, "description": { "en": "10x more experience!" }, "expiration": { "type": "day", "value": 0 }, "external_id": "3b355320", "grace_period": { "type": "day", "value": 0 }, "billing_retry": { "value": 1 }, "refund_period": null, "group_id": null, "id": 241037, "localized_name": "Platinum VIP", "name": { "en": "Platinum VIP", "fr": "Le VIP-statut platinum" }, "project_id": 40797, "status": { "value": "active" }, "tags": [], "trial": { "type": "day", "value": 0 } }, { "charge": { "amount": 9.99, "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": "3x more experience!" }, "expiration": { "type": "day", "value": 0 }, "external_id": "0fe1b6fc", "grace_period": { "type": "day", "value": 0 }, "billing_retry": { "value": 1 }, "refund_period": null, "group_id": null, "id": 241038, "localized_name": "Gold Status", "name": { "en": "Gold Status", "fr": "Le statut d’or" }, "project_id": 40797, "status": { "value": "active" }, "tags": [], "trial": { "type": "day", "value": 0 } } ] } } } } } }, "/projects/{project_id}/subscriptions/plans/{plan_id}": { "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ], "put": { "summary": "Update Plan", "description": "Updates subscription plan parameters.", "tags": [ "plans" ], "operationId": "update-plan-parameters", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/plan-id-path-param" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionsPlanRequest" }, "example": { "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": { "200": { "description": "OK.", "content": { "application/json": { "example": { "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": 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" } } } } } }, "patch": { "summary": "Enable Plan", "description": "Enables a subscription plan.", "tags": [ "plans" ], "operationId": "enable-plan", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/plan-id-path-param" } ], "responses": { "204": { "description": "No content." } } }, "delete": { "summary": "Disable Plan", "description": "Disables a subscription plan.", "tags": [ "plans" ], "operationId": "disable-plan", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/plan-id-path-param" } ], "responses": { "204": { "description": "No content." } } } }, "/projects/{project_id}/subscriptions/plans/{plan_id}/delete": { "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ], "delete": { "summary": "Delete Plan", "description": "Deletes a subscription plan.", "tags": [ "plans" ], "operationId": "delete-plan", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/plan-id-path-param" } ], "responses": { "204": { "description": "No content." } } } }, "/projects/{project_id}/subscriptions/products": { "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ], "post": { "summary": "Create Product", "description": "Creates a subscription-based product.", "tags": [ "products" ], "operationId": "create-product", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "required": [ "name", "group_id" ] }, { "$ref": "#/components/schemas/SubscriptionsProduct" } ] }, "example": { "description": { "en": "Kids TV" }, "group_id": "charge", "name": "Channel2" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "integer" } } }, "example": { "product_id": 172003 } } } } } }, "get": { "summary": "Get Products", "description": "Lists all subscription-based products.", "tags": [ "products" ], "operationId": "get-products", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/offset-query-param" }, { "$ref": "#/components/parameters/limit-query-param" }, { "$ref": "#/components/parameters/group-id-query-param" }, { "$ref": "#/components/parameters/product-id-query-param" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionsProductWithId" } }, "example": [ { "description": { "en": "Description in English." }, "group_id": "charge", "id": 714, "name": "Channel" }, { "description": { "en": "Description in English." }, "group_id": "notify", "id": 715, "name": "notify" }, { "description": { "en": "Description in English." }, "group_id": "charge", "id": 716, "name": "charge2" }, { "description": { "en": "Description in English." }, "group_id": "charge", "id": 486, "name": "Channel2" } ] } } } } } }, "/projects/{project_id}/subscriptions/products/{product_id}": { "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ], "put": { "summary": "Update Product", "description": "Updates a subscription-based product.", "tags": [ "products" ], "operationId": "update-product", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/product-id-path-param" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "required": [ "name", "group_id" ] }, { "$ref": "#/components/schemas/SubscriptionsProduct" } ] }, "example": { "description": { "en": "Description in English." }, "group_id": "charge13", "name": "Channel23" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionsProductWithId" }, "example": { "description": { "en": "Description in English." }, "group_id": "charge13", "id": 1713603, "name": "Channel23" } } } } } }, "delete": { "summary": "Delete Product", "description": "Deletes a subscription-based product.", "tags": [ "products" ], "operationId": "delete-product", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/product-id-path-param" } ], "responses": { "204": { "description": "No content." } } } }, "/projects/{project_id}/subscriptions/{subscription_id}": { "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ], "get": { "summary": "Get Subscription", "description": "Gets a specific subscription details by ID.", "tags": [ "subscriptions" ], "operationId": "get-subscription", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/subscription-id-path-param" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" }, "example": { "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" } } } } } } } }, "/projects/{project_id}/users/{user_id}/subscriptions/{subscription_id}": { "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ], "put": { "summary": "Update Subscription", "description": "Updates a subscription by either changing its status (`active`, `canceled`, or `non_renewing`) or postponing the next billing date.", "tags": [ "subscriptions" ], "operationId": "update-subscription", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/user-id-path-param" }, { "$ref": "#/components/parameters/subscription-id-path-param" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" }, "example": { "status": "active" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "example": { "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": { "amount": 0.03, "currency": "USD", "period": { "type": "day", "value": 1 } }, "description": null, "expiration": { "type": "day", "value": 0 }, "external_id": "lowcost", "grace_period": { "type": "day", "value": 2 }, "billing_retry": { "value": 1 }, "refund_period": null, "group_id": "newPlans", "id": 66001, "localized_name": null, "name": null, "project_id": 18404, "status": { "value": "active" }, "tags": null, "trial": { "type": "day", "value": 0 }, "type": "all" }, "product": null, "status": "active", "user": { "id": "jb1", "name": "J.Black" } } } } } } } }, "/merchants/{merchant_id}/subscriptions": { "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ], "get": { "summary": "Get Subscriptions", "description": "Lists all recurrent subscriptions.
Notice

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

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.

\n
", "tags": [ "subscriptions" ], "operationId": "get-subscriptions", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/offset-query-param" }, { "$ref": "#/components/parameters/limit-query-param" }, { "$ref": "#/components/parameters/user-id-query-param" }, { "$ref": "#/components/parameters/array-project-id-query-param" }, { "$ref": "#/components/parameters/array-plan-id-query-param" }, { "$ref": "#/components/parameters/array-product-id-query-param" }, { "$ref": "#/components/parameters/array-group-id-query-param" }, { "$ref": "#/components/parameters/status-query-param-array" }, { "$ref": "#/components/parameters/datetime-from-query-param" }, { "$ref": "#/components/parameters/datetime-to-query-param" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionResponse" } }, "example": [ { "id": 45, "status": "canceled", "user": { "id": "User1", "name": "John Smith" }, "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": { "id": 12345, "project_id": 12345 }, "product": { "id": null } } ] } } } } } }, "/projects/{project_id}/subscriptions/payments": { "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ], "get": { "summary": "Get Payments", "description": "Lists all subscription payments.", "tags": [ "payments" ], "operationId": "get-payments", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/offset-query-param" }, { "$ref": "#/components/parameters/limit-query-param" }, { "$ref": "#/components/parameters/user-id-query-param" }, { "$ref": "#/components/parameters/status-id-query-param" }, { "$ref": "#/components/parameters/datetime-from-query-param2" }, { "$ref": "#/components/parameters/datetime-to-query-param2" }, { "$ref": "#/components/parameters/subscription-id-query-param" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "example": [ { "date_payment": "2016-04-05T10:02:01+03:00", "id": 67683, "id_payment": 203960, "status": "fail", "subscription": { "charge_amount": 1, "comment": null, "currency": "RUB", "date_create": "2015-05-28T14:33:54+03:00", "date_end": "2016-04-05T10:02:07+03:00", "date_last_charge": "2015-06-03T16:07:29+03:00", "date_next_charge": "2015-06-04T00:00:00+03:00", "id": 3646, "plan": { "charge": { "amount": 1, "currency": "RUB", "period": { "type": "day", "value": 1 } }, "description": null, "expiration": { "type": "day", "value": 0 }, "external_id": "E8nJ79", "grace_period": { "type": "day", "value": 0 }, "billing_retry": { "value": 1 }, "refund_period": null, "group_id": "charge", "id": 24, "localized_name": null, "name": null, "project_id": 12345, "status": { "value": "deleted" }, "tags": null, "trial": { "type": "day", "value": 0 }, "type": "charge" }, "product": { "description": null, "group_id": "charge", "id": 1, "name": "charge" }, "status": "freeze", "user": { "id": "10", "name": "user2" } } }, { "date_payment": "2015-09-21T17:06:47+03:00", "id": 1531, "id_payment": 168866, "status": "done", "subscription": { "charge_amount": 1, "comment": " \r\n", "currency": "RUB", "date_create": "2015-09-21T17:06:47+03:00", "date_end": null, "date_last_charge": "2015-09-21T18:10:09+03:00", "date_next_charge": "2015-09-22T18:10:09+03:00", "id": 2004846, "plan": { "charge": { "amount": 1, "currency": "RUB", "period": { "type": "day", "value": 1 } }, "description": null, "expiration": { "type": "day", "value": 0 }, "external_id": "E8nX9", "grace_period": { "type": "day", "value": 0 }, "billing_retry": { "value": 1 }, "refund_period": null, "group_id": "charge", "id": 200, "localized_name": null, "name": null, "project_id": 70, "status": { "value": "deleted" }, "tags": null, "trial": { "type": "day", "value": 0 }, "type": "charge" }, "product": null, "status": "new", "user": { "id": "12", "name": "user1" } } } ] } } } } } }, "/projects/{project_id}/users/{user_id}/subscriptions/payments": { "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ], "get": { "summary": "Get User Payments", "description": "Lists all payments made by a specific user.", "tags": [ "payments" ], "operationId": "get-user-payments", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/user-id-path-param" }, { "$ref": "#/components/parameters/status-id-query-param" }, { "$ref": "#/components/parameters/offset-query-param" }, { "$ref": "#/components/parameters/limit-query-param" }, { "$ref": "#/components/parameters/datetime-from-query-param" }, { "$ref": "#/components/parameters/datetime-to-query-param" }, { "$ref": "#/components/parameters/subscription-id-query-param" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "example": [ { "date_payment": "2016-04-05T10:02:01+03:00", "id": 6746083, "id_payment": 202789960, "status": "fail", "subscription": { "charge_amount": 200, "comment": null, "currency": "RUB", "date_create": "2015-05-28T14:33:54+03:00", "date_end": "2016-04-05T10:02:07+03:00", "date_last_charge": "2015-06-03T16:07:29+03:00", "date_next_charge": "2015-06-04T00:00:00+03:00", "id": 36946, "plan": { "charge": { "amount": 200, "currency": "RUB", "period": { "type": "day", "value": 1 } }, "description": null, "expiration": { "type": "day", "value": 0 }, "external_id": "E8n34J79", "grace_period": { "type": "day", "value": 0 }, "group_id": "charge", "id": 24, "localized_name": null, "name": null, "project_id": 1234, "status": { "value": "deleted" }, "refund_period": null, "tags": null, "trial": { "type": "day", "value": 0 }, "type": "charge" }, "product": { "description": null, "group_id": "charge", "id": 1, "name": "charge" }, "status": "freeze", "user": { "id": "12", "name": "John" } } } ] } } } } } }, "/projects/{project_id}/subscriptions/currencies": { "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ], "get": { "summary": "Get Currencies", "description": "Lists all supported subscription currencies.", "tags": [ "payments" ], "operationId": "get-currencies", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "example": [ "AED", "ALL", "AMD", "ARS", "AUD", "AZN", "BAM", "BBD", "BGN", "BHD", "BND", "BRL", "BYN", "BZD", "CAD", "CHF", "CLP", "CNY", "COP", "CRC", "CZK", "DKK", "DZD", "EGP", "EUR", "GBP", "GEL", "GHS", "GIP", "GTQ", "HKD", "HRK", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "JPY", "KES", "KGS", "KRW", "KWD", "KZT", "LAK", "LBP", "LKR", "MAD", "MDL", "MKD", "MMK", "MNT", "MUR", "MXN", "MYR", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "SAR", "SEK", "SGD", "SVC", "THB", "TND", "TRY", "TWD", "UAH", "USD", "UYU", "UZS", "VEF", "VND", "XOF", "YER", "ZAR" ] } } } } } }, "/api/user/v1/management/projects/{project_id}/subscriptions": { "servers": [ { "url": "https://subscriptions.xsolla.com" } ], "get": { "tags": [ "subscription-management" ], "summary": "List subscriptions", "operationId": "list-subscriptions", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "locale", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } } ], "responses": { "200": { "description": "Get subscriptions info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListManagementSubscriptionsResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "example": { "error": { "code": "subscriptions.bad_request", "description": "Incorrect limit value, maximum allowed is 100" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } } } }, "security": [ { "subscriptionsManagementJwtAuth": [] } ] } }, "/api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}": { "servers": [ { "url": "https://subscriptions.xsolla.com" } ], "get": { "tags": [ "subscription-management" ], "summary": "Get subscription", "operationId": "get-management-subscription", "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } }, { "name": "locale", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } } ], "responses": { "200": { "description": "Get subscription info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementSubscriptionResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "example": { "error": { "code": "subscriptions.exception", "description": "Project with id = 123 was not found" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "error": { "code": "subscriptions.not_found", "description": "Subscription not found" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } } } }, "security": [ { "subscriptionsManagementJwtAuth": [] } ] } }, "/api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/cancel": { "servers": [ { "url": "https://subscriptions.xsolla.com" } ], "put": { "tags": [ "subscription-management" ], "summary": "Cancel subscription", "operationId": "cancel-subscription", "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } } ], "responses": { "200": { "description": "Make subscription non-renewable", "content": { "application/json": {} } }, "400": { "description": "Bad request", "content": { "application/json": { "example": { "error": { "code": "subscriptions.not_active", "description": "Subscription is not active" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "error": { "code": "subscriptions.not_found", "description": "Subscription not found" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } } } }, "security": [ { "subscriptionsManagementJwtAuth": [] } ] } }, "/api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_account": { "servers": [ { "url": "https://subscriptions.xsolla.com" } ], "get": { "tags": [ "subscription-management" ], "summary": "Get payment account", "operationId": "get-payment-account", "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } } ], "responses": { "200": { "description": "Get payment account info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRecurrentAccountResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "error": { "code": "data.not_found", "description": "Data not found" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } } } }, "security": [ { "subscriptionsManagementJwtAuth": [] } ] } }, "/api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/activate": { "servers": [ { "url": "https://subscriptions.xsolla.com" } ], "put": { "tags": [ "subscription-management" ], "summary": "Activate subscription", "operationId": "activate-subscription", "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } } ], "responses": { "200": { "description": "Move subscription from non-renew to active", "content": { "application/json": { "example": { "status": "successful" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "example": { "error": { "code": "subscriptions.bad_request", "description": "Subscription is not allowed to change to active" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "error": { "code": "subscriptions.not_found", "description": "Subscription not found" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } } } }, "security": [ { "subscriptionsManagementJwtAuth": [] } ] } }, "/api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/change_plan": { "servers": [ { "url": "https://subscriptions.xsolla.com" } ], "post": { "tags": [ "subscription-management" ], "summary": "Get change plan link", "operationId": "get-change-plan-link", "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } }, { "name": "plan_external_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "sandbox", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } } ], "responses": { "200": { "description": "Returns link to change subscription plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayStationLinkResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "example": { "error": { "code": "subscriptions.exception", "description": "Change plan is not possible" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "error": { "code": "subscriptions.not_found", "description": "ubscription with id = 123 not found or not belongs to user" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "example": { "error": { "code": "subscriptions.exception", "description": "Publisher API request failed" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } } } }, "security": [ { "subscriptionsManagementJwtAuth": [] } ] } }, "/api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/plans_for_change": { "servers": [ { "url": "https://subscriptions.xsolla.com" } ], "get": { "tags": [ "subscription-management" ], "summary": "List plans for change", "operationId": "list-plans-for-change", "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "locale", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } } ], "responses": { "200": { "description": "List of available plans for change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPlansResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "example": { "error": { "code": "subscriptions.exception", "description": "Incorrect limit value, maximum allowed is 100" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "error": { "code": "subscriptions.not_found", "description": "Subscription with id = 123 not found or not belongs to user" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } } } }, "security": [ { "subscriptionsManagementJwtAuth": [] } ] } }, "/api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/plans_for_change/{plan_id}": { "servers": [ { "url": "https://subscriptions.xsolla.com" } ], "get": { "tags": [ "subscription-management" ], "summary": "Get plan for change", "operationId": "get-plan-for-change", "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } }, { "name": "plan_id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } }, { "name": "locale", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } } ], "responses": { "200": { "description": "Available plans for change with payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePlanPaymentDetailsResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "example": { "error": { "code": "subscriptions.exception", "description": "Change plan is not possible" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "error": { "code": "subscriptions.not_found", "description": "Subscription with id = 123 not found or not belongs to user" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } } } }, "security": [ { "subscriptionsManagementJwtAuth": [] } ] } }, "/api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_account/manage": { "servers": [ { "url": "https://subscriptions.xsolla.com" } ], "post": { "tags": [ "subscription-management" ], "summary": "Manage payment account", "operationId": "manage-payment-account", "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } }, { "name": "sandbox", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } } ], "responses": { "200": { "description": "Returns link for managing payment accounts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayStationLinkResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "example": { "error": { "code": "subscriptions.exception", "description": "Token retrieve error" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "error": { "code": "subscriptions.not_found", "description": "Subscription with id = 123 not found or not belongs to user" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "example": { "error": { "code": "subscriptions.exception", "description": "Publisher API request failed" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } } } }, "security": [ { "subscriptionsManagementJwtAuth": [] } ] } }, "/api/user/v1/management/projects/{project_id}/subscriptions/settings": { "servers": [ { "url": "https://subscriptions.xsolla.com" } ], "get": { "tags": [ "subscription-management" ], "summary": "Get management settings", "operationId": "get-management-settings", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } } ], "responses": { "200": { "description": "Returns project settings for managing subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectManageSubscriptionSettingsResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "example": { "error": { "code": "subscriptions.access_denied", "description": "You don't have access to requested project or resource." }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "error": { "code": "subscriptions.not_found", "description": "Project not found" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "example": { "error": { "code": "subscriptions.exception", "description": "Retrieving data from cache has failed." }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } } } }, "security": [ { "subscriptionsManagementJwtAuth": [] } ] } }, "/api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_accounts": { "servers": [ { "url": "https://subscriptions.xsolla.com" } ], "get": { "tags": [ "subscription-management" ], "summary": "List payment accounts", "operationId": "list-payment-accounts", "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } } ], "responses": { "200": { "description": "Returns the user's billing accounts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingAccountsListResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "example": { "error": { "code": "subscriptions.access_denied", "description": "You don't have access to requested project or resource." }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "error": { "code": "subscriptions.not_found", "description": "Subscription with id = 123 not found or not belongs to user" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "example": { "error": { "code": "subscriptions.exception", "description": "Publisher API request failed." }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } } } }, "security": [ { "subscriptionsManagementJwtAuth": [] } ] }, "post": { "tags": [ "subscription-management" ], "summary": "Link payment account", "operationId": "link-payment-account", "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } }, { "name": "payment_account_id", "in": "query", "required": true, "schema": { "type": "integer" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } } ], "responses": { "200": { "description": "Links a payment account to a subscription", "content": { "application/json": { "example": { "status": "successful" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "example": { "error": { "code": "subscriptions.exception", "description": "This account is already linked" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "error": { "code": "subscriptions.not_found", "description": "Subscription with id = 123 not found or not belongs to user" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "example": { "error": { "code": "subscriptions.exception", "description": "Publisher API request failed" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } } } }, "security": [ { "subscriptionsManagementJwtAuth": [] } ] } }, "/api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_accounts/{payment_account_id}": { "servers": [ { "url": "https://subscriptions.xsolla.com" } ], "delete": { "tags": [ "subscription-management" ], "summary": "Unlink payment account", "operationId": "unlink-payment-account", "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } }, { "name": "payment_account_id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } } ], "responses": { "200": { "description": "Unlink payment accounts", "content": { "application/json": { "example": { "status": "successful" } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "error": { "code": "subscriptions.not_found", "description": "Subscription with id = 123 not found or not belongs to user" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "example": { "error": { "code": "subscriptions.exception", "description": "Error saving data" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } } } }, "security": [ { "subscriptionsManagementJwtAuth": [] } ] } } }, "components": { "parameters": { "project-id-path-param": { "name": "project_id", "in": "path", "required": true, "description": "Project ID.", "schema": { "type": "integer" } }, "plan-id-path-param": { "name": "plan_id", "in": "path", "required": true, "description": "Plan ID.", "schema": { "type": "integer" } }, "product-id-path-param": { "name": "product_id", "in": "path", "required": true, "description": "Product ID the plans are linked to.", "schema": { "type": "integer" } }, "subscription-id-path-param": { "name": "subscription_id", "in": "path", "required": true, "description": "Subscription ID.", "schema": { "type": "integer" } }, "user-id-path-param": { "name": "user_id", "in": "path", "required": true, "description": "User ID.", "schema": { "type": "string" } }, "merchant-id-path-param": { "name": "merchant_id", "in": "path", "required": true, "description": "Merchant ID.", "schema": { "type": "integer" } }, "code-path-param": { "name": "code", "in": "path", "required": true, "description": "Coupon code.", "schema": { "type": "string" } }, "campaign-id-path-param": { "name": "campaign_id", "in": "path", "required": true, "description": "Campaign ID.", "schema": { "type": "integer" } }, "promotion-id-path-param": { "name": "promotion_id", "in": "path", "required": true, "description": "Promotion ID.", "schema": { "type": "integer" } }, "offset-query-param": { "name": "offset", "in": "query", "description": "Number of the element from which the list is generated (the count starts from 0).", "schema": { "type": "integer" } }, "external-id-query-param": { "name": "external_id", "in": "query", "description": "Plan external ID (32 characters).", "schema": { "type": "string" } }, "group-id-query-param": { "name": "group_id", "in": "query", "description": "Group ID the plans are linked to.", "schema": { "type": "string" } }, "product-id-query-param": { "name": "product_id", "in": "query", "description": "Product ID the plans are linked to.", "schema": { "type": "integer" } }, "user-id-query-param": { "name": "user_id", "in": "query", "description": "User ID.", "schema": { "type": "string" } }, "status-id-query-param": { "name": "status", "in": "query", "description": "Transaction status.", "schema": { "type": "string", "enum": [ "done", "fail" ], "x-enumDescriptions": { "done": "Payment was successfully processed.", "fail": "Payment was not processed successfully, or refund was issued." } } }, "datetime-from-query-param": { "name": "datetime_from", "in": "query", "description": "Sample date. Use this to find subscriptions created later than the request.", "schema": { "type": "string", "format": "datetime" } }, "datetime-to-query-param": { "name": "datetime_to", "in": "query", "description": "Sample date. Use this to find subscriptions created later than the request.", "schema": { "type": "string", "format": "datetime" } }, "subscription-id-query-param": { "name": "subscription_id", "in": "query", "description": "Subscription ID.", "schema": { "type": "integer" } }, "limit-query-param": { "required": true, "name": "limit", "in": "query", "description": "Limit for the number of elements on the page.", "schema": { "type": "integer" } }, "array-group-id-query-param": { "name": "group_id[]", "in": "query", "description": "List of group IDs the plans are linked to.", "schema": { "type": "array", "items": { "type": "string" } } }, "array-product-id-query-param": { "name": "product_id[]", "in": "query", "description": "List of product IDs the plans are linked to.", "schema": { "type": "array", "items": { "type": "integer" } } }, "plan-id-query-param": { "name": "plan_id", "in": "query", "description": "Subscription plan ID.", "schema": { "type": "integer" } }, "array-plan-id-query-param": { "name": "plan_id[]", "in": "query", "description": "List of subscription plan IDs.", "schema": { "type": "array", "items": { "type": "integer" } } }, "query-query-param": { "name": "query", "in": "query", "description": "Search query (searches name.en (default locale)).", "schema": { "type": "string" } }, "array-project-id-query-param": { "name": "project_id[]", "in": "query", "description": "List of project IDs.", "schema": { "type": "array", "items": { "type": "integer" } } }, "status-query-param-array": { "name": "status[]", "in": "query", "description": "Status.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "active", "canceled", "non_renewing" ] } } }, "datetime-from-query-param2": { "name": "datetime_from", "in": "query", "description": "Period start.", "schema": { "type": "string", "format": "datetime" } }, "datetime-to-query-param2": { "name": "datetime_to", "in": "query", "description": "Period end.", "schema": { "type": "string", "format": "datetime" } } }, "schemas": { "token": { "type": "object", "properties": { "user": { "type": "object", "description": "User details.", "required": [ "id" ], "properties": { "id": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "string", "description": "User ID." } } }, "email": { "type": "object", "description": "The `user.email` object is an integral part of building anti-fraud models and helps increase acceptance rates. It is both Xsolla and payment systems requirement. If the parameter is not passed, the required field for entering email appears on the payment page. A user receives a purchase receipt to the email passed in the parameter or entered on the payment page.\n", "required": [ "value" ], "properties": { "value": { "type": "string", "description": "User email. Must be valid according to the [RFC 822](https://www.w3.org/Protocols/rfc822/#z8) protocol." } } }, "name": { "type": "object", "properties": { "value": { "type": "string", "description": "User screen name." } } }, "age": { "type": "integer", "description": "User age." }, "phone": { "type": "object", "properties": { "value": { "type": "string", "description": "User phone number." } } }, "country": { "type": "object", "properties": { "value": { "type": "string", "description": "Two-letter uppercase country code per [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)." }, "allow_modify": { "type": "boolean", "description": "Whether a user can change the country on payment UI. If `country.value` is passed in the token, the value is `false` by default." } } }, "attributes": { "type": "object", "description": "User attributes for filtering the item list, represented as a valid JSON set of key-value pairs." }, "steam_id": { "type": "object", "properties": { "value": { "type": "string", "description": "Steam ID." } } }, "tracking_id": { "type": "object", "properties": { "value": { "type": "string", "description": "Unique tracking ID (used in marketing campaigns)." } } }, "public_id": { "type": "object", "properties": { "value": { "type": "string", "description": "Parameter that uniquely identifies the user and is known to the user (email, screen name, etc). Allows the user to make purchases outside the game store (e.g., via cash kiosks)." } } }, "utm": { "type": "object", "description": "Traffic attributes.", "properties": { "utm_source": { "type": "string", "description": "Traffic source." }, "utm_medium": { "type": "string", "description": "Traffic channel (contextual ads, media ads, email lists, etc.)." }, "utm_campaign": { "type": "string", "description": "Campaign title, transliterated or translated to English." }, "utm_term": { "type": "string", "description": "Campaign keyword. If set, statistics will be based on the keywords used for ad targeting rather than on specific search queries. In Google Analytics, the specified `utm_term` is part of the general search terms report." }, "utm_content": { "type": "string", "description": "Campaign content." } } }, "is_legal": { "type": "boolean", "description": "Whether the user is a legal entity." }, "legal": { "allOf": [ { "description": "Object with legal entity details. Object and all its parameters are required if `user.is_legal` is `true`." }, { "type": "object", "description": "Object with legal entity details.", "properties": { "name": { "type": "string", "description": "Full legal name." }, "address": { "type": "string", "description": "Full legal address." }, "vat_id": { "type": "string", "description": "Individual taxpayer identifier." }, "country": { "type": "string", "description": "Country of incorporation. Two-letter uppercase country code per [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) is used." } } } ] } } }, "settings": { "type": "object", "description": "Custom project settings.", "required": [ "project_id" ], "properties": { "project_id": { "type": "integer", "description": "Game’s Xsolla ID. Can be found in Publisher Account." }, "external_id": { "type": "string", "description": "Transaction ID in the game. Has to be unique for each user payment." }, "language": { "type": "string", "description": "Interface language. Two-letter lowercase [language code](https://developers.xsolla.com/doc/pay-station/features/localization/)." }, "return_url": { "type": "string", "description": "Page to redirect the user to after payment. Parameters `user_id`, `foreigninvoice`, `invoice_id` and `status` will be automatically added to the link." }, "redirect_policy": { "type": "object", "description": "Redirect policy settings.", "properties": { "redirect_conditions": { "type": "string", "description": "Payment status for which a user is redirected to the return URL. Can be `none`, `successful`, `successful_or_canсeled`, or `any`.", "enum": [ "none", "successful", "successful_or_canceled", "any" ] }, "delay": { "type": "integer", "description": "Delay (in seconds) after which a user is automatically redirected to the return URL." }, "autoredirect_from_status_page": { "type": "boolean", "description": "Whether to automatically redirect from the status page." }, "status_for_manual_redirection": { "type": "string", "description": "Payment status for which a button redirecting a user to the return URL is displayed. Can be `none`, `successful`, `successful_or_canсeled`, or `any`.", "enum": [ "none", "successful", "successful_or_canceled", "any" ] }, "manual_redirection_action": { "type": "string", "description": "Pay Station behavior triggered by the user clicking the close button or the **Back to the Game** button. Can be `redirect` (by default) and `postmessage`. If set to `redirect`, a user is redirected to the URL passed in the token or specified in Publisher Account. If set to `postmessage`, a user is not redirected to other pages. Clicking the close icon initiates sending the `close` event, and clicking the **Back to the Game** button — the `return` event.", "enum": [ "redirect", "postmessage" ] }, "redirect_button_caption": { "type": "string", "description": "Text on the button for manual redirection." } } }, "currency": { "type": "string", "description": "Preferred payment currency. Three-letter currency code per [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)." }, "mode": { "type": "string", "description": "Set to `sandbox` to test out the payment process. In this case, use *https://sandbox-secure.xsolla.com* to access the test payment UI." }, "payment_method": { "type": "integer", "description": "Payment method ID." }, "payment_widget": { "type": "string", "description": "Payment widget. Can be `paybycash` or `giftcard`. If the parameter is set, the user is redirected to the Pay by Cash or Gift Cards widget, respectively.", "enum": [ "paybycash", "giftcard" ] }, "ui": { "type": "object", "description": "Interface settings.", "properties": { "theme": { "type": "string", "description": "Payment UI theme. Can be `default` or `default_dark`.", "enum": [ "default", "default_dark" ] }, "size": { "type": "string", "description": "Payment UI size. Can be:\n - [small](https://livedemo.xsolla.com/developers/small/): the least possible size of the payment UI. Use this value when the window size is strictly limited (dimensions: 620 x 630)\n - [medium](https://livedemo.xsolla.com/developers/medium/): recommended size. Use this value to display the payment UI in a lightbox (dimensions: 740 x 760)\n - [large](https://livedemo.xsolla.com/developers/large/): the optimal size for displaying the payment UI in a new window or tab (dimensions: 820 x 840)\n", "enum": [ "small", "medium", "large" ] }, "version": { "type": "string", "description": "Device type. Can be `desktop` (default) or `mobile`.", "enum": [ "desktop", "mobile" ] }, "desktop": { "type": "object", "description": "Interface settings for the desktop version.", "properties": { "header": { "type": "object", "description": "Header settings.", "properties": { "is_visible": { "type": "boolean", "description": "Whether to show the header in the payment UI." }, "visible_logo": { "type": "boolean", "description": "If `true`, the header will show your logo (first provide the image to your Customer Success Manager)." }, "visible_name": { "type": "boolean", "description": "Whether to show the project name in the header." }, "visible_purchase": { "type": "boolean", "description": "Whether to show the purchase description (`purchase.description.value`) in the header. `true` by default." }, "type": { "type": "string", "description": "How to show the header. Can be `compact` (hides project name and user ID) or `normal` (default).", "enum": [ "compact", "normal" ] }, "close_button": { "type": "boolean", "description": "Whether to show a Close button in Pay Station desktop. The button closes Pay Station and redirects the user to the URL specified in the `settings.return_url` parameter. `false` by default." } } }, "subscription_list": { "type": "object", "description": "Settings for the list of subscription plans.", "properties": { "layout": { "type": "string", "description": "List template. Can be `list` (default) or `grid`.", "enum": [ "list", "grid" ] }, "description": { "type": "string", "description": "Any text to show above the list of available subscription plans in the payment UI." }, "display_local_price": { "type": "boolean", "description": "If `true`, and if the user’s local currency is different from the one set for the subscription plan, the user will be able to see both prices: one in the local and one in the basic currency.\n" } } }, "virtual_item_list": { "type": "object", "description": "Settings for the list of virtual items.", "properties": { "layout": { "type": "string", "description": "List template. Can be `list` (default) or `grid`.", "enum": [ "list", "grid" ] }, "button_with_price": { "type": "boolean", "description": "If `true`, the price will be shown on the button. If `false`, the price will be shown on the left of the button. `false` by default." }, "view": { "type": "string", "description": "Display virtual item groups as a vertical/horizontal menu. Can be `horizontal_navigation` or `vertical_navigation` (default).", "enum": [ "horizontal_navigation", "vertical_navigation" ] } } }, "virtual_currency_list": { "type": "object", "description": "Settings for the list of virtual currencies.", "properties": { "description": { "type": "string", "description": "Any text to show above the list of virtual currencies." }, "button_with_price": { "type": "boolean", "description": "If `true`, the price will be shown on the button. If `false`, the price will be shown on the left of the button. `false` by default." } } } } }, "header": { "type": "object", "properties": { "visible_virtual_currency_balance": { "type": "boolean", "description": "Whether or not this element can be hidden on Payment UI. `true` by default." } } }, "mobile": { "type": "object", "properties": { "mode": { "type": "string", "description": "A user can only pay using their saved payment methods. Can be `saved_accounts`.", "enum": [ "saved_accounts" ] }, "header": { "type": "object", "properties": { "close_button": { "type": "boolean", "description": "Whether to show a Close button in Pay Station mobile. The button closes Pay Station and redirects the user to the URL specified in the `settings.return_url` parameter. `false` by default." } } }, "footer": { "type": "object", "properties": { "is_visible": { "type": "boolean", "description": "Whether to hide the footer in the mobile version of the payment UI." } } } } }, "license_url": { "type": "string", "description": "Link to the EULA." }, "components": { "type": "object", "description": "Menu settings.", "properties": { "virtual_items": { "type": "object", "description": "Virtual items submenu settings.", "properties": { "order": { "type": "integer", "description": "Position of the submenu in the menu." }, "hidden": { "type": "boolean", "description": "Whether to show the submenu." }, "selected_group": { "type": "string", "description": "Group to show after opening the virtual items tab." }, "selected_item": { "type": "string", "description": "Item to show after opening the virtual items tab (item SKU)." } } }, "virtual_currency": { "type": "object", "description": "Virtual currency submenu settings.", "properties": { "custom_amount": { "type": "boolean", "description": "Whether the user can enter an arbitrary quantity of the virtual currency in the payment UI." }, "order": { "type": "integer", "description": "Position of the submenu in the menu." }, "hidden": { "type": "boolean", "description": "Whether to show the submenu." } } }, "subscriptions": { "type": "object", "description": "Subscription plans submenu settings.", "properties": { "order": { "type": "integer", "description": "Position of the submenu in the menu." }, "hidden": { "type": "boolean", "description": "Whether to show the submenu." } } } } }, "mode": { "type": "string", "description": "Interface mode in Pay Station. Can be `user_account` only. The header contains only the account navigation menu, and the user cannot select a product or make a payment. This mode is only available on the desktop.\n" }, "is_prevent_external_link_open": { "type": "boolean", "description": "Whether or not redirecting links to an external resource is disabled. `true` by default. When clicking an external link, the `external-link-open` event is sent via the `postMessage` mechanism. The address for the redirected link is passed in the `url` parameter." }, "user_account": { "type": "object", "description": "User account details.", "properties": { "info": { "allOf": [ { "description": "Page **My account**." }, { "type": "object", "properties": { "order": { "type": "integer", "description": "Position of the submenu in the menu." }, "enable": { "type": "boolean", "description": "Whether to show the submenu. `false` by default." } } } ] }, "history": { "allOf": [ { "description": "**History** submenu." }, { "type": "object", "properties": { "order": { "type": "integer", "description": "Position of the submenu in the menu." }, "enable": { "type": "boolean", "description": "Whether to show the submenu. `false` by default." } } } ] }, "payment_accounts": { "allOf": [ { "description": "**My payment accounts** submenu." }, { "type": "object", "properties": { "order": { "type": "integer", "description": "Position of the submenu in the menu." }, "enable": { "type": "boolean", "description": "Whether to show the submenu. `false` by default." } } } ] }, "subscriptions": { "allOf": [ { "description": "**Manage subscriptions** submenu." }, { "type": "object", "properties": { "order": { "type": "integer", "description": "Position of the submenu in the menu." }, "enable": { "type": "boolean", "description": "Whether to show the submenu. `false` by default." } } } ] } } } } } } }, "purchase": { "type": "object", "description": "Object containing purchase details.", "properties": { "checkout": { "type": "object", "description": "Object containing checkout details.", "properties": { "currency": { "type": "string", "description": "Currency of the purchase. Three-letter currency code per [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)." }, "amount": { "type": "integer", "format": "float", "description": "Purchase amount." } } }, "subscription": { "type": "object", "description": "Subscription data.", "properties": { "plan_id": { "type": "string", "description": "External ID of the subscription plan. Can be found in the **Subscriptions > Subscription plans** section of Publisher Account." }, "operation": { "type": "string", "description": "The type of operation applied to the user’s subscription plan. To change the subscription plan, pass the `change_plan` value. You need to specify the new plan ID in the `purchase.subscription.plan_id` parameter." }, "product_id": { "type": "string", "description": "Product ID." }, "currency": { "type": "string", "description": "Currency of the subscription plan to use in all calculations." }, "available_plans": { "type": "array", "items": { "type": "string" }, "description": "Subscription plans to show in the payment UI." }, "trial_days": { "type": "integer", "description": "Trial period in days." }, "gift": { "type": "object", "description": "Gifted subscription details.", "required": [ "recipient", "email" ], "properties": { "recipient": { "type": "string", "description": "ID of the recipient." }, "email": { "type": "string", "description": "Recipient email." }, "anonymous": { "type": "boolean", "description": "Whether to hide the gifter name. If `true`, the sender's name is hidden in the email notification. Defaults to `false`." }, "message": { "type": "string", "description": "Message for the recipient." }, "redirect_url": { "type": "string", "description": "Provide a link here to a page with additional information about the gifted subscription or to the account creation page. The gift recipient can navigate to this page from the subscription gift email notification." } } } } } } }, "custom_parameters": { "type": "object", "description": "You can pass additional parameters in the token in the `custom_parameters` object to configure anti-fraud filters. The recommended parameters are shown in the drop-down list. [See Pay Station documentation](https://developers.xsolla.com/doc/pay-station/features/antifraud/).\n", "properties": { "registration_date": { "type": "string", "description": "Account creation date per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." }, "total_hours": { "type": "integer", "description": "Total number of in-game hours." }, "total_characters": { "type": "integer", "description": "Number of in-game characters." }, "social_networks_added": { "type": "boolean", "description": "Whether the player has connected social media profiles." }, "profile_image_added": { "type": "boolean", "description": "Whether the player has uploaded a profile image." }, "active_date": { "type": "string", "description": "Last seen date per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." }, "total_friends": { "type": "integer", "description": "Number of friends." }, "additional_verification": { "type": "boolean", "description": "Whether the player uses account verification procedures." }, "win_rate": { "type": "integer", "description": "Win rate." }, "last_change_password_date": { "type": "string", "description": "Last password change date per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." }, "chat_activity": { "type": "boolean", "description": "Whether the player uses the chat function." }, "forum_activity": { "type": "boolean", "description": "Whether the player uses the forum function." }, "total_bans": { "type": "integer", "description": "Number of times the player was banned in the chat/forum." }, "profile_completed": { "type": "boolean", "description": "Whether the player added additional information to their profile." }, "notifications_enabled": { "type": "boolean", "description": "Whether the player enabled notifications." }, "user_level": { "type": "integer", "description": "Player’s level, reputation, or rank." }, "karma_points": { "type": "integer", "description": "Player’s karma." }, "total_sum": { "type": "integer", "format": "float", "description": "Total amount of payments." }, "non_premium_currency": { "type": "integer", "format": "float", "description": "Amount of non-premium currency." }, "total_game_events": { "type": "integer", "description": "Number of in-game events the player took part in." }, "total_gifts": { "type": "integer", "description": "Number of in-game gifts the player has sent/received." }, "tutorial_completed": { "type": "boolean", "description": "Whether the player has completed the game’s tutorial." }, "completed_tasks": { "type": "integer", "description": "Number of tasks/objectives completed." }, "items_used": { "type": "boolean", "description": "Whether the player uses purchased in-game items." }, "pvp_activity": { "type": "boolean", "description": "Whether the player takes part in PvP battles." }, "total_clans": { "type": "integer", "description": "Number of clans the player is a member of." }, "unlocked_achievements": { "type": "integer", "description": "Number of achievements unlocked." }, "total_inventory_value": { "type": "integer", "format": "float", "description": "Total inventory value (in-game currency)." }, "character_customized": { "type": "boolean", "description": "Whether the player has customized their character." }, "session_time": { "type": "string", "description": "Average session time per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." } } } }, "example": { "purchase": { "checkout": { "currency": "USD", "amount": 10 }, "subscription": { "gift": { "recipient": "test_recipient_v1", "email": "recipient_email@email.com" } } }, "settings": { "currency": "USD", "language": "en", "project_id": 16184, "ui": { "components": { "virtual_currency": { "custom_amount": true } }, "desktop": { "virtual_item_list": { "button_with_price": true, "layout": "list" } }, "size": "medium" } }, "user": { "country": { "allow_modify": true, "value": "US" }, "age": 19, "email": { "value": "john.smith@mail.com" }, "id": { "value": "user_2" }, "name": { "value": "John Smith" } } } }, "LocalizedStringPairs": { "type": "object", "properties": { "en": { "type": "string", "description": "English." }, "ru": { "type": "string", "description": "Russian." }, "cs": { "type": "string", "description": "Czech." }, "ar": { "type": "string", "description": "Arabic." }, "bg": { "type": "string", "description": "Bulgarian." }, "cn": { "type": "string", "description": "Chinese (Simplified)." }, "tw": { "type": "string", "description": "Chinese (Traditional)." }, "fr": { "type": "string", "description": "French." }, "de": { "type": "string", "description": "German." }, "he": { "type": "string", "description": "Hebrew." }, "it": { "type": "string", "description": "Italian." }, "ko": { "type": "string", "description": "Korean." }, "pl": { "type": "string", "description": "Polish." }, "pt": { "type": "string", "description": "Portuguese." }, "ro": { "type": "string", "description": "Romanian." }, "es": { "type": "string", "description": "Spanish." }, "th": { "type": "string", "description": "Thai." }, "tr": { "type": "string", "description": "Turkish." }, "vi": { "type": "string", "description": "Vietnamese." }, "ja": { "type": "string", "description": "Japanese." } } }, "CreatePromotion": { "type": "object", "properties": { "technical_name": { "type": "string", "description": "Technical name of the promotion." }, "project_id": { "type": "integer", "description": "Project ID." }, "label": { "allOf": [ { "$ref": "#/components/schemas/LocalizedStringPairs" }, { "description": "Array of localized labels to show in the payment UI." } ] }, "name": { "allOf": [ { "$ref": "#/components/schemas/LocalizedStringPairs" }, { "description": "Array of localized promotion names." } ] }, "description": { "allOf": [ { "$ref": "#/components/schemas/LocalizedStringPairs" }, { "description": "Array of localized promotion descriptions." } ] } } }, "GetPromotion": { "allOf": [ { "$ref": "#/components/schemas/CreatePromotion" }, { "type": "object", "properties": { "id": { "type": "integer" }, "read_only": { "type": "boolean" }, "show_banner": { "type": "boolean" }, "enabled": { "type": "boolean" } } } ] }, "PromotionReward": { "type": "object", "properties": { "purchase": { "description": "Set the reward for the whole purchase.", "type": "object", "properties": { "discount_percent": { "type": "number", "format": "float", "description": "Discount percentage." } } }, "package": { "description": "Set the reward for a virtual currency package.", "type": "object", "properties": { "bonus_percent": { "type": "number", "format": "float", "description": "Reward as a percentage of the package amount." }, "bonus_amount": { "type": "number", "format": "float", "description": "Reward as an absolute quantity of the virtual currency." } } }, "item": { "description": "Set the reward for specific virtual items.", "type": "object", "properties": { "discount": { "description": "Discounts for specific virtual items.", "type": "array", "items": { "type": "object", "properties": { "localized_name": { "type": "string", "description": "Plan name in default language (en), replicates name.en value." }, "sku": { "type": "string", "description": "Item SKU." }, "discount_percent": { "type": "number", "format": "float", "description": "Discount percentage." }, "max_amount": { "type": "number", "format": "integer", "description": "Maximum number of items to apply the promotion to." } } } }, "bonus": { "description": "Extra virtual items given as a bonus.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "localized_name": { "type": "string", "description": "Plan name in default language (en), replicates name.en value." }, "sku": { "type": "string", "description": "Item SKU." }, "quantity": { "type": "integer", "description": "Number of virtual items given as a bonus." } } } } } }, "subscription": { "type": "object", "description": "Sets the reward for a subscription.", "properties": { "trial_days": { "type": "integer", "description": "Trial period in days." } } } } }, "PromotionSubject": { "type": "object", "properties": { "purchase": { "type": "boolean", "description": "Whether the promotion applies to the whole purchase." }, "items": { "description": "Array of virtual items that the promotion applies to.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "localized_name": { "type": "string", "description": "Plan name in default language (en), replicates name.en value." }, "sku": { "type": "string", "description": "Item SKU." } } } }, "packages": { "type": "array", "nullable": true, "items": { "type": "object" }, "description": "Array of virtual currency packages that the promotion applies to." }, "subscriptions": { "type": "object", "nullable": true, "description": "Subscription plans or products that the promotion applies to.", "properties": { "plans": { "type": "array", "items": { "type": "string", "description": "Array of subscription plans that the promotion applies to." } }, "products": { "type": "array", "items": { "type": "string", "description": "Array of subscription-based products that the promotion applies to." } }, "max_charges_count": { "type": "integer", "description": "Maximum number of billings that the promotion applies to." } } }, "digital_contents": { "type": "object", "nullable": true } } }, "CouponAttribute": { "type": "object", "properties": { "key": { "type": "string", "description": "Key of the user attribute." }, "name": { "allOf": [ { "$ref": "#/components/schemas/LocalizedStringPairs" }, { "description": "Localized attribute names." } ] }, "type": { "type": "string", "description": "Key type.", "enum": [ "int", "string", "enum", "date" ] }, "list_of_values": { "type": "array", "items": { "type": "object" }, "description": "Array of possible values for enum type." }, "skip_condition_on_nonexistent_key": { "type": "boolean", "description": "Whether to skip the condition if key doesn't exist." }, "visible": { "type": "boolean" } } }, "Coupon": { "type": "object", "properties": { "campaign_code": { "type": "string" }, "coupon_code": { "type": "string" }, "coupon_id": { "type": "integer" }, "expiration_date": { "type": "string" }, "is_active": { "type": "boolean" }, "project_id": { "type": "integer" }, "redeems_count_for_user": { "type": "integer" }, "redeems_count_remain": { "type": "integer" }, "subscription_coupon": { "type": "string", "nullable": true }, "virtual_currency_amount": { "type": "integer" }, "virtual_items": { "type": "array", "items": { "type": "string" } } } }, "PromotionPaymentSystem": { "type": "object", "properties": { "payment_systems": { "description": "Payment systems.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Payment system ID." }, "name": { "type": "string", "description": "Payment system name." } } } } } }, "PromotionPeriod": { "type": "object", "properties": { "periods": { "description": "Date/time ranges.", "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "format": "datetime", "description": "Period start." }, "offset": { "type": "string", "description": "Number of the element from which the list is generated (the count starts from 0)." }, "to": { "type": "string", "format": "datetime", "description": "Period end." } } } } } }, "Campaign": { "type": "object", "properties": { "campaign_code": { "type": "string", "description": "Campaign name." }, "project_id": { "type": "integer", "description": "Project ID." }, "campaign_names": { "allOf": [ { "$ref": "#/components/schemas/LocalizedStringPairs" }, { "description": "Object containing localized campaign names." } ] }, "expiration_date": { "type": "string", "format": "datetime", "description": "Campaign expiration date in the `YYYY-MM-DD’T’HH:MM:SS` format per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." }, "virtual_currency_amount": { "type": "number", "format": "float", "description": "Virtual currency amount in a reward." }, "virtual_items": { "type": "object", "description": "Array of virtual items parameters in a reward.", "required": [ "sku", "quantity" ], "properties": { "sku": { "type": "string", "description": "Virtual item SKU." }, "quantity": { "type": "integer", "description": "Virtual items quantity." } } }, "subscription_coupon": { "type": "object", "description": "Object containing subscription parameters in a reward.", "required": [ "plan_id", "product_id", "trial_period" ], "properties": { "plan_id": { "type": "integer", "description": "Subscription plan ID." }, "product_id": { "type": "integer", "description": "Subscription product ID." }, "trial_period": { "type": "integer", "description": "Trial period duration in days." } } }, "redeems_count": { "type": "integer", "description": "Maximum number of coupon redeems. If `null` is passed, the redeems number is unlimited." }, "redeems_count_for_user": { "type": "integer", "description": "Maximum number of coupon redeems per user. If `null` is passed, the redeems number is unlimited." }, "campaign_redeems_count_for_user": { "type": "integer", "description": "Maximum number of coupon redeems per user within a campaign. If `null` is passed, the redeems number is unlimited." } } }, "SubscriptionsPlan": { "type": "object", "properties": { "project_id": { "type": "integer", "description": "Project ID." }, "name": { "allOf": [ { "$ref": "#/components/schemas/LocalizedStringPairs" }, { "description": "Plan name. Value consists of pairs \"localization\":\"plan name\"." } ] }, "charge": { "type": "object", "description": "Billing details.", "required": [ "period" ], "properties": { "period": { "type": "object", "description": "Billing period.", "required": [ "value", "type" ], "properties": { "value": { "type": "integer", "description": "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`" }, "type": { "type": "string", "description": "Time unit. Can be `day`, `month` or `lifetime`.", "enum": [ "day", "month", "lifetime" ] } } }, "amount": { "type": "number", "format": "float", "description": "Billing amount." }, "currency": { "type": "string", "description": "Currency of the purchase. Three-letter currency code per [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)." }, "prices": { "type": "array", "description": "List of prices in different currencies.", "items": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "number", "format": "float", "description": "Billing amount." }, "currency": { "type": "string", "description": "Currency of the purchase. Three-letter currency code per [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)." }, "setup_fee": { "type": "number", "format": "float", "description": "One-time setup fee charged as part of the first invoice." } } } } } }, "id": { "type": "integer", "description": "Subscription plan ID." }, "external_id": { "type": "string", "description": "Plan external ID (32 characters)." }, "description": { "allOf": [ { "$ref": "#/components/schemas/LocalizedStringPairs" }, { "description": "Plan description. Value consists of pairs \"localization\":\"plan description\"." } ] }, "group_id": { "type": "string", "description": "Group ID the plan is linked to.", "nullable": true }, "expiration": { "type": "object", "description": "Subscription expiration details.", "required": [ "value", "type" ], "properties": { "value": { "type": "integer", "description": "Validity time.", "nullable": true }, "type": { "type": "string", "description": "Time unit. Can be `day` or `month`.", "enum": [ "day", "month" ] } } }, "trial": { "type": "object", "description": "Trial period details.", "required": [ "value", "type" ], "properties": { "value": { "type": "integer", "description": "Number of time units." }, "type": { "type": "string", "description": "Time unit. Can be `day`.", "enum": [ "day" ] } } }, "grace_period": { "type": "object", "description": "Grace period details.", "required": [ "value", "type" ], "properties": { "value": { "type": "integer", "description": "Number of time units." }, "type": { "type": "string", "description": "Time unit. Can be `day`.", "enum": [ "day" ] } } }, "billing_retry": { "type": "object", "description": "Billing retry details.", "required": [ "value" ], "properties": { "value": { "type": "integer", "description": "Number of billing retries." } } }, "refund_period": { "type": "integer", "description": "Period of time that user can refund the payment for a subscription plan (in days).", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Plan tags." }, "status": { "type": "object", "properties": { "value": { "type": "string", "description": "Subscription plan status.", "enum": [ "active", "disabled" ] } } } } }, "SubscriptionsPlanRequest": { "type": "object", "properties": { "name": { "allOf": [ { "$ref": "#/components/schemas/LocalizedStringPairs" }, { "description": "Plan name. Value consists of pairs \"localization\":\"plan name\"." } ] }, "charge": { "type": "object", "description": "Billing details.", "required": [ "period" ], "properties": { "period": { "type": "object", "description": "Billing period.", "required": [ "value", "type" ], "properties": { "value": { "type": "integer", "description": "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`" }, "type": { "type": "string", "description": "Time unit. Can be `day`, `month` or `lifetime`.", "enum": [ "day", "month", "lifetime" ] } } }, "amount": { "type": "number", "format": "float", "description": "Billing amount." }, "currency": { "type": "string", "description": "Currency of the purchase. Three-letter currency code per [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)." }, "prices": { "type": "array", "description": "List of prices in different currencies.", "items": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "number", "format": "float", "description": "Billing amount." }, "currency": { "type": "string", "description": "Currency of the purchase. Three-letter currency code per [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)." }, "setup_fee": { "type": "number", "format": "float", "description": "One-time setup fee charged as part of the first invoice." } } } } } }, "external_id": { "type": "string", "description": "Plan external ID (32 characters)." }, "description": { "allOf": [ { "$ref": "#/components/schemas/LocalizedStringPairs" }, { "description": "Plan description. Value consists of pairs \"localization\":\"plan description\"." } ] }, "group_id": { "type": "string", "description": "Group ID the plan is linked to." }, "expiration": { "type": "object", "description": "Subscription expiration details.", "required": [ "value", "type" ], "properties": { "value": { "type": "integer", "description": "Validity time.", "nullable": true }, "type": { "type": "string", "description": "Time unit. Can be `day` or `month`.", "enum": [ "day", "month" ] } } }, "trial": { "type": "object", "description": "Trial period details. If this parameter is not passed, the default values (0 days) are used.", "required": [ "value", "type" ], "properties": { "value": { "type": "integer", "description": "Number of time units." }, "type": { "type": "string", "description": "Time unit. Can be `day`.", "enum": [ "day" ] } } }, "grace_period": { "type": "object", "description": "Grace period details.", "required": [ "value", "type" ], "properties": { "value": { "type": "integer", "description": "Number of time units." }, "type": { "type": "string", "description": "Time unit. Can be `day`.", "enum": [ "day" ] } } }, "billing_retry": { "type": "object", "description": "Billing retry details.", "required": [ "value" ], "properties": { "value": { "type": "integer", "description": "Number of billing retries." } } }, "refund_period": { "type": "integer", "description": "Period of time that user can refund the payment for a subscription plan (in days).", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Plan tags." }, "status": { "type": "object", "properties": { "value": { "type": "string", "description": "Subscription plan status.", "enum": [ "active", "disabled" ] } } } } }, "SubscriptionsProduct": { "type": "object", "properties": { "name": { "type": "string", "description": "Product name." }, "group_id": { "type": "string", "description": "Group ID the product is linked to." }, "description": { "allOf": [ { "$ref": "#/components/schemas/LocalizedStringPairs" }, { "description": "Localized item descriptions." } ] } }, "nullable": true }, "SubscriptionsProductWithId": { "allOf": [ { "type": "object", "properties": { "id": { "type": "integer", "description": "Product ID the plans are linked to.", "nullable": true } } }, { "$ref": "#/components/schemas/SubscriptionsProduct" } ] }, "SubscriptionResponse": { "type": "object", "properties": { "id": { "type": "integer", "description": "Subscription ID" }, "plan": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionsPlan" } ] }, "user": { "allOf": [ { "$ref": "#/components/schemas/User" } ] }, "product": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionsProductWithId" } ] }, "charge_amount": { "type": "number", "format": "float", "description": "Billing amount." }, "currency": { "type": "string", "description": "Currency of the purchase. Three-letter currency code per ISO 4217." }, "date_create": { "type": "string", "format": "datetime", "description": "Subscription creation date in the `YYYY-MM-DD’T’HH:MM:SS` format per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." }, "date_end": { "type": "string", "format": "datetime", "description": "Subscription end date in the `YYYY-MM-DD’T’HH:MM:SS` format per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." }, "date_last_charge": { "type": "string", "format": "datetime", "description": "Last subscription charge date in the `YYYY-MM-DD’T’HH:MM:SS` format per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).", "nullable": true }, "date_next_charge": { "type": "string", "format": "datetime", "description": "Next subscription charge date in the `YYYY-MM-DD’T’HH:MM:SS` format per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).", "nullable": true }, "status": { "type": "string", "enum": [ "new", "active", "canceled", "non_renewing", "freeze" ], "description": "Status" }, "comment": { "type": "string", "description": "Reason for changing subscription status" } } }, "Subscription": { "type": "object", "properties": { "status": { "type": "string", "description": "Status.", "enum": [ "active", "canceled", "non_renewing" ] }, "cancel_subscription_payment": { "type": "boolean", "description": "Setting to `true` will refund the last payment made for this subscription. **Only works together with setting the status to `canceled`**." }, "timeshift": { "type": "object", "description": "Billing postponement.", "properties": { "type": { "type": "string", "description": "Billing time unit. Can be `day` or `month`.", "enum": [ "day", "month" ] }, "value": { "type": "string", "description": "Number of time units to postpone the billing by. 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`" } } }, "xsolla_network": { "type": "object", "properties": { "collaborator_id": { "type": "string", "description": "Collaborator ID — [influencer](https://developers.xsolla.com/doc/partner-network/#guides_network_glossary_influencer) or [affiliate network](https://developers.xsolla.com/doc/partner-network/#guides_network_glossary_affiliate_network) identifier. You can find it in your **Publisher Account > Partner Network > Influencers** section." } } } } }, "User": { "type": "object", "properties": { "id": { "type": "string", "description": "User ID" }, "name": { "type": "string", "description": "User name" } } }, "ListManagementSubscriptionsResponse": { "required": [ "has_more" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ManagementSubscriptionResponse2" }, "default": [] }, "has_more": { "type": "boolean", "example": "false" } }, "type": "object" }, "ManagementSubscriptionResponse": { "required": [ "id", "plan_name", "plan_description", "status", "is_in_trial", "date_create", "charge", "period", "is_renew_possible", "is_change_to_non_renew_possible", "is_change_plan_allowed" ], "properties": { "id": { "type": "integer", "example": "12345" }, "plan_name": { "type": "string", "example": "Localized plan name" }, "plan_description": { "type": "string", "example": "Localized plan description" }, "product_name": { "type": "string", "example": "Product name", "nullable": true }, "product_description": { "type": "string", "example": "Localized product description", "nullable": true }, "status": { "type": "string", "example": "active" }, "is_in_trial": { "type": "boolean", "example": "false" }, "trial_period": { "type": "integer", "example": "0", "nullable": true }, "date_create": { "type": "string", "format": "date-time", "example": "2031-04-11T13:51:02+03:00" }, "date_next_charge": { "type": "string", "format": "date-time", "example": "2031-04-11T13:51:02+03:00", "nullable": true }, "date_last_charge": { "type": "string", "format": "date-time", "example": "2031-04-11T13:51:02+03:00", "nullable": true }, "date_end": { "type": "string", "format": "date-time", "example": "2031-04-11T13:51:02+03:00", "nullable": true }, "charge": { "$ref": "#/components/schemas/Charge" }, "period": { "$ref": "#/components/schemas/Period" }, "is_renew_possible": { "type": "boolean", "example": "true" }, "is_change_to_non_renew_possible": { "type": "boolean", "example": "true" }, "is_change_plan_allowed": { "type": "boolean", "example": "false" }, "payment_account": { "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/PaymentRecurrentAccountResponse2" } ] }, "last_successful_charge": { "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/LastSuccessfulCharge" } ] } }, "type": "object" }, "PaymentRecurrentAccountResponse": { "required": [ "id", "type" ], "properties": { "id": { "type": "integer", "example": "123" }, "type": { "type": "string", "example": "card" }, "name": { "type": "string", "example": "** 7398", "nullable": true }, "card_expiry_date": { "properties": { "year": { "type": "string", "example": "2023" }, "month": { "type": "string", "example": "09" } }, "type": "object", "nullable": true }, "ps_name": { "type": "string", "example": "Mastercard", "nullable": true }, "switch_icon_name": { "type": "string", "example": "mastercard.svg", "nullable": true } }, "type": "object" }, "PayStationLinkResponse": { "required": [ "link_to_ps" ], "properties": { "link_to_ps": { "type": "string", "example": "https://secure.xsolla.com/paystation2/?access_token=" } }, "type": "object" }, "ListPlansResponse": { "required": [ "has_more" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PlanResponse" }, "default": [] }, "has_more": { "type": "boolean", "example": "false" } }, "type": "object" }, "ChangePlanPaymentDetailsResponse": { "required": [ "plan_id", "plan_external_id", "plan_type", "plan_name", "plan_description", "period", "charge", "promotion", "payment_details" ], "properties": { "plan_id": { "type": "integer", "example": "54321" }, "plan_external_id": { "type": "string", "example": "PlanExternalId" }, "plan_group_id": { "type": "string", "example": "TestGroupId", "nullable": true }, "plan_type": { "type": "string", "example": "all" }, "plan_name": { "type": "string", "example": "Localized plan name" }, "plan_description": { "type": "string", "example": "Localized plan description" }, "plan_start_date": { "type": "string", "format": "date-time", "example": "2021-04-11T13:51:02+03:00", "nullable": true }, "plan_end_date": { "type": "string", "format": "date-time", "example": "2031-04-11T13:51:02+03:00", "nullable": true }, "trial_period": { "type": "integer", "example": "7", "nullable": true }, "period": { "$ref": "#/components/schemas/Period2" }, "charge": { "$ref": "#/components/schemas/Charge2" }, "promotion": { "$ref": "#/components/schemas/Promotion" }, "payment_details": { "$ref": "#/components/schemas/PaymentDetails" } }, "type": "object" }, "ProjectManageSubscriptionSettingsResponse": { "required": [ "recurrent_cancel_possible", "allow_change_package" ], "properties": { "recurrent_cancel_possible": { "type": "boolean", "example": "true" }, "allow_change_package": { "type": "boolean", "example": "true" } }, "type": "object" }, "BillingAccountsListResponse": { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BillingAccountResponse" }, "default": [] } }, "type": "object" }, "ManagementSubscriptionResponse2": { "required": [ "id", "plan_name", "plan_description", "status", "is_in_trial", "date_create", "charge", "period" ], "properties": { "id": { "type": "integer", "example": "12345" }, "plan_name": { "type": "string", "example": "Localized plan name" }, "plan_description": { "type": "string", "example": "Localized plan description" }, "product_name": { "type": "string", "example": "Product name", "nullable": true }, "product_description": { "type": "string", "example": "Localized product description", "nullable": true }, "status": { "type": "string", "example": "active" }, "is_in_trial": { "type": "boolean", "example": "false" }, "trial_period": { "type": "integer", "example": "0", "nullable": true }, "date_create": { "type": "string", "format": "date-time", "example": "2031-04-11T13:51:02+03:00" }, "date_next_charge": { "type": "string", "format": "date-time", "example": "2031-04-11T13:51:02+03:00", "nullable": true }, "date_last_charge": { "type": "string", "format": "date-time", "example": "2031-04-11T13:51:02+03:00", "nullable": true }, "charge": { "$ref": "#/components/schemas/Charge3" }, "period": { "$ref": "#/components/schemas/Period3" }, "payment_account": { "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/PaymentRecurrentAccountResponse3" } ] } }, "type": "object" }, "Charge": { "required": [ "amount", "currency" ], "properties": { "amount": { "type": "number", "format": "float", "example": "4.99" }, "amount_with_promotion": { "type": "number", "format": "float", "default": null, "example": "3.99", "nullable": true }, "currency": { "type": "string", "example": "USD" } }, "type": "object" }, "Period": { "properties": { "value": { "type": "integer", "default": null, "example": "1", "nullable": true }, "unit": { "type": "string", "default": null, "example": "month", "nullable": true } }, "type": "object" }, "PaymentRecurrentAccountResponse2": { "required": [ "id", "type" ], "properties": { "id": { "type": "integer", "example": "123" }, "type": { "type": "string", "example": "card" }, "name": { "type": "string", "example": "** 7398", "nullable": true }, "card_expiry_date": { "properties": { "year": { "type": "string", "example": "2023" }, "month": { "type": "string", "example": "09" } }, "type": "object", "nullable": true }, "ps_name": { "type": "string", "example": "Mastercard", "nullable": true }, "switch_icon_name": { "type": "string", "example": "mastercard.svg", "nullable": true } }, "type": "object" }, "LastSuccessfulCharge": { "required": [ "date" ], "properties": { "date": { "type": "string", "format": "date-time", "example": "2031-04-11T13:51:02+03:00" }, "amount": { "type": "number", "format": "float", "example": "3.99", "nullable": true }, "currency": { "type": "string", "example": "USD", "nullable": true } }, "type": "object" }, "PlanResponse": { "required": [ "plan_id", "plan_external_id", "plan_type", "plan_name", "plan_description", "period", "charge", "promotion" ], "properties": { "plan_id": { "type": "integer", "example": "54321" }, "plan_external_id": { "type": "string", "example": "PlanExternalId" }, "plan_group_id": { "type": "string", "example": "TestGroupId", "nullable": true }, "plan_type": { "type": "string", "example": "all" }, "plan_name": { "type": "string", "example": "Localized plan name" }, "plan_description": { "type": "string", "example": "Localized plan description" }, "plan_start_date": { "type": "string", "format": "date-time", "example": "2021-04-11T13:51:02+03:00", "nullable": true }, "plan_end_date": { "type": "string", "format": "date-time", "example": "2031-04-11T13:51:02+03:00", "nullable": true }, "trial_period": { "type": "integer", "example": "7", "nullable": true }, "period": { "$ref": "#/components/schemas/Period4" }, "charge": { "$ref": "#/components/schemas/Charge4" }, "promotion": { "$ref": "#/components/schemas/Promotion2" } }, "type": "object" }, "Period2": { "properties": { "value": { "type": "integer", "default": null, "example": "1", "nullable": true }, "unit": { "type": "string", "default": null, "example": "month", "nullable": true } }, "type": "object" }, "Charge2": { "required": [ "amount", "currency" ], "properties": { "amount": { "type": "number", "format": "float", "example": "4.99" }, "setup_fee": { "type": "number", "format": "float", "example": "0.99", "nullable": true }, "currency": { "type": "string", "example": "USD" } }, "type": "object" }, "Promotion": { "properties": { "promotion_charge_amount": { "type": "number", "format": "float", "default": null, "example": "3.99", "nullable": true }, "promotion_remaining_charges": { "type": "integer", "default": null, "example": "3", "nullable": true } }, "type": "object" }, "PaymentDetails": { "properties": { "unused": { "default": null, "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/Unused" } ] }, "surcharge": { "default": null, "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/Surcharge" } ] } }, "type": "object" }, "BillingAccountResponse": { "required": [ "id" ], "properties": { "id": { "type": "integer", "example": "12345" }, "name": { "type": "string", "example": "PP_saved_account", "nullable": true }, "payment_system": { "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/PaymentSystemResponse" } ] }, "type": { "type": "string", "example": "paypal", "nullable": true } }, "type": "object" }, "Charge3": { "required": [ "amount", "currency" ], "properties": { "amount": { "type": "number", "format": "float", "example": "4.99" }, "amount_with_promotion": { "type": "number", "format": "float", "default": null, "example": "3.99", "nullable": true }, "currency": { "type": "string", "example": "USD" } }, "type": "object" }, "Period3": { "properties": { "value": { "type": "integer", "default": null, "example": "1", "nullable": true }, "unit": { "type": "string", "default": null, "example": "month", "nullable": true } }, "type": "object" }, "PaymentRecurrentAccountResponse3": { "required": [ "id", "type" ], "properties": { "id": { "type": "integer", "example": "123" }, "type": { "type": "string", "example": "card" }, "name": { "type": "string", "example": "** 7398", "nullable": true }, "card_expiry_date": { "properties": { "year": { "type": "string", "example": "2023" }, "month": { "type": "string", "example": "09" } }, "type": "object", "nullable": true }, "ps_name": { "type": "string", "example": "Mastercard", "nullable": true }, "switch_icon_name": { "type": "string", "example": "mastercard.svg", "nullable": true } }, "type": "object" }, "Period4": { "properties": { "value": { "type": "integer", "default": null, "example": "1", "nullable": true }, "unit": { "type": "string", "default": null, "example": "month", "nullable": true } }, "type": "object" }, "Charge4": { "required": [ "amount", "currency" ], "properties": { "amount": { "type": "number", "format": "float", "example": "4.99" }, "setup_fee": { "type": "number", "format": "float", "example": "0.99", "nullable": true }, "currency": { "type": "string", "example": "USD" } }, "type": "object" }, "Promotion2": { "properties": { "promotion_charge_amount": { "type": "number", "format": "float", "default": null, "example": "3.99", "nullable": true }, "promotion_remaining_charges": { "type": "integer", "default": null, "example": "3", "nullable": true } }, "type": "object" }, "Unused": { "properties": { "unused_amount": { "type": "number", "format": "float", "default": null, "example": "1.99", "nullable": true }, "unused_currency": { "type": "string", "default": null, "example": "USD", "nullable": true } }, "type": "object" }, "Surcharge": { "properties": { "surcharge_amount": { "type": "number", "format": "float", "default": null, "example": "1.99", "nullable": true }, "surcharge_currency": { "type": "string", "default": null, "example": "USD", "nullable": true } }, "type": "object" }, "PaymentSystemResponse": { "required": [ "id" ], "properties": { "id": { "type": "integer", "example": "12345" }, "name": { "type": "string", "example": "PayPal", "nullable": true } }, "type": "object" } }, "securitySchemes": { "basicAuth": { "type": "http", "description": "\nXsolla API uses basic access authentication. All requests to API must contain the `Authorization: Basic ` header, where `` is the `merchant_id:api_key` pair encoded according to the Base64 standard.\n\n Go to [Publisher Account](https://publisher.xsolla.com/) to find these parameters:
  • `merchant_id` is shown:
    • In the Company settings > Company section.
    • In the URL in the browser address bar on any Publisher Account page. The URL has the following format: `https://publisher.xsolla.com/`.
  • `api_key` is shown in Publisher Account only once when it is created and must be stored on your side. You can create a new key in the following section:
    • Company settings > API keys.
    • Project settings > API keys.

\n For more information about working with API keys, see the [API reference](https://developers.xsolla.com/api/getting-started/#api_keys_overview).", "scheme": "basic" }, "subscriptionsManagementJwtAuth": { "type": "http", "scheme": "bearer" } } }, "x-tagGroups": [ { "name": "Admin subscription management", "tags": [ "token", "plans", "products", "subscriptions", "payments", "promotions", "coupons" ] }, { "name": "User subscription management", "tags": [ "subscription-management" ] } ] }