Store API v2.0

Overview

This section describes methods for working with Store modules. Use basic authentication to call methods. To open the Store UI and enable secure payments you first need to get a token.

Endpoint path: https://api.xsolla.com.

Store UI

Opening Store

Use the following link to open the store UI in a new window: https://secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN, where ACCESS_TOKEN is the token received via API.

Use the following URL for testing purposes: https://sandbox-secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN.

Notice: Parameter access_token contains private user data. Please make sure that you use server-to-server communication when getting this parameter.

Test Cards List

In the Sandbox you can use these cards to simulate successful payments:

Card 3-D Secure
Card number: 4111111111111111
Exp. date: 1220
CVV2: 123
Card type: VISA
No
Card number: 5555555555554444
Exp. date: 1119
CVV2: 321
Card type: MasterCard
No
Card number: 4000000000000010
Exp. date: 1220
CVV2: 123
Card type: VISA
Yes
Card number: 5200000000000114
Exp. date: 1119
CVV2: 321
Card type: MasterCard
Yes
Card number: 6759649826438453
Exp. date: 1225
CVV2: 321
Card type: Maestro
Yes

In addition, you can use the following data to simulate declined transactions:

Card 3-D Secure Description
Card number: 4000000000000002
Exp. date: 1220
CVV2: 123
Card type: VISA
No Insufficient funds
Card number: 5200000000000007
Exp. date: 1119
CVV2: 321
Card type: MasterCard
No Insufficient funds
Card number: 4000000000000036
Exp. date: 1220
CVV2: 123
Card type: VISA
Yes Declined
Card number: 5200000000000031
Exp. date: 1119
CVV2: 321
Card type: MasterCard
Yes Declined

Errors List

Code Description
0004-0001 Token expired or incorrect.
0004-0008 Wrong URL (trying to access sandbox mode at secure.xsolla.com or live mode at sandbox-secure.xsolla.com).
0002-0004 Agreement not signed.
0004-0010 Tokenless integration prohibited.
0010-0001 Package not found.
0010-0003 Package has no DRM configured.
1000-0003 No modules turned on for the project.

Virtual Currency

Get Packages

Lists virtual currency packages available for a project.

HTTP REQUEST

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_currency

Parameter Type Description
project_id
integer Project ID.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->GetProjectVirtualCurrencySettings(array(
    'project_id' => PROJECT_ID
));
GET /merchant/v2/projects/{project_id}/virtual_currency HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_currency' \
-X GET \
-u merchant_id:merchant_api_key
Response
<?php

// example response
$response = array (
    'id' => 1,
    'vc_name' =>
        array (
            'en' => 'Golden Coins'
        ),
    'base' =>
        array (
            'USD' => 0.04,
            'EUR' => 0.03
        ),
    'default_currency' => 'USD',
    'min' => 0,
    'max' => 0,
    'is_currency_discrete' => true,
    'allow_user_sum' => true,
    'packets' =>
        array (
            'USD' =>
                array (
                    array (
                        'id' => 1,
                        'sku' => 'vc_usd',
                        'amount' => 100,
                        'price' => 10,
                        'image_url' => '//images.storage.com/some_image',
                        'description' =>
                            array (
                                'en' => 'Standard Package'
                            ),
                        'label' =>
                            array (
                                'en' => 'Standard Package'
                            ),
                        'bonus' => 0,
                        'advertisement_type' => 'recommended'
                        'enabled' => true
                    )
                ),
            'EUR' =>
                array (
                    array (
                        'id' => 2,
                        'sku' => 'vc_eur',
                        'amount' => 80,
                        'price' => 5,
                        'image_url' => null,
                        'description' =>
                            array (
                                'en' => 'Standard Package'
                            ),
                        'label' =>
                            array (
                                'en' => 'Standard Package'
                            ),
                        'bonus' => 0,
                        'advertisement_type' => 'recommended'
                        'enabled' => true
                    )
                )
        ),
    'type' => 'packets',
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "vc_name": {
        "en": "Golden Coins"
    },
    "base": {
        "USD": 0.04,
        "EUR": 0.03
    },
    "default_currency": "USD",
    "min": 0,
    "max": 0,
    "is_currency_discrete": true,
    "allow_user_sum": true,
    "packets": {
        "USD": [
            {
                "id": 1,
                "sku": "vc_usd",
                "amount": 100,
                "price": 10,
                "image_url": "//images.storage.com/some_image",
                "description": {
                    "en": "Standard Package"
                },
                "label": {
                    "en": "Standard Package"
                },
                "bonus": 0,
                "advertisement_type": "recommended",
                "enabled": true
            }
        ],
        "EUR": [
            {
                "id": 2,
                "sku": "vc_eur",
                "amount": 80,
                "price": 5,
                "image_url": null,
                "description": {
                    "en": "Standard Package"
                },
                "label": {
                    "en": "Standard Package"
                },
                "bonus": 0,
                "advertisement_type": "recommended",
                "enabled": true
            }
        ]
    },
    "type": "packets"
}
{
    "id": 1,
    "vc_name": {
        "en": "Golden Coins"
    },
    "base": {
        "USD": 0.04,
        "EUR": 0.03
    },
    "default_currency": "USD",
    "min": 0,
    "max": 0,
    "is_currency_discrete": true,
    "allow_user_sum": true,
    "packets": {
        "USD": [
            {
                "id": 1,
                "sku": "vc_usd",
                "amount": 100,
                "price": 10,
                "image_url": "//images.storage.com/some_image",
                "description": {
                    "en": "Standard Package"
                },
                "label": {
                    "en": "Standard Package"
                },
                "bonus": 0,
                "advertisement_type": "recommended",
                "enabled": true
            }
        ],
        "EUR": [
            {
                "id": 2,
                "sku": "vc_eur",
                "amount": 80,
                "price": 5,
                "image_url": null,
                "description": {
                    "en": "Standard Package"
                },
                "label": {
                    "en": "Standard Package"
                },
                "bonus": 0,
                "advertisement_type": "recommended",
                "enabled": true
            }
        ]
    },
    "type": "packets"
}

Update Package

Updates a project’s virtual currency package.

HTTP REQUEST

PUT https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_currency

Parameter Type Description
project_id
integer Project ID.
vc_name
array of strings Product name. Value consists of pairs “localization”:“product name”.
base
array Main product currency (object). Key = currency name (3 letters per ISO 4217); value = amount in that currency.
default_currency
string Default currency.
min
float Minimum purchase amount.
max
float Maximum purchase amount.
is_currency_discrete
boolean Whether to enable decimal units for the virtual currency.
allow_user_sum
boolean Whether the user can pay an arbitrary amount for the package.
amount
float Quantity of the virtual currency in the package.
sku
string Unique ID of the virtual currency package.
price
float Price of the package.
image_url
string Image URL.
description
array of strings Array with localized package names. Value consists of pairs “localization”:“package description”.
label
array of strings Localized package labels (array). Value consists of pairs “localization”:“package description”.
bonus
float Discount for the package (%).
advertisement_type
string Type of label to be used for the package. Can be ‘recommended’, ‘best_deal’, ‘special_offer’, or ‘null’.
enabled
boolean Enables the virtual currency package.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->UpdateProjectVirtualCurrencySettings(array(
    'project_id' => PROJECT_ID,
    'request' => array (
         'vc_name' =>
             array (
                 'en' => 'Golden Coins'
             ),
         'base' =>
             array (
                 'USD' => 0.04,
                 'EUR' => 0.02,
             ),
         'default_currency' => 'USD',
         'min' => 0,
         'max' => 0,
         'is_currency_discrete' => true,
         'allow_user_sum' => true,
         'packets' =>
             array (
                 'USD' =>
                     array (
                         array (
                             'id' => 1,
                             'sku' => 'vc_usd',
                             'amount' => 100,
                             'price' => 10,
                             'image_url' => '//images.storage.com/some_image',
                             'description' =>
                                 array (
                                     'en' => 'Standard Package'
                                 ),
                             'label' =>
                                 array (
                                     'en' => 'Standard Package'
                                 ),
                             'bonus' => 0,
                             'advertisement_type' => 'recommended'
                             'enabled' => true
                         )
                     ),
                 'EUR' =>
                     array (
                         array (
                             'id' => 2,
                             'sku' => 'vc_eur',
                             'amount' => 80,
                             'price' => 5,
                             'image_url' => null,
                             'description' =>
                                 array (
                                     'en' => 'Standard Package'
                                 ),
                             'label' =>
                                 array (
                                     'en' => 'Standard Package'
                                 ),
                             'bonus' => 0,
                             'advertisement_type' => 'recommended'
                             'enabled' => true
                         )
                     )
             ),
         'type' => 'packets',
     )
));
PUT /merchant/v2/projects/{project_id}/virtual_currency HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "vc_name": {
        "en": "Golden Coins"
    },
    "base": {
        "USD": 0.04,
        "EUR": 0.03
    },
    "default_currency": "USD",
    "min": 0,
    "max": 0,
    "is_currency_discrete": true,
    "allow_user_sum": true,
    "packets": {
        "USD": [
            {
                "id": 1,
                "sku": "vc_usd",
                "amount": 100,
                "price": 10,
                "image_url": "//images.storage.com/some_image",
                "description": {
                    "en": "Standard Package"
                },
                "label": {
                    "en": "Standard Package"
                },
                "bonus": 0,
                "advertisement_type": "recommended",
                "enabled": true
            }
        ],
        "EUR": [
            {
                "id": 2,
                "sku": "vc_eur",
                "amount": 80,
                "price": 5,
                "image_url": null,
                "description": {
                    "en": "Standard Package"
                },
                "label": {
                    "en": "Standard Package"
                },
                "bonus": 0,
                "advertisement_type": "recommended",
                "enabled": true
            }
        ]
    }
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_currency' \
-X PUT \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "vc_name": {
        "en": "Golden Coins"
    },
    "base": {
        "USD": 0.04,
        "EUR": 0.03
    },
    "default_currency": "USD",
    "min": 0,
    "max": 0,
    "is_currency_discrete": true,
    "allow_user_sum": true,
    "packets": {
        "USD": [
            {
                "id": 1,
                "sku": "vc_usd",
                "amount": 100,
                "price": 10,
                "image_url": "//images.storage.com/some_image",
                "description": {
                    "en": "Standard Package"
                },
                "label": {
                    "en": "Standard Package"
                },
                "bonus": 0,
                "advertisement_type": "recommended",
                "enabled": true
            }
        ],
        "EUR": [
            {
                "id": 2,
                "sku": "vc_eur",
                "amount": 80,
                "price": 5,
                "image_url": null,
                "description": {
                    "en": "Standard Package"
                },
                "label": {
                    "en": "Standard Package"
                },
                "bonus": 0,
                "advertisement_type": "recommended",
                "enabled": true
            }
        ]
    }
}'
Response
<?php

$response = null;
HTTP/1.1 204 No Content

Virtual Items

Create Item

Creates a virtual item.

HTTP REQUEST

POST https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/items

Parameter Type Description
project_id
integer Project ID.
sku
string Unique item ID. The SKU may only contain lowercase Latin alphanumeric characters, dashes, and underscores.
item_code
string Additional item code. Optional.
name
array of strings Localized item names (array).
description
array of strings Localized item descriptions (array).
long_description
array of strings Localized extended descriptions of the item (array).
prices
array Item prices (array).
default_currency
string Default purchase currency. Three-letter code per ISO 4217.
enabled
boolean Enables the item.
permanent
boolean If true, the item can only be purchased once.
image_url
string Image URL.
item_type
string Type of Item: Consumable/Expiration/Permanent/Lootboxes/Physical.
expiration
integer Lifetime in seconds. For Expiration-type items only.
groups
array of integers Groups the item belongs to (array).
deleted
boolean Whether the item was deleted.
user_attribute_conditions
array of objects List of conditions on the user attribute.
user_attribute_conditions.right_operand
array Values to compare the user attribute to.
user_attribute_conditions.user_attribute_key
string Key of the user attribute condition.
user_attribute_conditions.operation
string Type of operation. Can be ‘greater’, ‘greaterOrEqual’, ‘equal’, ‘notEqual’, ‘less’, ‘lessOrEqual’, ‘between’, ‘in’, ‘notIn’.
user_attribute_conditions.action
string Type of action. Can be ‘hide’, ‘block’, ‘warning’.
advertisement_type
string Type of a special banner to show for the item in the payment UI. Can be ‘recommended’, ‘best_deal’, ‘special_offer’, ‘null’.
virtual_currency_price
integer Price in the in-game currency. If ‘null’, the item can only be purchased for real currency.
purchase_limit
integer Number of times the item can be purchased. If ‘null’, there is no limit on the number of purchases.
keywords
array Keywords that can be used to find the item in the payment UI.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->CreateVirtualItem(array(
    'project_id' => PROJECT_ID,
    'request' => array (
         'sku' => 'T-43-3-unique-id',
         'item_code' => 'chinese-medium-tank',
         'name' =>
             array (
                 'en' => 'T-34-3',
             ),
         'description' =>
             array (
                 'en' => 'Chinese Tier VIII medium tank.',
             ),
         'long_description' =>
             array (
                 'en' => 'This Chinese Tier VIII medium tank is a real beast in its class.',
             ),
         'prices' =>
             array (
                 'USD' => 40.09,
             ),
         'default_currency' => 'USD',
         'enabled' => true,
         'permanent' => false,
         'image_url' => 'http://livedemo.xsolla.com/airplanes/tank5.jpg',
         'item_type' => 'Expiration',
         'expiration' => 1296000,
         'groups' =>
             array (
                 24,
                 25,
             ),
         'user_attribute_conditions' =>
             array (
             array (
                     'right_operand' =>
                         array (
                             'magic',
                         ),
                     'id' => 2015,
                     'user_attribute_key' => 'type',
                     'operation' => 'equal',
                     'action' => 'hide',
                     'name' => null,
                 ),
             ),
         'virtual_currency_price' => null,
         'purchase_limit' => null,
         'keywords' =>
             array (
                 'de' =>
                     array (
                         'Inhalt',
                         'Aufgaben',
                         'Region',
                         'Landschaft',
                     ),
                 'en' =>
                     array (
                         'content',
                         'quests',
                         'region',
                         'landscape',
                     ),
             ),
         'advertisement_type' => 'recommended',
         'deleted' => false,
    )
));
POST /merchant/v2/projects/{project_id}/virtual_items/items HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "sku": "T-43-3-unique-id",
    "item_code": "chinese-medium-tank",
    "name": {
        "en": "T-34-3"
    },
    "description": {
        "en": "Chinese Tier VIII medium tank."
    },
    "long_description": {
            "en": "This Chinese Tier VIII medium tank is a real beast in its class."
    },
    "prices": {
        "USD": 40.09
    },
    "default_currency": "USD",
    "enabled": true,
    "permanent": false,
    "image_url": "http:\/\/livedemo.xsolla.com\/airplanes\/tank5.jpg",
    "item_type": "Expiration",
    "expiration": 1296000,
    "groups": [
        24,
        25
    ],
    "user_attribute_conditions": [
         {
             "right_operand": [
                 "magic"
             ],
             "id": 2015,
             "user_attribute_key": "type",
             "operation": "equal",
             "action": "hide",
             "name":null
         }
    ],
    "virtual_currency_price": null,
    "purchase_limit": null,
    "keywords": {
        "de":[
            "Inhalt","Aufgaben","Region","Landschaft"
        ],
        "en":[
            "content","quests","region","landscape"
        ]
    },
    "advertisement_type": "recommended",
    "deleted": false
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/items' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "sku": "T-43-3-unique-id",
    "item_code": "chinese-medium-tank",
    "name": {
        "en": "T-34-3"
    },
    "description": {
        "en": "Chinese Tier VIII medium tank."
    },
    "long_description": {
            "en": "This Chinese Tier VIII medium tank is a real beast in its class."
    },
    "prices": {
        "USD": 40.09
    },
    "default_currency": "USD",
    "enabled": true,
    "permanent": false,
    "image_url": "http:\/\/livedemo.xsolla.com\/airplanes\/tank5.jpg",
    "item_type": "Expiration",
    "expiration": 1296000,
    "groups": [
        24,
        25
    ],
    "user_attribute_conditions": [
         {
             "right_operand": [
                 "magic"
             ],
             "id": 2015,
             "user_attribute_key": "type",
             "operation": "equal",
             "action": "hide",
             "name":null
         }
    ],
    "virtual_currency_price": null,
    "purchase_limit": null,
    "keywords": {
        "de":[
            "Inhalt","Aufgaben","Region","Landschaft"
        ],
        "en":[
            "content","quests","region","landscape"
        ]
    },
    "advertisement_type": "recommended",
    "deleted": false
}'
Response
<?php

// example response
$response = array (
    'item_id' => 77
);
HTTP/1.1 201 Created
Content-Type: application/json

{
    "item_id": 77
}
{
    "item_id": 77
}

Get Item

Retrieves a virtual item.

HTTP REQUEST

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/items/{item_id}

Parameter Type Description
item_id
integer Item ID.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->GetVirtualItem(array(
    'project_id' => PROJECT_ID,
    'item_id' => ITEM_ID
));
GET /merchant/v2/projects/{project_id}/virtual_items/items/{item_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/items/{item_id}' \
-X GET \
-u merchant_id:merchant_api_key
Response
<?php

// example response
$response = array (
    'id' => 77,
    'sku' => 'T-43-3-unique-id',
    'item_code' => 'chinese-medium-tank',
    'name' =>
        array (
            'en' => 'T-34-3'
        ),
    'description' =>
        array (
            'en' => 'Chinese Tier VIII medium tank.'
        ),
    'long_description' =>
        array (
            'en' => 'This Chinese Tier VIII medium tank is a real beast in its class.'
        ),
    'prices' =>
        array (
            'USD' => 40.09
        ),
    'default_currency' => 'USD',
    'enabled' => true,
    'permanent' => false,
    'image_url' => 'http://livedemo.xsolla.com/airplanes/tank5.jpg',
    'item_type' => 'Expiration',
    'expiration' => 1296000,
    'groups' =>
        array (
            24,
            25
        ),
    'user_attribute_conditions' =>
        array (
        array (
                'right_operand' =>
                     array (
                        'magic',
                    ),
                'id' => 2015,
                'user_attribute_key' => 'type',
                'operation' => 'equal',
                'action' => 'hide',
                'name' => null,
            ),
        ),
    'virtual_currency_price' => null,
    'purchase_limit' => null,
    'keywords' =>
        array (
            'de' =>
                array (
                    'Inhalt',
                    'Aufgaben',
                    'Region',
                    'Landschaft',
                ),
            'en' =>
                array (
                    'content',
                    'quests',
                    'region',
                    'landscape',
                ),
        ),
    'advertisement_type' => 'recommended',
    'deleted' => false,
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 77,
    "sku": "T-43-3-unique-id",
    "item_code": "chinese-medium-tank",
    "name": {
        "en": "T-34-3"
    },
    "description": {
        "en": "Chinese Tier VIII medium tank."
    },
    "long_description": {
            "en": "This Chinese Tier VIII medium tank is a real beast in its class."
    },
    "prices": {
        "USD": 40.09
    },
    "default_currency": "USD",
    "enabled": true,
    "permanent": false,
    "image_url": "http:\/\/livedemo.xsolla.com\/airplanes\/tank5.jpg",
    "item_type": "Expiration",
    "expiration": 1296000,
    "groups": [
        24,
        25
    ],
    "user_attribute_conditions": [
         {
             "right_operand": [
                 "magic"
             ],
             "id": 2015,
             "user_attribute_key": "type",
             "operation": "equal",
             "action": "hide",
             "name":null
         }
    ],
    "virtual_currency_price": null,
    "purchase_limit": null,
    "keywords": {
        "de":[
            "Inhalt","Aufgaben","Region","Landschaft"
        ],
        "en":[
            "content","quests","region","landscape"
        ]
    },
    "advertisement_type": "recommended",
    "deleted": false
}
{
    "id": 77,
    "sku": "T-43-3-unique-id",
    "item_code": "chinese-medium-tank",
    "name": {
        "en": "T-34-3"
    },
    "description": {
        "en": "Chinese Tier VIII medium tank."
    },
    "long_description": {
            "en": "This Chinese Tier VIII medium tank is a real beast in its class."
    },
    "prices": {
        "USD": 40.09
    },
    "default_currency": "USD",
    "enabled": true,
    "permanent": false,
    "image_url": "http:\/\/livedemo.xsolla.com\/airplanes\/tank5.jpg",
    "item_type": "Expiration",
    "expiration": 1296000,
    "groups": [
        24,
        25
    ],
    "user_attribute_conditions": [
         {
             "right_operand": [
                 "magic"
             ],
             "id": 2015,
             "user_attribute_key": "type",
             "operation": "equal",
             "action": "hide",
             "name":null
         }
    ],
    "virtual_currency_price": null,
    "purchase_limit": null,
    "keywords": {
        "de":[
            "Inhalt","Aufgaben","Region","Landschaft"
        ],
        "en":[
            "content","quests","region","landscape"
        ]
    },
    "advertisement_type": "recommended",
    "deleted": false
}

Update Item

Updates a virtual item.

HTTP REQUEST

PUT https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/items/{item_id}

Parameter Type Description
item_id
integer Item ID.
sku
string Unique item ID. The SKU may only contain lowercase Latin alphanumeric characters, dashes, and underscores.
item_code
string Additional item code. Optional.
name
array of strings Localized item names (array).
description
array of strings Localized item descriptions (array).
long_description
array of strings Localized extended descriptions of the item (array).
prices
array Item prices (array).
default_currency
string Default purchase currency. Three-letter code per ISO 4217.
enabled
boolean Enables the item.
permanent
boolean If true, the item can only be purchased once.
image_url
string Image URL.
item_type
string Type of Item: Consumable/Expiration/Permanent/Lootboxes/Physical.
expiration
integer Lifetime in seconds. For Expiration-type items only.
groups
array of integers Groups the item belongs to (array).
deleted
boolean Whether the item was deleted.
user_attribute_conditions
array of objects List of conditions on the user attribute.
user_attribute_conditions.right_operand
array Values to compare the user attribute to.
user_attribute_conditions.user_attribute_key
string Key of the user attribute condition.
user_attribute_conditions.operation
string Type of operation. Can be ‘greater’, ‘greaterOrEqual’, ‘equal’, ‘notEqual’, ‘less’, ‘lessOrEqual’, ‘between’, ‘in’, ‘notIn’.
user_attribute_conditions.action
string Type of action. Can be ‘hide’, ‘block’, ‘warning’.
advertisement_type
string Type of a special banner to show for the item in the payment UI. Can be ‘recommended’, ‘best_deal’, ‘special_offer’, ‘null’.
virtual_currency_price
integer Price in the in-game currency. If ‘null’, the item can only be purchased for real currency.
purchase_limit
integer Number of times the item can be purchased. If ‘null’, there is no limit on the number of purchases.
keywords
array Keywords that can be used to find the item in the payment UI.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->UpdateVirtualItem(array(
    'project_id' => PROJECT_ID,
    'request' => array (
         'sku' => 'T-43-3-unique-id',
         'item_code' => 'chinese-medium-tank',
         'name' =>
             array (
                 'en' => 'T-34-3',
             ),
         'description' =>
             array (
                 'en' => 'Chinese Tier VIII medium tank.',
             ),
         'long_description' =>
             array (
                 'en' => 'This Chinese Tier VIII medium tank is a real beast in its class.',
             ),
         'prices' =>
             array (
                 'USD' => 40.09,
             ),
         'default_currency' => 'USD',
         'enabled' => true,
         'permanent' => false,
         'image_url' => 'http://livedemo.xsolla.com/airplanes/tank5.jpg',
         'item_type' => 'Expiration',
         'expiration' => 1296000,
         'groups' =>
             array (
                 24,
                 25,
             ),
         'user_attribute_conditions' =>
             array (
             array (
                     'right_operand' =>
                         array (
                             'magic',
                         ),
                     'id' => 2015,
                     'user_attribute_key' => 'type',
                     'operation' => 'equal',
                     'action' => 'hide',
                     'name' => null,
                 ),
             ),
         'virtual_currency_price' => null,
         'purchase_limit' => null,
         'keywords' =>
             array (
                 'de' =>
                     array (
                         'Inhalt',
                         'Aufgaben',
                         'Region',
                         'Landschaft',
                     ),
                 'en' =>
                     array (
                         'content',
                         'quests',
                         'region',
                         'landscape',
                     ),
             ),
         'advertisement_type' => 'recommended',
         'deleted' => false,
    )
));
PUT /merchant/v2/projects/{project_id}/virtual_items/items/{item_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
{
    "sku": "T-43-3-unique-id",
    "item_code": "chinese-medium-tank",
    "name": {
        "en": "T-34-3"
    },
    "description": {
        "en": "Chinese Tier VIII medium tank."
    },
    "long_description": {
            "en": "This Chinese Tier VIII medium tank is a real beast in its class."
    },
    "prices": {
        "USD": 40.09
    },
    "default_currency": "USD",
    "enabled": true,
    "permanent": false,
    "image_url": "http:\/\/livedemo.xsolla.com\/airplanes\/tank5.jpg",
    "item_type": "Expiration",
    "expiration": 1296000,
    "groups": [
        24,
        25
    ],
    "user_attribute_conditions": [
         {
             "right_operand": [
                 "magic"
             ],
             "id": 2015,
             "user_attribute_key": "type",
             "operation": "equal",
             "action": "hide",
             "name":null
         }
    ],
    "virtual_currency_price": null,
    "purchase_limit": null,
    "keywords": {
        "de":[
            "Inhalt","Aufgaben","Region","Landschaft"
        ],
        "en":[
            "content","quests","region","landscape"
        ]
    },
    "advertisement_type": "recommended",
    "deleted": false
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/items/{item_id}' \
-X PUT \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "sku": "T-43-3-unique-id",
    "item_code": "chinese-medium-tank",
    "name": {
        "en": "T-34-3"
    },
    "description": {
        "en": "Chinese Tier VIII medium tank."
    },
    "long_description": {
            "en": "This Chinese Tier VIII medium tank is a real beast in its class."
    },
    "prices": {
        "USD": 40.09
    },
    "default_currency": "USD",
    "enabled": true,
    "permanent": false,
    "image_url": "http:\/\/livedemo.xsolla.com\/airplanes\/tank5.jpg",
    "item_type": "Expiration",
    "expiration": 1296000,
    "groups": [
        24,
        25
    ],
    "user_attribute_conditions": [
         {
             "right_operand": [
                 "magic"
             ],
             "id": 2015,
             "user_attribute_key": "type",
             "operation": "equal",
             "action": "hide",
             "name":null
         }
    ],
    "virtual_currency_price": null,
    "purchase_limit": null,
    "keywords": {
        "de":[
            "Inhalt","Aufgaben","Region","Landschaft"
        ],
        "en":[
            "content","quests","region","landscape"
        ]
    },
    "advertisement_type": "recommended",
    "deleted": false
}'
Response
<?php

$response = null;
HTTP/1.1 204 No Content

Delete Item

Deletes a virtual item.

HTTP REQUEST

DELETE https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/items/{item_id}

Parameter Type Description
item_id
integer Item ID.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->DeleteVirtualItem(array(
    'project_id' => PROJECT_ID,
    'item_id' => ITEM_ID
));
DELETE /merchant/v2/projects/{project_id}/virtual_items/items/{item_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/items/{item_id}' \
-X DELETE \
-u merchant_id:merchant_api_key
Response
<?php

$response = null;
HTTP/1.1 204 No Content

Get Items List

Lists all virtual items.

HTTP REQUEST

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/items

Parameter Type Description
project_id
integer Project ID.
offset
integer Number of the element from which the list is generated (the count starts from 0).
limit
integer Limit for the number of elements on the page.
has_price
string Price type: ‘virtual_currency’ or ‘real_currency’ if the item can be purchased for virtual or real currency, respectively.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->ListVirtualItems(array(
    'project_id' => PROJECT_ID
));
GET /merchant/v2/projects/{project_id}/virtual_items/items HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/items' \
-X GET \
-u merchant_id:merchant_api_key
Response
<?php

// example response
$response = array (
    array (
            'id' => 46,
            'sku' => 'T-43-3-unique-id',
            'localized_name' => 'T-34-3',
            'prices' =>
                array (
                    'USD' => 40.09
                ),
            'default_currency' => 'USD',
            'enabled' => true,
            'permanent' => false,
            'groups' =>
                array (
                    25
                ),
            'advertisement_type' => null,
            'virtual_currency_price' => null
        )
);
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": 46,
        "sku": "T-43-3-unique-id",
        "localized_name": "T-34-3",
        "prices": {
            "USD": 40.09
        },
        "default_currency": "USD",
        "enabled": true,
        "permanent": false,
        "groups": [
            25
        ],
        "advertisement_type": null,
        "virtual_currency_price": null
    }
]
[
    {
        "id": 46,
        "sku": "T-43-3-unique-id",
        "localized_name": "T-34-3",
        "prices": {
            "USD": 40.09
        },
        "default_currency": "USD",
        "enabled": true,
        "permanent": false,
        "groups": [
            25
        ],
        "advertisement_type": null,
        "virtual_currency_price": null
    }
]

Create Items Group

Creates a virtual item group.

HTTP REQUEST

POST https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/groups

Parameter Type Description
project_id
integer Project ID.
name
array of strings Localized group names (array).
description
array of strings Localized group descriptions (array).
enabled
boolean Enables the group.
parent_id
integer Parent group ID.
code
integer Group’s unique code.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->CreateVirtualItemsGroup(array(
    'project_id' => PROJECT_ID,
    'request' => array (
         'name' =>
             array (
                 'en' => 'Tanks',
             ),
         'description' =>
             array (
                 'en' => 'Tanks Group',
             ),
         'enabled' => true,
         'parent_id' => null,
         'code' => null
     )
));
POST /merchant/v2/projects/{project_id}/virtual_items/groups HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "name": {
        "en": "Tanks"
    },
    "description": {
        "en": "Tanks Group"
    },
    "enabled": true,
    "parent_id": null,
    "code": null
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/groups' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "name": {
        "en": "Tanks"
    },
    "description": {
        "en": "Tanks Group"
    },
    "enabled": true,
    "parent_id": null,
    "code": null
}'
Response
<?php

// example response
$response = array (
    'group_id' => 7
);
HTTP/1.1 201 Created
Content-Type: application/json

{
    "group_id": 7
}
{
    "group_id": 7
}

Get Items Group

Retrieves details on a virtual item group.

HTTP REQUEST

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/groups/{group_id}

Parameter Type Description
group_id
string Group ID.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->GetVirtualItemsGroup(array(
    'project_id' => PROJECT_ID,
    'group_id' => GROUP_ID
));
GET /merchant/v2/projects/{project_id}/virtual_items/groups/{group_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/groups/{group_id}' \
-X GET \
-u merchant_id:merchant_api_key
Response
<?php

// example response
$response = array (
    'id' => 25,
    'name' =>
        array (
            'en' => 'Tanks'
        ),
    'description' =>
        array (
            'en' => 'Tanks Group'
        ),
    'enabled' => true,
    'parent_id' => null,
    'code' => null
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 25,
    "name": {
        "en": "Tanks"
    },
    "description": {
        "en": "Tanks Group"
    },
    "enabled": true,
    "parent_id": null,
    "code": null
}
{
    "id": 25,
    "name": {
        "en": "Tanks"
    },
    "description": {
        "en": "Tanks Group"
    },
    "enabled": true,
    "parent_id": null,
    "code": null
}

Update Items Group

Updates a virtual item group.

HTTP REQUEST

PUT https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/groups/{group_id}

Parameter Type Description
group_id
string Group ID.
name
array of strings Localized group names (array).
description
array of strings Localized group descriptions (array).
enabled
boolean Enables the group.
parent_id
integer Parent group ID.
code
integer Group’s unique code.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->UpdateVirtualItemsGroup(array(
    'project_id' => PROJECT_ID,
    'group_id' => GROUP_ID,
    'request' => array (
         'name' =>
             array (
                 'en' => 'Tanks',
             ),
         'description' =>
             array (
                 'en' => 'Tanks Group',
             ),
         'enabled' => true,
         'parent_id' => null,
         'code' => null
     )
));
PUT /merchant/v2/projects/{project_id}/virtual_items/groups/{group_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "name": {
        "en": "Tanks"
    },
    "description": {
        "en": "Tanks Group"
    },
    "enabled": true,
    "parent_id": null,
    "code": null
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/groups/{group_id}' \
-X PUT \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "name": {
        "en": "Tanks"
    },
    "description": {
        "en": "Tanks Group"
    },
    "enabled": true,
    "parent_id": null,
    "code": null
}'
Response
<?php

$response = null;
HTTP/1.1 204 No Content

Delete Items Group

Deletes a virtual item group.

HTTP REQUEST

DELETE https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/groups/{group_id}

Parameter Type Description
group_id
string Group ID.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->DeleteVirtualItemsGroup(array(
    'project_id' => PROJECT_ID,
    'group_id' => GROUP_ID
));
DELETE /merchant/v2/projects/{project_id}/virtual_items/groups/{group_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/groups/{group_id}' \
-X DELETE \
-u merchant_id:merchant_api_key
Response
<?php

$response = null;
HTTP/1.1 204 No Content

Get Items Groups List

Lists all virtual item groups.

HTTP REQUEST

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/groups

Parameter Type Description
project_id
integer Project ID.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->ListVirtualItemsGroups(array(
    'project_id' => PROJECT_ID
));
GET /merchant/v2/projects/{project_id}/virtual_items/groups HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/groups' \
-X GET \
-u merchant_id:merchant_api_key
Response
<?php

// example response
$response = array (
    array (
        'id' => 25,
        'localized_name' => 'Tanks',
        'enabled' => true,
        'parent_id' => null,
        'has_groups' => false,
        'has_virtual_items' => true,
        'virtual_items_count' => 6,
        'code' => null
    )
);
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": 25,
        "localized_name": "Tanks",
        "enabled": true,
        "parent_id": null,
        "has_groups": false,
        "has_virtual_items": true,
        "virtual_items_count": 6,
        "code": null
    }
]
[
    {
        "id": 25,
        "localized_name": "Tanks",
        "enabled": true,
        "parent_id": null,
        "has_groups": false,
        "has_virtual_items": true,
        "virtual_items_count": 6,
        "code": null
    }
]

User Attributes

Create Attribute

Creates a user attribute.

HTTP REQUEST

POST https://api.xsolla.com/merchant/v2/projects/{project_id}/user_attributes

Parameter Type Description
project_id
integer Project ID. Required.
key
string Key of the user attribute. Required.
name
array of strings Localized attribute names. Required.
type
string Key type. Can be ‘int’, ‘string’, ‘enum’, or ‘date’. Required.
list_of_values
array Array of possible values for enum type. Required.
skip_condition_on_nonexistent_key
boolean Whether to skip the condition if key doesn’t exist.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->CreateUserAttribute(array(
    'project_id' => PROJECT_ID,
    'request' => array (
         'key' => 'class',
         'name' =>
             array (
                 'en' => 'Сlass',
                 'de' => 'Classe',
             ),
         'type' => 'enum',
         'list_of_values' =>
             array (
                 'Warrior',
                 'magic',
             ),
     )
));
POST /merchant/v2/projects/{project_id}/user_attributes HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
{
    "key": "class",
    "name": {
        "en": "Сlass",
        "de": "Classe"
    },
    "type": "enum",
    "list_of_values": ["Warrior", "magic"],
    "visible":true
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/user_attributes' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "key": "class",
    "name": {
        "en": "Сlass",
        "de": "Classe"
    },
    "type": "enum",
    "list_of_values": ["Warrior", "magic"],
    "visible":true
}'
Response
<?php

// example response
$response = array (
    'id' => 77
);
HTTP/1.1 201 Created
Content-Type: application/json

{
    "id": 77
}
{
    "id": 77
}

Get Attribute

Gets details on a specific user attribute.

HTTP REQUEST

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/user_attributes/{user_attribute_id}

Parameter Type Description
project_id
integer Project ID.
user_attribute_id
integer User attribute ID.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->GetUserAttribute(array(
    'project_id' => PROJECT_ID,
    'user_attribute_id' => USER_ATTRIBUTE_ID
));
GET /merchant/v2/projects/{project_id}/user_attributes/{user_attribute_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/user_attributes/{user_attribute_id}' \
-X GET \
-u merchant_id:merchant_api_key
Response
<?php

// example response
$response = array (
    'id' => 2,
    'key' => 'level',
    'localized_name' =>
        array (
            'en' => 'level',
            'de' => 'niveau'
        ),
    'name' => 'Level',
    'type' => 'int',
    'list_of_values' =>
        array (),
    'visible' => true,
    'skip_condition_on_nonexistent_key' => false
);
HTTP/1.1 200 OK
Content-Type: application/json
{
    "id": 2,
    "key": "level",
    "localized_name": {
        "en": "level",
        "de": "niveau"
    },
    "name": "Level",
    "type": "int",
    "list_of_values": [],
    "visible":true,
    "skip_condition_on_nonexistent_key": false
}
{
    "id": 2,
    "key": "level",
    "localized_name": {
        "en": "level",
        "de": "niveau"
    },
    "name": "Level",
    "type": "int",
    "list_of_values": [],
    "visible":true,
    "skip_condition_on_nonexistent_key": false
}

Update Attribute

Updates a user attribute.

HTTP REQUEST

PUT https://api.xsolla.com/merchant/v2/projects/{project_id}/user_attributes/{user_attribute_id}

Parameter Type Description
project_id
integer Project ID.
user_attribute_id
integer User attribute ID.
key
string Key of the user attribute. Required.
name
array of strings Localized attribute names. Required.
type
string Key type. Can be ‘int’, ‘string’, ‘enum’, or ‘date’. Required.
list_of_values
array Array of possible values for enum type. Required.
skip_condition_on_nonexistent_key
boolean Whether to skip the condition if key doesn’t exist.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->UpdateUserAttribute(array(
    'project_id' => PROJECT_ID,
    'user_attribute_id' => USER_ATTRIBUTE_ID,
    'request' => array(
         'key' => 'class',
         'name' =>
             array (
                 'en' => 'Сlass',
                 'de' => 'Classe',
             ),
         'type' => 'enum',
         'list_of_values' =>
             array (
                 'Warrior',
                 'magic',
             ),
         'skip_condition_on_nonexistent_key' => false
     )
));
PUT /merchant/v2/projects/{project_id}/user_attributes/{user_attribute_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
{
    "key": "class",
    "localized_name": {
        "en": "Сlass",
        "de": "Classe"
    },
    "type": "enum",
    "list_of_values": ["Warrior", "magic"],
    "visible":true,
    "skip_condition_on_nonexistent_key": false
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/user_attributes/{user_attribute_id}' \
-X PUT \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "key": "class",
    "localized_name": {
        "en": "Сlass",
        "de": "Classe"
    },
    "type": "enum",
    "list_of_values": ["Warrior", "magic"],
    "visible":true,
    "skip_condition_on_nonexistent_key": false
}'
Response
<?php

$response = null;
HTTP/1.1 204 No Content

Delete Attribute

Deletes a user attribute.

HTTP REQUEST

DELETE https://api.xsolla.com/merchant/v2/projects/{project_id}/user_attributes/{user_attribute_id}

Parameter Type Description
project_id
integer Project ID.
user_attribute_id
integer User attribute ID.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->DeleteUserAttribute(array(
    'project_id' => PROJECT_ID,
    'user_attribute_id' => USER_ATTRIBUTE_ID
));
DELETE /merchant/v2/projects/{project_id}/user_attributes/{user_attribute_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/user_attributes/{user_attribute_id}' \
-X DELETE \
-u merchant_id:merchant_api_key
Response
<?php

$response = null;
HTTP/1.1 204 No Content

Get Attributes List

Lists all user attributes.

HTTP REQUEST

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/user_attributes

Parameter Type Description
project_id
integer Project ID.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->ListUserAttributes(array(
    'project_id' => PROJECT_ID
));
GET /merchant/v2/projects/{project_id}/user_attributes HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/user_attributes' \
-X GET \
-u merchant_id:merchant_api_key
Response
<?php

// example response
$response = array (
    array (
        'id' => 2,
        'key' => 'level',
        'localized_name' =>
            array (
                'en' => 'Level'
            ),
        'name' => 'Level',
        'type' => 'int',
        'list_of_values' =>
            array (
            ),
        'visible' => true,
        'skip_condition_on_nonexistent_key' => false
    ),
    array (
        'id' => 3,
        'key' => 'class',
        'localized_name' =>
            array (
            )
        'name' => null,
        'type' => 'string',
        'list_of_values' =>
            array (
            ),
        'visible' => true,
        'skip_condition_on_nonexistent_key' => false
    ),
    array (
        'id' => 4,
        'key' => 'type',
        'localized_name' =>
            array (
            )
        'name' => null,
        'type' => 'enum',
        'list_of_values' =>
            array (
                0 => 'class1',
                1 => 'class2',
                2 => 'class3'
            ),
        'visible' => true,
        'skip_condition_on_nonexistent_key' => false
    ),
    array (
        'id' => 5,
        'key' => 'date',
        'localized_name' =>
            array (
                'en' => 'Date'
            ),
        'name' => 'Date',
        'type' => 'date',
        'list_of_values' =>
            array (
            ),
        'visible' => true,
        'skip_condition_on_nonexistent_key' => false
    )
);
HTTP/1.1 200 OK
Content-Type: application/json
[
    {
        "id": 2,
        "key": "level",
        "localized_name": {
            "en": "Level"
        },
        "name": "Level",
        "type": "int",
        "list_of_values": [],
        "visible":true,
        "skip_condition_on_nonexistent_key": false
    },
    {
        "id": 3,
        "key": "class",
        "localized_name": [],
        "name": null,
        "type": "string",
        "list_of_values": [],
        "visible":true
    },
    {
        "id": 4,
        "key": "type",
        "localized_name": [],
        "name": null,
        "type": "enum",
        "list_of_values": [
            "class1",
            "class2",
            "class3"
        ],
        "visible":true,
        "skip_condition_on_nonexistent_key": false
    },
    {
        "id": 5,
        "key": "date",
        "localized_name": {
            "en": "Date"
        },
        "name": "Date",
        "type": "date",
        "list_of_values": [],
        "visible":true,
        "skip_condition_on_nonexistent_key": false
    }
]
[
    {
        "id": 2,
        "key": "level",
        "localized_name": {
            "en": "Level"
        },
        "name": "Level",
        "type": "int",
        "list_of_values": [],
        "visible":true,
        "skip_condition_on_nonexistent_key": false
    },
    {
        "id": 3,
        "key": "class",
        "localized_name": [],
        "name": null,
        "type": "string",
        "list_of_values": [],
        "visible":true,
        "skip_condition_on_nonexistent_key": false
    },
    {
        "id": 4,
        "key": "type",
        "localized_name": [],
        "name": null,
        "type": "enum",
        "list_of_values": [
            "class1",
            "class2",
            "class3"
        ],
        "visible":true,
        "skip_condition_on_nonexistent_key": false
    },
    {
        "id": 5,
        "key": "date",
        "localized_name": {
            "en": "Date"
        },
        "name": "Date",
        "type": "date",
        "list_of_values": [],
        "visible":true,
        "skip_condition_on_nonexistent_key": false
    }
]

Subscriptions

Create Plan

Creates a subscription plan.

HTTP REQUEST

POST https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/plans

Parameter Type Description
project_id
integer Project ID.
external_id
string Plan external ID (32 characters). Optional.
name
array of strings Plan name. Value consists of pairs “localization”:“plan name”.
description
array of strings Plan description. Value consists of pairs “localization”:“plan description”. Optional.
group_id
string Group ID the plans are linked to.
charge
object Billing details (object).
charge.period
object Billing period (object).
charge.period.value
integer Number of time units.
charge.period.type
string Time unit: day/month.
charge.amount
float Billing amount.
charge.currency
string Currency of the purchase. Three-letter currency code per ISO 4217.
expiration
object Subscription expiration details (object).
expiration.value
integer Validity time.
expiration.type
string Time unit: day/month.
trial
object Trial period details (object). Optional.
trial.value
integer Trial period.
trial.type
string Time unit: day.
grace_period
object Grace period details. Optional.
grace_period.value
integer Grace period.
grace_period.type
string Time unit: day.
tags
array Plan tags. Optional.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->CreateSubscriptionPlan(array(
    'project_id' => PROJECT_ID,
    'request' => array (
         'external_id' => 'sample_plan',
         'name' =>
             array (
                 'en' => 'Sample Plan',
             ),
         'description' =>
             array (
                 'en' => 'Basic options plan',
             ),
         'group_id' => 'USA Products',
         'charge' =>
             array (
                 'period' =>
                     array (
                         'value' => 1,
                         'type' => 'month',
                     ),
                 'amount' => 10,
                 'currency' => 'USD',
             ),
         'expiration' =>
             array (
                 'value' => '',
                 'type' => '',
             ),
         'tags' =>
             array (
                 'tag1',
                 'tag2',
                 'tag3',
             ),
     )

));
POST /merchant/v2/projects/{project_id}/subscriptions/plans HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "external_id": "sample_plan",
    "name": {
        "en": "Sample Plan"
    },
    "description": {
        "en": "Basic options plan"
    },
    "group_id": "USA Products",
    "charge": {
        "period": {
            "value": 1,
            "type": "month"
        },
        "amount": 10,
        "currency": "USD"
    },
    "expiration": {
        "value": "",
        "type": ""
    },
    "tags": [
      "tag1",
      "tag2",
      "tag3"
    ]
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/plans' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "external_id": "sample_plan",
    "name": {
        "en": "Sample Plan"
    },
    "description": {
        "en": "Basic options plan"
    },
    "group_id": "USA Products",
    "charge": {
        "period": {
            "value": 1,
            "type": "month"
        },
        "amount": 10,
        "currency": "USD",
    },
    "expiration": {
        "value": "",
        "type": ""
    },
    "tags": [
      "tag1",
      "tag2",
      "tag3"
    ]
}'
Response
<?php

// example response
$response = array (
    'plan_id' => 54,
    'external_id': 'sample_plan'
);
HTTP/1.1 201 Created
Content-Type: application/json

{
    "plan_id": 54
}
{
    "plan_id": 54,
    "external_id": "sample_plan"
}

Update Plan Parameters

Updates subscription plan parameters.

HTTP REQUEST

PUT https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/plans/{plan_id}

Parameter Type Description
project_id
integer Project ID.
plan_id
integer Plan ID.
external_id
string Plan external ID (32 characters). Optional.
name
array of strings Plan name. Value consists of pairs “localization”:“plan name”.
description
array of strings Plan description. Value consists of pairs “localization”:“plan description”. Optional.
group_id
string Group ID the plans are linked to.
charge
object Billing details (object).
charge.period
object Billing period (object).
charge.period.value
integer Number of time units.
charge.period.type
string Time unit: day/month.
charge.amount
float Billing amount.
charge.currency
string Currency of the purchase. Three-letter currency code per ISO 4217.
expiration
object Subscription expiration details (object).
expiration.value
integer Validity time.
expiration.type
string Time unit: day/month.
trial
object Trial period details (object). Optional.
trial.value
integer Trial period.
trial.type
string Time unit: day.
grace_period
object Grace period details. Optional.
grace_period.value
integer Grace period.
grace_period.type
string Time unit: day.
tags
array Plan tags. Optional.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->UpdateSubscriptionPlan(array(
    'project_id' => PROJECT_ID,
    'plan_id' => PLAN_ID,
    'request' => array (
         'external_id' => 'sample_plan',
         'name' =>
             array (
                 'en' => 'Sample Plan',
             ),
         'description' =>
             array (
                 'en' => 'Basic options plan',
             ),
         'charge' =>
             array (
                 'period' =>
                     array (
                         'value' => 1,
                         'type' => 'month',
                     ),
                 'amount' => 10,
                 'currency' => 'USD',
             ),
         'expiration' =>
             array (
                 'value' => '',
                 'type' => '',
             ),
         'tags' =>
             array (
                 'tag1',
                 'tag2',
                 'tag3',
             ),
     )
));
PUT /merchant/v2/projects/{project_id}/subscriptions/plans/{plan_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "external_id": "sample_plan",
    "name": {
        "en": "Sample Plan"
    },
    "description": {
        "en": "Basic options plan"
    },
    "charge": {
        "period": {
            "value": 1,
            "type": "month"
        },
        "amount": 10,
        "currency": "USD"
    },
    "expiration": {
        "value": "",
        "type": ""
    },
    "tags": [
      "tag1",
      "tag2",
      "tag3"
    ]
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/plans/{plan_id}' \
-X PUT \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "external_id": "sample_plan",
    "name": {
        "en": "Sample Plan"
    },
    "description": {
        "en": "Basic options plan"
    },
    "charge": {
        "period": {
            "value": 1,
            "type": "month"
        },
        "amount": 10,
        "currency": "USD"
    },
    "expiration": {
        "value": "",
        "type": ""
    },
    "tags": [
      "tag1",
      "tag2",
      "tag3"
    ]
}'
Response
<?php

// example response
$response = array (
    'id' => '54',
    'external_id' => 'sample_plan',
    'name' =>
        array (
            'en' => 'Sample Plan'
        ),
    'description' =>
        array (
            'en' => 'Basic options plan'
        ),
    'charge' =>
        array (
            'period' =>
                array (
                    'value' => 1,
                    'type' => 'month'
                ),
            'amount' => 10,
            'currency' => 'USD'
        ),
    'expiration' =>
        array (
            'value' => '',
            'type' => ''
        ),
    'trial' =>
        array (
            'value' => 14,
            'type' => 'day'
        ),
    'status' =>
        array (
            'value' => 'disabled',
            'counters' =>
                array (
                    'active' => 0,
                    'canceled' => 0,
                    'expired' => 0
                )
        )
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "54",
    "external_id": "sample_plan",
    "name": {
        "en": "Sample Plan"
    },
    "description": {
        "en": "Basic options plan"
    },
    "charge": {
        "period": {
            "value": 1,
            "type": "month"
        },
        "amount": 10,
        "currency": "USD"
    },
    "expiration": {
        "value": "",
        "type": ""
    },
    "trial": {
        "value": 14,
        "type": "day"
    },
    "status": {
        "value": "disabled",
        "counters": {
            "active": 0,
            "canceled": 0,
            "expired": 0
        }
    }
}
{
    "id": "54",
    "external_id": "sample_plan",
    "name": {
        "en": "Sample Plan"
    },
    "description": {
        "en": "Basic options plan"
    },
    "charge": {
        "period": {
            "value": 1,
            "type": "month"
        },
        "amount": 10,
        "currency": "USD"
    },
    "expiration": {
        "value": "",
        "type": ""
    },
    "trial": {
        "value": 14,
        "type": "day"
    },
    "status": {
        "value": "disabled",
        "counters": {
            "active": 0,
            "canceled": 0,
            "expired": 0
        }
    },
    "type":
}

Enable Plan

Enables a subscription plan.

HTTP REQUEST

PATCH https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/plans/{plan_id}

Parameter Type Description
project_id
integer Project ID.
plan_id
integer Plan ID.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->EnableSubscriptionPlan(array(
    'project_id' => PROJECT_ID,
    'plan_id' => PLAN_ID
));
PATCH /merchant/v2/projects/{project_id}/subscriptions/plans/{plan_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/plans/{plan_id}' \
-X PATCH \
-u merchant_id:merchant_api_key
Response
<?php

$response = null;
HTTP/1.1 204 No Content

Disable Plan

Disables a subscription plan.

HTTP REQUEST

DELETE https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/plans/{plan_id}

Parameter Type Description
project_id
integer Project ID.
plan_id
integer Plan ID.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->DisableSubscriptionPlan(array(
    'project_id' => PROJECT_ID,
    'plan_id' => PLAN_ID
));
DELETE /merchant/v2/projects/{project_id}/subscriptions/plans/{plan_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/plans/{plan_id}' \
-X DELETE \
-u merchant_id:merchant_api_key
Response
<?php

$response = null;
HTTP/1.1 204 No Content

Delete Plan

Deletes a subscription plan.

HTTP REQUEST

DELETE https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/plans/{plan_id}/delete

Parameter Type Description
project_id
integer Project ID.
plan_id
integer Plan ID.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->DeleteSubscriptionPlan(array(
    'project_id' => PROJECT_ID,
    'plan_id' => PLAN_ID
));
DELETE /merchant/v2/projects/{project_id}/subscriptions/plans/{plan_id}/delete HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/plans/{plan_id}/delete' \
-X DELETE \
-u merchant_id:merchant_api_key
Response
<?php

$response = null;
HTTP/1.1 204 No Content

Get Plans

Lists all subscription plans.

HTTP REQUEST

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/plans

Parameter Type Description
project_id
integer Project ID.
external_id
string Plan external ID (32 characters).
limit
integer Limit for the number of elements on the page.
offset
integer Number of the element from which the list is generated (the count starts from 0).
group_id
string Group ID the plans are linked to.
product_id
integer Product ID the plans are linked to.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->ListSubscriptionPlans(array(
    'project_id' => PROJECT_ID
));
GET /merchant/v2/projects/{project_id}/subscriptions/plans?external_id=1&limit=1&offset=1 HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/plans?external_id=1&limit=1&offset=1' \
-X GET \
-u merchant_id:merchant_api_key
Response
<?php

// example response
$response = array (
    array (
        'id' => '54',
        'external_id' => 'sample_plan',
        'name' =>
            array (
                'en' => 'Sample Plan'
            ),
        'description' =>
            array (
                'en' => 'Basic options plan'
            ),
        'group_id' => 'USA Products',
        'charge' =>
            array (
                'period' =>
                    array (
                        'value' => 1,
                        'type' => 'month'
                    ),
                'amount' => 10,
                'currency' => 'USD'
            ),
        'expiration' =>
            array (
                'value' => 90,
                'type' => 'day'
            ),
        'trial' =>
            array (
                'value' => 14,
                'type' => 'day'
            ),
        'tags' =>
            array (
                'tag1',
                'tag2',
                'tag3'
            ),
        'status' =>
            array (
                'value' => 'disabled',
                'counters' =>
                    array (
                        'active' => 0,
                        'canceled' => 0,
                        'expired' => 0
                    )
            )
    )
);
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": "54",
        "external_id": "sample_plan",
        "name": {
            "en": "Sample Plan"
        },
        "description": {
            "en": "Basic options plan"
        },
        "group_id": "USA Products",
        "charge": {
            "period": {
                "value": 1,
                "type": "month"
            },
            "amount": 10,
            "currency": "USD"
        },
        "expiration": {
            "value": 90,
            "type": "day"
        },
        "trial": {
            "value": 14,
            "type": "day"
        },
        "tags": [
          "tag1",
          "tag2",
          "tag3"
        ],
        "status": {
            "value": "disabled",
            "counters": {
                "active": 0,
                "canceled": 0,
                "expired": 0
            }
        }
    }
]
[
    {
        "id": "54",
        "external_id": "sample_plan",
        "name": {
            "en": "Sample Plan"
        },
        "description": {
            "en": "Basic options plan"
        },
        "group_id": "USA Products",
        "charge": {
            "period": {
                "value": 1,
                "type": "month"
            },
            "amount": 10,
            "currency": "USD",
        },
        "expiration": {
            "value": 90,
            "type": "day",
        },
        "trial": {
            "value": 14,
            "type": "day"
        },
        "tags": [
          "tag1",
          "tag2",
          "tag3"
        ],
        "status": {
            "value": "disabled",
            "counters": {
                "active": 0,
                "canceled": 0,
                "expired": 0
            }
        }
    }
]

Create Product

Creates a subscription-based product.

HTTP REQUEST

POST https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/products

Parameter Type Description
project_id
integer Project ID.
name
string Product name.
group_id
string Group ID the plans are linked to.
description
string Localized item descriptions (array).
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->CreateSubscriptionProduct(array(
    'project_id' => PROJECT_ID,
    'request' => array(
        'name' => 'Demo Product',
        'group_id' => 'USA Products',
        "description": {
            "en": "USA Products"
          }
    ),
));
POST /merchant/v2/projects/{project_id}/subscriptions/products HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "name": "Demo Product",
    "group_id": "USA Products",
    "description": {
        "en": "USA Products"
      }
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/products' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
        "name": "Demo Product",
        "group_id": "USA Products",
        "description": {
            "en": "USA Products"
          }
    }'
Response
<?php

// example response
$response = array (
    'product_id' => '64'
);
HTTP/1.1 201 Created
Content-Type: application/json

{
    "product_id": "64"
}
{
    "product_id": "64"
}

Update Product

Updates a subscription-based product.

HTTP REQUEST

PUT https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/products/{product_id}

Parameter Type Description
project_id
integer Project ID.
product_id
integer Product ID the plans are linked to.
name
string Product name.
group_id
string Group ID the plans are linked to.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->UpdateSubscriptionProduct(array(
    'project_id' => PROJECT_ID,
    'request' => array(
        'name' => 'Demo Product',
        'group_id' => 'USA Products'
    ),
));
PUT /merchant/v2/projects/{project_id}/subscriptions/products/{product_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
        "name": "Demo Product",
        "group_id": "USA Products"
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/products/{product_id}' \
-X PUT \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
            "name": "Demo Product",
            "group_id": "USA Products"
    }'
Response
<?php

// example response
$response = array (
    'id' => '64',
    'name' => 'Demo Product',
    'group_id' => 'USA Products'
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "64",
    "name": "Demo Product",
    "group_id": "USA Products"
}
{
    "id": "64",
    "name": "Demo Product",
    "group_id": "USA Products"
}

Delete Product

Deletes a subscription-based product.

HTTP REQUEST

DELETE https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/products/{product_id}

Parameter Type Description
project_id
integer Project ID.
product_id
integer Product ID the plans are linked to.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->DeleteSubscriptionProduct(array(
    'project_id' => PROJECT_ID,
    'product_id' => PRODUCT_ID
));
DELETE /merchant/v2/projects/{project_id}/subscriptions/products/{product_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/products/{product_id}' \
-X DELETE \
-u merchant_id:merchant_api_key
Response
<?php

$response = null;
HTTP/1.1 204 No Content

Get Products

Lists all subscription-based products.

HTTP REQUEST

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/products

Parameter Type Description
project_id
integer Project ID.
group_id
string Group ID the plans are linked to.
product_id
integer Product ID the plans are linked to.
limit
integer Limit for the number of elements on the page.
offset
integer Number of the element from which the list is generated (the count starts from 0).
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->DeleteSubscriptionProduct(array(
    'project_id' => PROJECT_ID
));
GET /merchant/v2/projects/{project_id}/subscriptions/products?group_id=USA%20Products&limit=1&offset=1 HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/products?group_id=USA%20Products&limit=1&offset=1' \
-X GET \
-u merchant_id:merchant_api_key
Response
<?php

// example response
$response = array (
    array (
        'id' => 3,
        'group_id' => 'USA Products',
        'name' => 'Demo Product'
    )
);
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": 3,
        "group_id": "USA Products",
        "name": "Demo Product"
    }
]
[
    {
        "id": 3,
        "group_id": "USA Products",
        "name": "Demo Product"
    }
]

Get Subscription

Gets a specific subscription details by ID.

HTTP REQUEST

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/{subscription_id}

Parameter Type Description
project_id
integer Project ID. Required.
subscription_id
integer Subscription ID. Required.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

<?php
$request['project_id']=PROJECT_ID;
$request['subscription_id']=SUBSCRIPTION_ID;
GET https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/{subscription_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/{subscription_id}' \
-X GET \
-u merchant_id:merchant_api_key
Response
<?php
$response = array(
    'id' => 5096406,
    'user' =>
        array(
            'id' => 5096406,
            'name' => null,
        ),
    'plan' =>
        array(
            'id' => 123,
            'external_id' => 'a1s2d3'
        ),
    'product' =>
        array(
            'id' => 123
            'id_group' => 1234,
            'name' => 'product_name'
        ),
    'charge_amount' => 14.99,
    'currency' => ‘USD’,
    'date_create' => ‘2010-04-09T04:58:49+0400,
    'date_end' => null,
    'date_last_charge' => ‘2010-04-09T04:58:49+0400,
    'date_next_charge' => ‘2025-03-31T00:00:00+0300,
    'status' => ‘non_renewing’,
    'comment' => null
);
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 5096406,
  "user": {
    "id": "23KM3QP",
    "name": null
  },
  "plan": {
    "id": 123,
    "external_id": "a1s2d3"
  },
  "product": {
    "id": 123,
    "id_group": 1234,
    "name": "product_name"
  },
  "charge_amount": 14.99,
  "currency": "USD",
  "date_create": "2010-04-09T04:58:49+0400",
  "date_end": null,
  "date_last_charge": "2010-04-09T04:58:49+0400",
  "date_next_charge": "2025-03-31T00:00:00+0300",
  "status": "non_renewing",
  "comment": null
}
{
  "id": 5096406,
  "user": {
    "id": "23KM3QP",
    "name": null
  },
  "plan": {
    "id": 123,
    "external_id": "a1s2d3"
  },
  "product": {
    "id": 123,
    "id_group": 1234,
    "name": "product_name"
  },
  "charge_amount": 14.99,
  "currency": "USD",
  "date_create": "2010-04-09T04:58:49+0400",
  "date_end": null,
  "date_last_charge": "2010-04-09T04:58:49+0400",
  "date_next_charge": "2025-03-31T00:00:00+0300",
  "status": "non_renewing",
  "comment": null
}

Update Subscription

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

HTTP REQUEST

PUT https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/subscriptions/{subscription_id}

Parameter Type Description
project_id
integer Project ID.
subscription_id
integer Subscription ID.
user_id
string User ID.
status
string Status: active/canceled/non_renewing.
cancel_subscription_payment
boolean Setting to true will refund the last payment made for this subscription. Only works together with setting the status to canceled.
timeshift
object Billing postponement
timeshift.value
string Number of time units to postpone the billing by. Setting to a negative value will bring the billing forward.
timeshift.type
string Time unit: day/month.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->UpdateSubscription(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID,
    'subscription_id' => SUBSCRIPTION_ID,
    'request' => array (
         'status' => 'canceled',
         'timeshift' =>
             array (
                 'value' => '30',
                 'type' => 'day',
             )
    )
));
PUT /merchant/v2/projects/{project_id}/users/{user_id}/subscriptions/{subscription_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "status": "canceled",
    "timeshift": {
         "value": "30",
         "type": "day"
    }
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/subscriptions/{subscription_id}' \
-X PUT \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "status": "canceled",
    "timeshift": {
         "value": "30",
         "type": "day"
    }
}'
Response
<?php

// example response
$response = array (
    'id' => 45,
    'plan' =>
        array (
            'id' => '54',
            'external_id' => 'sample_plan',
            'group_id' => 'USA Products',
            'project_id' => 14004,
            'name' =>
                array (
                    'en' => 'Sample Plan'
                ),
            'description' =>
                array (
                    'en' => 'Basic options plan'
                ),
            'localized_name' => 'Basic Plan',
            'charge' =>
                array (
                    'period' =>
                        array (
                            'value' => 1,
                            'type' => 'month'
                        ),
                    'amount' => 10,
                    'currency' => 'USD'
                ),
            'expiration' =>
                array (
                    'value' => 90,
                    'type' => 'day'
                ),
            'trial' =>
                array (
                    'value' => 14,
                    'type' => 'day'
                ),
            'status' =>
                array (
                    'value' => 'active',
                    'counters' =>
                        array (
                            'active' => 0,
                            'canceled' => 1,
                            'expired' => 0
                        )
                )
        ),
    'user' =>
        array (
            'id' => '20',
        ),
    'product' => null,
    'charge_amount' => 10,
    'currency' => 'USD',
    'date_create' => '2014-09-30T15:34:17+06:00',
    'date_end' => '2014-10-07T15:34:17+06:00',
    'date_last_charge' => '2014-10-01T15:34:17+06:00',
    'date_next_charge' => '2014-11-01T15:34:17+06:00',
    'status' => 'canceled'
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 45,
    "plan": {
        "id": "54",
        "external_id": "sample_plan",
        "group_id": "USA Products",
        "project_id": 14004,
        "name": {
                "en": "Sample Plan"
        },
        "description": {
            "en": "Basic options plan"
        },
        "localized_name": "Basic Plan",
        "charge": {
            "period": {
                "value": 1,
                "type": "month"
            },
            "amount": 10,
            "currency": "USD"
        },
        "expiration": {
            "value": 90,
            "type": "day"
        },
        "trial": {
            "value": 14,
            "type": "day"
        },
        "status": {
            "value": "active",
            "counters": {
                "active": 0,
                "canceled": 1,
                "expired": 0
            }
        }
    },
    "user": {
        "id": "20"
    },
    "product": null,
    "charge_amount": 10,
    "currency": "USD",
    "date_create": "2014-09-30T15:34:17+06:00",
    "date_end": "2014-10-07T15:34:17+06:00",
    "date_last_charge": "2014-10-01T15:34:17+06:00",
    "date_next_charge": "2014-11-01T15:34:17+06:00",
    "status": "canceled"
}
{
    "id": 45,
    "plan": {
        "id": "54",
        "external_id": "sample_plan",
        "group_id": "USA Products",
        "project_id": 14004,
        "name": {
            "en": "Sample Plan"
        },
        "description": {
            "en": "Basic options plan"
        },
        "localized_name": "Basic Plan",
        "charge": {
            "period": {
                "value": 1,
                "type": "month"
            },
            "amount": 10,
            "currency": "USD"
        },
        "expiration": {
            "value": 90,
            "type": "day"
        },
        "trial": {
            "value": 14,
            "type": "day"
        },
        "status": {
            "value": "active",
            "counters": {
                "active": 0,
                "canceled": 1,
                "expired": 0
            }
        }
    },
    "user": {
        "id": "20"
    },
    "product": null,
    "charge_amount": 10,
    "currency": "USD",
    "date_create": "2014-09-30T15:34:17+06:00",
    "date_end": "2014-10-07T15:34:17+06:00",
    "date_last_charge": "2014-10-01T15:34:17+06:00",
    "date_next_charge": "2014-11-01T15:34:17+06:00",
    "status": "canceled"
}

Get Subscriptions

Lists all recurrent subscriptions.

HTTP REQUEST

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/plans/{plan_id}/subscriptions

Parameter Type Description
project_id
integer Project ID. Required.
user_id
string User ID. Required.
status
string Status: active/canceled/non_renewing.
limit
integer Limit for the number of elements on the page.
offset
integer Number of the element from which the list is generated (the count starts from 0).
datetime_from
datetime Period start.
datetime_to
datetime Period end.
plan_id
integer Plan ID.
product_id
integer Product ID the plans are linked to.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->ListSubscriptions(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID
));
GET /merchant/v2/projects/{project_id}/plans/{plan_id}/subscriptions?status=active&limit=1&offset=1&datetime_from=2014-10-01T00%3A00%3A00Z&datetime_to=2014-10-02T00%3A00%3A00Z HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/plans/{plan_id}/subscriptions?status=active&limit=1&offset=1&datetime_from=2014-10-01T00%3A00%3A00Z&datetime_to=2014-10-02T00%3A00%3A00Z' \
-X GET \
-u merchant_id:merchant_api_key
Response
<?php

// example response
$response = array (
  array (
0 => 
stdClass::__set_state(array(
   'id' => 5096406,
   'user' =>
  stdClass::__set_state(array(
     'id' => '23KM3QP',
     'name' => NULL,
  )),
   'product' => NULL,
   'charge_amount' => 14.99,
   'currency' => 'USD',
   'date_create' => '2010-04-09T04:58:49+0400',
   'date_end' => NULL,
   'date_last_charge' => '2010-04-09T04:58:49+0400',
   'date_next_charge' => '2025-03-31T00:00:00+0300',
   'status' => 'non_renewing',
   'comment' => NULL,
)),
1 =>
stdClass::__set_state(array(
   'id' => 5096405,
   'user' =>
  stdClass::__set_state(array(
     'id' => '2EH93HFYE',
     'name' => NULL,
  )),
   'product' => NULL,
   'charge_amount' => 14.99,
   'currency' => 'USD',
   'date_create' => '2010-01-05T13:59:48+0300',
   'date_end' => NULL,
   'date_last_charge' => '2010-01-05T13:59:48+0300',
   'date_next_charge' => '2038-01-01T00:00:00+0300',
   'status' => 'non_renewing',
   'comment' => NULL,
)),
)
HTTP/1.1 200 OK
Content-Type: application/json

[
  {
      "id": 5096406,
      "user": {
          "id": "23KM3QP",
          "name": null
      },
      "product": null,
      "charge_amount": 14.99,
      "currency": "USD",
      "date_create": "2010-04-09T04:58:49+0400",
      "date_end": null,
      "date_last_charge": "2010-04-09T04:58:49+0400",
      "date_next_charge": "2025-03-31T00:00:00+0300",
      "status": "non_renewing",
      "comment": null
  },
  {
      "id": 5096405,
      "user": {
          "id": "2EH93HFYE",
          "name": null
      },
      "product": null,
      "charge_amount": 14.99,
      "currency": "USD",
      "date_create": "2010-01-05T13:59:48+0300",
      "date_end": null,
      "date_last_charge": "2010-01-05T13:59:48+0300",
      "date_next_charge": "2038-01-01T00:00:00+0300",
      "status": "non_renewing",
      "comment": null
  }
]
[
  {
      "id": 5096406,
      "user": {
          "id": "23KM3QP",
          "name": null
      },
      "product": null,
      "charge_amount": 14.99,
      "currency": "USD",
      "date_create": "2010-04-09T04:58:49+0400",
      "date_end": null,
      "date_last_charge": "2010-04-09T04:58:49+0400",
      "date_next_charge": "2025-03-31T00:00:00+0300",
      "status": "non_renewing",
      "comment": null
  },
  {
      "id": 5096405,
      "user": {
          "id": "2EH93HFYE",
          "name": null
      },
      "product": null,
      "charge_amount": 14.99,
      "currency": "USD",
      "date_create": "2010-01-05T13:59:48+0300",
      "date_end": null,
      "date_last_charge": "2010-01-05T13:59:48+0300",
      "date_next_charge": "2038-01-01T00:00:00+0300",
      "status": "non_renewing",
      "comment": null
  }
]

Get Payments

Lists all subscription payments.

HTTP REQUEST

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/payments

Parameter Type Description
project_id
integer Project ID.
user_id
string User ID.
status
string Status: processing/canceled/done.
limit
integer Limit for the number of elements on the page.
offset
integer Number of the element from which the list is generated (the count starts from 0).
datetime_from
datetime Period start.
datetime_to
datetime Period end.
subscription_id
integer Subscription ID.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->ListSubscriptionPayments(array(
    'project_id' => PROJECT_ID
));
GET /merchant/v2/projects/{project_id}/subscriptions/payments?status=done&limit=1&offset=1&datetime_from=2014-10-01T00%3A00%3A00Z&datetime_to=2014-10-02T00%3A00%3A00Z HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/payments?status=done&limit=1&offset=1&datetime_from=2014-10-01T00%3A00%3A00Z&datetime_to=2014-10-02T00%3A00%3A00Z' \
-X GET \
-u merchant_id:merchant_api_key
Response
<?php

// example response
$response = array (
    array (
        'id' => 35,
        'id_payment' => 118441192,
        'date_payment' => '2014-09-30T15:34:17+04:00',
        'status' => 'done',
        'subscription' =>
            array (
                'id' => 45,
                'plan' =>
                    array (
                        'id' => '54',
                        'external_id' => 'sample_plan',
                        'group_id' => 'USA Products',
                        'name' =>
                            array (
                                'en' => 'Sample Plan'
                            ),
                        'description' =>
                            array (
                                'en' => 'Basic options plan'
                            ),
                        'localized_name' => 'Basic Plan',
                        'charge' =>
                            array (
                                'period' =>
                                    array (
                                        'value' => 1,
                                        'type' => 'month'
                                    ),
                                'amount' => 10,
                                'currency' => 'USD'
                            ),
                        'expiration' =>
                            array (
                                'value' => 90,
                                'type' => 'day'
                            ),
                        'trial' =>
                            array (
                                'value' => 14,
                                'type' => 'day'
                            ),
                        'status' =>
                            array (
                                'value' => 'disabled',
                                'counters' =>
                                    array (
                                        'active' => 0,
                                        'closed' => 0,
                                        'expired' => 0
                                    )
                            )
                    ),
                'user' =>
                    array (
                        'id' => 20,
                        'name' => 'John Smith'
                    ),
                'product' => null,
                'charge_amount' => 10,
                'currency' => 'USD',
                'date_create' => '2014-09-30T15:34:17+04:00',
                'date_end' => '2014-10-07T15:34:17+04:00',
                'date_last_charge' => '2014-10-01T15:34:17+04:00',
                'date_next_charge' => '2014-11-01T15:34:17+04:00',
                'status' => 'done'
            )
    )
);
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": 35,
        "id_payment": 118441192,
        "date_payment": "2014-09-30T15:34:17+04:00",
        "status": "done",
        "subscription": {
            "id": 45,
            "plan": {
                "id": "54",
                "external_id": "sample_plan",
                "group_id": "USA Products",
                "name": {
                    "en": "Sample Plan"
                },
                "description": {
                    "en": "Basic options plan"
                },
                "localized_name": "Basic Plan",
                "charge": {
                    "period": {
                        "value": 1,
                        "type": "month"
                    },
                    "amount": 10,
                    "currency": "USD"
                },
                "expiration": {
                    "value": 90,
                    "type": "day"
                },
                "trial": {
                    "value": 14,
                    "type": "day"
                },
                "status": {
                    "value": "disabled",
                    "counters": {
                        "active": 0,
                        "closed": 0,
                        "expired": 0
                    }
                }
            },
            "user": {
                "id": 20,
                "name": "John Smith"
            },
            "product": null,
            "charge_amount": 10,
            "currency": "USD",
            "date_create": "2014-09-30T15:34:17+04:00",
            "date_end": "2014-10-07T15:34:17+04:00",
            "date_last_charge": "2014-10-01T15:34:17+04:00",
            "date_next_charge": "2014-11-01T15:34:17+04:00",
            "status": "done"
        }
    }
]
[
    {
        "id": 35,
        "id_payment": 118441192,
        "date_payment": "2014-09-30T15:34:17+04:00",
        "status": "done",
        "subscription": {
            "id": 45,
            "plan": {
                "id": "54",
                "external_id": "sample_plan",
                "group_id": "USA Products",
                "name": {
                    "en": "Sample Plan"
                },
                "description": {
                    "en": "Basic options plan"
                },
                "localized_name": "Basic Plan",
                "charge": {
                    "period": {
                        "value": 1,
                        "type": "month"
                    },
                    "amount": 10,
                    "currency": "USD"
                },
                "expiration": {
                    "value": 90,
                    "type": "day"
                },
                "trial": {
                    "value": 14,
                    "type": "day"
                },
                "status": {
                    "value": "disabled",
                    "counters": {
                        "active": 0,
                        "closed": 0,
                        "expired": 0
                    }
                }
            },
            "user": {
                "id": 20,
                "name": "John Smith"
            },
            "product": null,
            "charge_amount": 10,
            "currency": "USD",
            "date_create": "2014-09-30T15:34:17+04:00",
            "date_end": "2014-10-07T15:34:17+04:00",
            "date_last_charge": "2014-10-01T15:34:17+04:00",
            "date_next_charge": "2014-11-01T15:34:17+04:00",
            "status": "done"
        }
    }
]

Get User Payments

Lists all payments made by a specific user.

HTTP REQUEST

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/subscriptions/payments

Parameter Type Description
project_id
integer Project ID.
user_id
string User ID.
status
string Status: processing/canceled/done.
limit
integer Limit for the number of elements on the page.
offset
integer Number of the element from which the list is generated (the count starts from 0).
datetime_from
datetime Period start.
datetime_to
datetime Period end.
subscription_id
integer Subscription ID.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->ListUserSubscriptionPayments(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID
));
GET /merchant/v2/projects/{project_id}/users/{user_id}/subscriptions/payments?status=done&limit=1&offset=1&datetime_from=2014-10-01T00%3A00%3A00Z&datetime_to=2014-10-02T00%3A00%3A00Z HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/subscriptions/payments?status=done&limit=1&offset=1&datetime_from=2014-10-01T00%3A00%3A00Z&datetime_to=2014-10-02T00%3A00%3A00Z' \
-X GET \
-u merchant_id:merchant_api_key
Response
<?php

// example response
$response = array (
    array (
        'id' => 35,
        'id_payment' => 118441192,
        'date_payment' => '2014-09-30T15:34:17+04:00',
        'status' => 'done',
        'subscription' =>
            array (
                'id' => 45,
                'plan' =>
                    array (
                        'id' => '54',
                        'external_id' => 'sample_plan',
                        'group_id' => 'USA Products',
                        'project_id' => 14004,
                        'name' =>
                            array (
                                'en' => 'Sample Plan'
                            ),
                        'description' =>
                            array (
                                'en' => 'Basic options plan'
                            ),
                        'localized_name' => 'Basic Plan',
                        'charge' =>
                            array (
                                'period' =>
                                    array (
                                        'value' => 1,
                                        'type' => 'month'
                                    ),
                                'amount' => 10,
                                'currency' => 'USD'
                            ),
                        'expiration' =>
                            array (
                                'value' => 90,
                                'type' => 'day'
                            ),
                        'trial' =>
                            array (
                                'value' => 14,
                                'type' => 'day'
                            ),
                        'status' =>
                            array (
                                'value' => 'disabled',
                                'counters' =>
                                    array (
                                        'active' => 0,
                                        'closed' => 0,
                                        'expired' => 0
                                    )
                            )
                    ),
                'user' =>
                    array (
                        'id' => 20,
                        'name' => 'John Smith'
                    ),
                'product' => null,
                'charge_amount' => 10,
                'currency' => 'USD',
                'date_create' => '2014-09-30T15:34:17+04:00',
                'date_end' => '2014-10-07T15:34:17+04:00',
                'date_last_charge' => '2014-10-01T15:34:17+04:00',
                'date_next_charge' => '2014-11-01T15:34:17+04:00',
                'status' => 'done'
            )
    )
);
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": 35,
        "id_payment": 118441192,
        "date_payment": "2014-09-30T15:34:17+04:00",
        "status": "done",
        "subscription": {
            "id": 45,
            "plan": {
                "id": "54",
                "external_id": "sample_plan",
                "group_id": "USA Products",
                "project_id": 14004,
                "name": {
                    "en": "Sample Plan"
                },
                "description": {
                    "en": "Basic options plan"
                },
                "localized_name": "Basic Plan",
                "charge": {
                    "period": {
                        "value": 1,
                        "type": "month"
                    },
                    "amount": 10,
                    "currency": "USD"
                },
                "expiration": {
                    "value": 90,
                    "type": "day"
                },
                "trial": {
                    "value": 14,
                    "type": "day"
                },
                "status": {
                    "value": "disabled",
                    "counters": {
                        "active": 0,
                        "closed": 0,
                        "expired": 0
                    }
                }
            },
            "user": {
                "id": 20,
                "name": "John Smith"
            },
            "product": null,
            "charge_amount": 10,
            "currency": "USD",
            "date_create": "2014-09-30T15:34:17+04:00",
            "date_end": "2014-10-07T15:34:17+04:00",
            "date_last_charge": "2014-10-01T15:34:17+04:00",
            "date_next_charge": "2014-11-01T15:34:17+04:00",
            "status": "done"
        }
    }
]
[
    {
        "id": 35,
        "id_payment": 118441192,
        "date_payment": "2014-09-30T15:34:17+04:00",
        "status": "done",
        "subscription": {
            "id": 45,
            "plan": {
                "id": "54",
                "external_id": "sample_plan",
                "group_id": "USA Products",
                "project_id": 14004,
                "name": {
                    "en": "Sample Plan"
                },
                "description": {
                    "en": "Basic options plan"
                },
                "localized_name": "Basic Plan",
                "charge": {
                    "period": {
                        "value": 1,
                        "type": "month"
                    },
                    "amount": 10,
                    "currency": "USD"
                },
                "expiration": {
                    "value": 90,
                    "type": "day"
                },
                "trial": {
                    "value": 14,
                    "type": "day"
                },
                "status": {
                    "value": "disabled",
                    "counters": {
                        "active": 0,
                        "closed": 0,
                        "expired": 0
                    }
                }
            },
            "user": {
                "id": 20,
                "name": "John Smith"
            },
            "product": null,
            "charge_amount": 10,
            "currency": "USD",
            "date_create": "2014-09-30T15:34:17+04:00",
            "date_end": "2014-10-07T15:34:17+04:00",
            "date_last_charge": "2014-10-01T15:34:17+04:00",
            "date_next_charge": "2014-11-01T15:34:17+04:00",
            "status": "done"
        }
    }
]

Get Currencies

Lists all supported subscription currencies.

HTTP REQUEST

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/currencies

Parameter Type Description
project_id
integer Project ID.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->ListSubscriptionCurrencies(array(
    'project_id' => PROJECT_ID
));
GET /merchant/v2/projects/{project_id}/subscriptions/currencies HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/currencies' \
-X GET \
-u merchant_id:merchant_api_key
Response
<?php

// example response
$response = array(
    "AED",
    "ALL",
    "AMD",
    "ARS",
    "AUD",
    "AZN",
    "BGN",
    "BRL",
    "BYR",
    "CAD",
    "CHF",
    "CLP",
    "CNY",
    "COP",
    "CZK",
    "DKK",
    "DZD",
    "EGP",
    "EUR",
    "GBP",
    "GEL",
    "HKD",
    "HRK",
    "HUF",
    "IDR",
    "ILS",
    "INR",
    "JPY",
    "KES",
    "KGS",
    "KRW",
    "KZT",
    "MAD",
    "MDL",
    "MKD",
    "MNT",
    "MXN",
    "MYR",
    "NGN",
    "NOK",
    "NZD",
    "PEN",
    "PHP",
    "PKR",
    "PLN",
    "RON",
    "RSD",
    "RUB",
    "SAR",
    "SEK",
    "SGD",
    "THB",
    "TRY",
    "UAH",
    "USD",
    "UYU",
    "UZS",
    "VND",
    "ZAR"
);
HTTP/1.1 200 OK
Content-Type: application/json

[
    "AED",
    "ALL",
    "AMD",
    "ARS",
    "AUD",
    "AZN",
    "BGN",
    "BRL",
    "BYR",
    "CAD",
    "CHF",
    "CLP",
    "CNY",
    "COP",
    "CZK",
    "DKK",
    "DZD",
    "EGP",
    "EUR",
    "GBP",
    "GEL",
    "HKD",
    "HRK",
    "HUF",
    "IDR",
    "ILS",
    "INR",
    "JPY",
    "KES",
    "KGS",
    "KRW",
    "KZT",
    "MAD",
    "MDL",
    "MKD",
    "MNT",
    "MXN",
    "MYR",
    "NGN",
    "NOK",
    "NZD",
    "PEN",
    "PHP",
    "PKR",
    "PLN",
    "RON",
    "RSD",
    "RUB",
    "SAR",
    "SEK",
    "SGD",
    "THB",
    "TRY",
    "UAH",
    "USD",
    "UYU",
    "UZS",
    "VND",
    "ZAR"
]
[
    "AED",
    "ALL",
    "AMD",
    "ARS",
    "AUD",
    "AZN",
    "BGN",
    "BRL",
    "BYR",
    "CAD",
    "CHF",
    "CLP",
    "CNY",
    "COP",
    "CZK",
    "DKK",
    "DZD",
    "EGP",
    "EUR",
    "GBP",
    "GEL",
    "HKD",
    "HRK",
    "HUF",
    "IDR",
    "ILS",
    "INR",
    "JPY",
    "KES",
    "KGS",
    "KRW",
    "KZT",
    "MAD",
    "MDL",
    "MKD",
    "MNT",
    "MXN",
    "MYR",
    "NGN",
    "NOK",
    "NZD",
    "PEN",
    "PHP",
    "PKR",
    "PLN",
    "RON",
    "RSD",
    "RUB",
    "SAR",
    "SEK",
    "SGD",
    "THB",
    "TRY",
    "UAH",
    "USD",
    "UYU",
    "UZS",
    "VND",
    "ZAR"
]

Game Keys

Create Entity

Creates a game delivery entity.

HTTP REQUEST

POST https://api.xsolla.com/merchant/v2/projects/{project_id}/game_delivery

Parameter Type Description
project_id
integer Project ID.
sku
string Unique ID. The SKU may only contain lowercase Latin alphanumeric characters, dashes, and underscores.
name
object Array of localized names of the game delivery entity.
description
object Array of localized descriptions of the game delivery entity.
system_requirements
string System requirements for the game.
image_url
string Image URL. Optional.
long_description
string Extended description of the game delivery entity. Optional.
locales_list
string Comma-separated list of localizations. Optional.
publisher
string Game publisher. Optional.
developer
string Game developer. Optional.
string Link to a video featuring the game. Optional.
genre
string Game genre. Optional.
additional_info
string Additional info about the game. Optional.
string Link to a discussion forum. Optional.
string Link to a support page. Optional.
old_price
string Old price of the game. Optional.
parent_id
integer ID of a parent game. Optional.
default_currency
string Default purchase currency. Three-letter currency code per ISO 4217.
delivery
object Data on the delivery of preordered keys.
delivery.release_date_type
string Type of release date. Can be set to a specific UTC date or a quarter & year. In the latter case, ‘delivery.release_date_type’ is set to the last day of the specified quarter.
delivery.delivery_method
string Key delivery method.
delivery.delivery_method.default
string Default key delivery method.
delivery.delivery_method.exception
string Exceptions to key delivery methods.
release_date
string Expected date of release. Optional.
drm
array Array with DRM data.
drm.id
integer ID of an available DRM.
drm.name
integer DRM name.
drm.prices
array Array of game prices for DRM. Optional.
drm.codes
array Key array for DRM. Optional.
drm.codes.total
string Total number of keys. Optional.
drm.codes.active
string Number of active keys. Optional.
drm.codes.used
string Number of used keys. Optional.
drm.platforms
array Array with data about DRM platforms.
drm.platforms.id
integer Platform ID for that DRM.
drm.enabled
boolean Whether DRM is in use for this game.
obtain_code_from_db
boolean Whether to use game keys from Xsolla database. Optional.
obtain_code_from_api
boolean Whether to use game keys received via API. Optional.
files
array Array of installation files for downloading. Optional.
files.name
string File name. Optional.
files.url
string URL for download. Optional.
tips_enabled
boolean Whether to enable tips for developers. Optional.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->CreateGameDeliveryEntity(array(
    'project_id' => PROJECT_ID,
    'request' =>  'sku' => 'GTA5',
   'name' =>
  stdClass::__set_state(array(
     'en' => 'GTA V',
  )),
   'description' =>
  stdClass::__set_state(array(
     'en' => 'Grand Theft Auto V is an open world, action-adventure video game developed by Rockstar North and published by Rockstar Games.',
  )),
   'system_requirements' => 'OS: Windows 8.1 64 Bit, Windows 8 64 Bit, Windows 7 64 Bit Service Pack 1, Windows Vista 64 Bit Service Pack 2* (*NVIDIA video card recommended if running Vista OS)',
   'image_url' => '//cdn2.xsolla.com/img/misc/merchant/default-item.png',
   'long_description' => NULL,
   'locales_list' => NULL,
   'publisher' => NULL,
   'developer' => NULL,
   'video_link' => NULL,
   'genre' => NULL,
   'additional_info' => NULL,
   'forum_link' => NULL,
   'support_link' => NULL,
   'old_price' => NULL,
   'parent_id' => NULL,
   'default_currency' => 'EUR',
   'delivery' =>
  stdClass::__set_state(array(
     'release_date_type' => 'exact_date',
     'delivery_method' =>
    stdClass::__set_state(array(
       'default' =>
      array (
        0 => 'key',
      ),
       'exceptions' =>
      stdClass::__set_state(array(
         'drmfree' =>
        array (
          0 => 'link',
          1 => 'key',
        ),
         'steam' =>
        array (
          0 => 'link',
        ),
      )),
    )),
     'is_pre_order' => false,
     'is_partner_side_processing' => false,
  )),
   'release_date' => '2016-01-01T00:00:00+00:00',
   'drm' =>
  array (
    0 =>
    stdClass::__set_state(array(
       'id' => 1,
       'name' => 'Steam',
       'platforms' =>
      array (
        0 =>
        stdClass::__set_state(array(
           'id' => 1,
        )),
        1 =>
        stdClass::__set_state(array(
           'id' => 2,
        )),
      ),
       'prices' =>
      stdClass::__set_state(array(
         'USD' => 19.989999999999998,
         'EUR' => 18.5,
      )),
       'codes' =>
      stdClass::__set_state(array(
         'total' => 0,
         'active' => 0,
         'used' => 0,
      )),
       'enabled' => true,
    )),
  ),
   'obtain_code_from_api' => false,
   'obtain_code_from_db' => false,
   'files' =>
  array (
  ),
   'tips_enabled' => false,
));
POST /merchant/v2/projects/{project_id}/game_delivery HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "sku":"GTA5",
    "name":{
        "en":"GTA V"
    },
    "description":{
        "en":"Grand Theft Auto V is an open world, action-adventure video game developed by Rockstar North and published by Rockstar Games."
    },
    "system_requirements":"OS: Windows 8.1 64 Bit, Windows 8 64 Bit, Windows 7 64 Bit Service Pack 1, Windows Vista 64 Bit Service Pack 2* (*NVIDIA video card recommended if running Vista OS)",
    "image_url":"//cdn2.xsolla.com/img/misc/merchant/default-item.png",
    "long_description":null,
    "locales_list":null,
    "publisher":null,
    "developer":null,
    "video_link":null,
    "genre":null,
    "additional_info":null,
    "forum_link":null,
    "support_link":null,
    "old_price":null,
    "parent_id":null,
    "default_currency":"EUR",
    "delivery": {
      "release_date_type": "exact_date",
      "delivery_method": {
        "default": [
              "key"
              ],
              "exceptions": {
                 "drmfree": ["link","key"],
                 "steam": ["link"]
              }
      },
        'is_pre_order': false,
        'is_partner_side_processing': false
    },
    "release_date":"2016-01-01T00:00:00+00:00",
    "drm":[
        {
            "id":1,
            "name": "Steam",
            "platforms":[
                {
                    "id":1
                },
                {
                    "id":2
                }
            ],
            "prices":{
                "USD":19.99,
                "EUR":18.5
            },
            "codes": {
                "total": 0,
                "active": 0,
                "used": 0
            },
            "enabled":true
        }
    ],
    "obtain_code_from_api":false,
    "obtain_code_from_db":false,
    "files": [],
    "tips_enabled": false
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/game_delivery' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "sku":"GTA5",
    "name":{
        "en":"GTA V"
    },
    "description":{
        "en":"Grand Theft Auto V is an open world, action-adventure video game developed by Rockstar North and published by Rockstar Games."
    },
    "system_requirements":"OS: Windows 8.1 64 Bit, Windows 8 64 Bit, Windows 7 64 Bit Service Pack 1, Windows Vista 64 Bit Service Pack 2* (*NVIDIA video card recommended if running Vista OS)",
    "image_url":"//cdn2.xsolla.com/img/misc/merchant/default-item.png",
    "long_description":null,
    "locales_list":null,
    "publisher":null,
    "developer":null,
    "video_link":null,
    "genre":null,
    "additional_info":null,
    "forum_link":null,
    "support_link":null,
    "old_price":null,
    "parent_id":null,
    "default_currency":"EUR",
    "delivery": {
      "release_date_type": "exact_date",
      "delivery_method": {
        "default": [
              "key"
              ],
              "exceptions": {
                 "drmfree": ["link","key"],
                 "steam": ["link"]
              }
      },
        'is_pre_order': false,
        'is_partner_side_processing': false
    },
    "release_date":"2016-01-01T00:00:00+00:00",
    "drm":[
        {
            "id":1,
            "name": "Steam",
            "platforms":[
                {
                    "id":1
                },
                {
                    "id":2
                }
            ],
            "prices":{
                "USD":19.99,
                "EUR":18.5
            },
            "codes": {
                "total": 0,
                "active": 0,
                "used": 0
            },
            "enabled":true
        }
    ],
    "obtain_code_from_api":false,
    "obtain_code_from_db":false,
    "files": [],
    "tips_enabled": false
}'
Response
<?php

// example response
$response = array (
    'id' => 77
);
HTTP/1.1 201 Created
Content-Type: application/json

{
    "id": 77
}
{
    "id": 77
}

Get Entity

Gets a game delivery entity.

HTTP REQUEST

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/game_delivery/{game_delivery_id}

Parameter Type Description
project_id
integer Project ID.
game_delivery_id
integer ID of the game delivery entity.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->GetGameDeliveryEntity(array(
    'project_id' => PROJECT_ID,
    'game_delivery_id' => GAME_DELIVERY_ID
));
GET /merchant/v2/projects/{project_id}/game_delivery/{game_delivery_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/game_delivery/{game_delivery_id}' \
-X GET \
-u merchant_id:merchant_api_key
Response
<?php

// example response
$response = array (
    array (
      'request' =>  'sku' => 'GTA5',
     'name' =>
    stdClass::__set_state(array(
       'en' => 'GTA V',
    )),
     'description' =>
    stdClass::__set_state(array(
       'en' => 'Grand Theft Auto V is an open world, action-adventure video game developed by Rockstar North and published by Rockstar Games.',
    )),
     'system_requirements' => 'OS: Windows 8.1 64 Bit, Windows 8 64 Bit, Windows 7 64 Bit Service Pack 1, Windows Vista 64 Bit Service Pack 2* (*NVIDIA video card recommended if running Vista OS)',
     'image_url' => '//cdn2.xsolla.com/img/misc/merchant/default-item.png',
     'long_description' => NULL,
     'locales_list' => NULL,
     'publisher' => NULL,
     'developer' => NULL,
     'video_link' => NULL,
     'genre' => NULL,
     'additional_info' => NULL,
     'forum_link' => NULL,
     'support_link' => NULL,
     'old_price' => NULL,
     'parent_id' => NULL,
     'default_currency' => 'EUR',
     'delivery' =>
    stdClass::__set_state(array(
       'release_date_type' => 'exact_date',
       'delivery_method' =>
      stdClass::__set_state(array(
         'default' =>
        array (
          0 => 'key',
        ),
         'exceptions' =>
        stdClass::__set_state(array(
           'drmfree' =>
          array (
            0 => 'link',
            1 => 'key',
          ),
           'steam' =>
          array (
            0 => 'link',
          ),
        )),
      )),
       'is_pre_order' => false,
       'is_partner_side_processing' => false,
    )),
     'release_date' => '2016-01-01T00:00:00+00:00',
     'drm' =>
    array (
      0 =>
      stdClass::__set_state(array(
         'id' => 1,
         'name' => 'Steam',
         'platforms' =>
        array (
          0 =>
          stdClass::__set_state(array(
             'id' => 1,
          )),
          1 =>
          stdClass::__set_state(array(
             'id' => 2,
          )),
        ),
         'prices' =>
        stdClass::__set_state(array(
           'USD' => 19.989999999999998,
           'EUR' => 18.5,
        )),
         'codes' =>
        stdClass::__set_state(array(
           'total' => 0,
           'active' => 0,
           'used' => 0,
        )),
         'enabled' => true,
      )),
    ),
     'obtain_code_from_api' => false,
     'obtain_code_from_db' => false,
     'files' =>
    array (
    ),
     'tips_enabled' => false,
  ));
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 9,
    "sku":"GTA5",
    "name":{
        "en":"GTA V"
    },
    "description":{
        "en":"Grand Theft Auto V is an open world, action-adventure video game developed by Rockstar North and published by Rockstar Games."
    },
    "system_requirements":"OS: Windows 8.1 64 Bit, Windows 8 64 Bit, Windows 7 64 Bit Service Pack 1, Windows Vista 64 Bit Service Pack 2* (*NVIDIA video card recommended if running Vista OS)",
    "image_url":"//cdn2.xsolla.com/img/misc/merchant/default-item.png",
    "long_description":null,
    "locales_list":null,
    "publisher":null,
    "developer":null,
    "video_link":null,
    "genre":null,
    "additional_info":null,
    "forum_link":null,
    "support_link":null,
    "old_price":null,
    "parent_id":null,
    "default_currency":"EUR",
    "delivery": {
      "release_date_type": "exact_date",
      "delivery_method": {
        "default": [
              "key"
              ],
              "exceptions": {
                 "drmfree": ["link","key"],
                 "steam": ["link"]
              }
      },
        'is_pre_order': false,
        'is_partner_side_processing': false
    },
    "release_date":"2016-01-01T00:00:00+00:00",
    "drm":[
        {
            "id":1,
            "name": "Steam",
            "platforms":[
                {
                    "id":1
                },
                {
                    "id":2
                }
            ],
            "prices":{
                "USD":19.99,
                "EUR":18.5
            },
            "codes": {
                "total": 0,
                "active": 0,
                "used": 0
            },
            "enabled":true
        }
    ],
    "obtain_code_from_api":false,
    "obtain_code_from_db":false,
    "files": [],
    "tips_enabled": false
}
{
    "id": 9,
    "sku":"GTA5",
    "name":{
        "en":"GTA V"
    },
    "description":{
        "en":"Grand Theft Auto V is an open world, action-adventure video game developed by Rockstar North and published by Rockstar Games."
    },
    "system_requirements":"OS: Windows 8.1 64 Bit, Windows 8 64 Bit, Windows 7 64 Bit Service Pack 1, Windows Vista 64 Bit Service Pack 2* (*NVIDIA video card recommended if running Vista OS)",
    "image_url":"//cdn2.xsolla.com/img/misc/merchant/default-item.png",
    "long_description":null,
    "locales_list":null,
    "publisher":null,
    "developer":null,
    "video_link":null,
    "genre":null,
    "additional_info":null,
    "forum_link":null,
    "support_link":null,
    "old_price":null,
    "parent_id":null,
    "default_currency":"EUR",
    "delivery": {
      "release_date_type": "exact_date",
      "delivery_method": {
        "default": [
              "key"
              ],
              "exceptions": {
                 "drmfree": ["link","key"],
                 "steam": ["link"]
              }
      },
        'is_pre_order': false,
        'is_partner_side_processing': false
    },
    "release_date":"2016-01-01T00:00:00+00:00",
    "drm":[
        {
            "id":1,
            "name": "Steam",
            "platforms":[
                {
                    "id":1
                },
                {
                    "id":2
                }
            ],
            "prices":{
                "USD":19.99,
                "EUR":18.5
            },
            "codes": {
                "total": 0,
                "active": 0,
                "used": 0
            },
            "enabled":true
        }
    ],
    "obtain_code_from_api":false,
    "obtain_code_from_db":false,
    "files": [],
    "tips_enabled": false
}

Update Entity

Updates a game delivery entity.

HTTP REQUEST

PUT https://api.xsolla.com/merchant/v2/projects/{project_id}/game_delivery/{game_delivery_id}

Parameter Type Description
project_id
integer Project ID.
sku
string Unique ID. The SKU may only contain lowercase Latin alphanumeric characters, dashes, and underscores.
name
object Array of localized names of the game delivery entity.
description
object Array of localized descriptions of the game delivery entity.
system_requirements
string System requirements for the game.
image_url
string Image URL. Optional.
long_description
string Extended description of the game delivery entity. Optional.
locales_list
string Comma-separated list of localizations. Optional.
publisher
string Game publisher. Optional.
developer
string Game developer. Optional.
string Link to a video featuring the game. Optional.
genre
string Game genre. Optional.
additional_info
string Additional info about the game. Optional.
string Link to a discussion forum. Optional.
string Link to a support page. Optional.
old_price
string Old price of the game. Optional.
parent_id
integer ID of a parent game. Optional.
default_currency
string Default purchase currency. Three-letter currency code per ISO 4217.
delivery
object Data on the delivery of preordered keys.
delivery.release_date_type
string Type of release date. Can be set to a specific UTC date or a quarter & year. In the latter case, ‘delivery.release_date_type’ is set to the last day of the specified quarter.
delivery.delivery_method
string Key delivery method.
delivery.delivery_method.default
string Default key delivery method.
delivery.delivery_method.exception
string Exceptions to key delivery methods.
release_date
string Expected date of release. Optional.
drm
array Array with DRM data.
drm.id
integer ID of an available DRM.
drm.name
integer DRM name.
drm.prices
array Array of game prices for DRM. Optional.
drm.codes
array Key array for DRM. Optional.
drm.codes.total
string Total number of keys. Optional.
drm.codes.active
string Number of active keys. Optional.
drm.codes.used
string Number of used keys. Optional.
drm.platforms
array Array with data about DRM platforms.
drm.platforms.id
integer Platform ID for that DRM.
drm.enabled
boolean Whether DRM is in use for this game.
obtain_code_from_db
boolean Whether to use Game keys from Xsolla database. Optional.
obtain_code_from_api
boolean Whether to use game keys received via API. Optional.
files
array Array of installation files for downloading. Optional.
files.name
string File name. Optional.
files.url
string URL for download. Optional.
tips_enabled
boolean Whether to enable tips for developers. Optional.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->UpdateGameDeliveryEntity(array(
  'project_id' => PROJECT_ID,
  'request' => array (
       'sku' => 'GTA5',
       'name' =>
           array (
               'en' => 'GTA V',
           ),
       'description' =>
           array (
               'en' => 'Grand Theft Auto V is an open world, action-adventure video game developed by Rockstar North and published by Rockstar Games.',
           ),
       'system_requirements' => 'OS: Windows 8.1 64 Bit, Windows 8 64 Bit, Windows 7 64 Bit Service Pack 1, Windows Vista 64 Bit Service Pack 2* (*NVIDIA video card recommended if running Vista OS)',
       'image_url' => '//cdn2.xsolla.com/img/misc/merchant/default-item.png',
       'long_description' => NULL,
       'locales_list' => NULL,
       'publisher' => NULL,
       'developer' => NULL,
       'video_link' => NULL,
       'genre' => NULL,
       'additional_info' => NULL,
       'forum_link' => NULL,
       'support_link' => NULL,
       'old_price' => NULL,
       'parent_id' => NULL,
       'default_currency' => 'EUR',
       'release_date' => '2016-01-01T00:00:00+00:00',
       "delivery" =>
           array (
        'release_date_type': 'exact_date',
        'delivery_method'=>
            array (
            'default'=>
                array (
                'key' => '123'
            ),
            'exceptions'=>
                array (
               'drmfree'=>
                   array ('link','key'),
               'steam'=>
                   array ('link')
            )
        ),
       'drm' =>
           array (
               array (
                   'id' => 1,
                   'name' => 'Game Keys'
                   'platforms' =>
                       array (
                           array (
                               'id' => 1,
                           ),
                           array (
                               'id' => 2,
                           ),
                       ),
                   'prices' =>
                       array (
                           'USD' => 19.99,
                           'EUR' => 18.5,
                       ),
                    'codes' =>
                        array (
                          'total' => 0,
                          "active" => 0,
                          "used" => 0
                        )
                   'enabled' => true
               ),
           ),
       'obtain_code_from_api' => false,
       'obtain_code_from_db' => false,
       'files' =>
           array (),
       'tips_enabled' => false
   )
));
PUT /merchant/v2/projects/{project_id}/game_delivery/{game_delivery_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
{
    "sku":"GTA5",
    "name":{
        "en":"GTA V"
    },
    "description":{
        "en":"Grand Theft Auto V is an open world, action-adventure video game developed by Rockstar North and published by Rockstar Games."
    },
    "system_requirements":"OS: Windows 8.1 64 Bit, Windows 8 64 Bit, Windows 7 64 Bit Service Pack 1, Windows Vista 64 Bit Service Pack 2* (*NVIDIA video card recommended if running Vista OS)",
    "image_url":"//cdn2.xsolla.com/img/misc/merchant/default-item.png",
    "long_description":null,
    "locales_list":null,
    "publisher":null,
    "developer":null,
    "video_link":null,
    "genre":null,
    "additional_info":null,
    "forum_link":null,
    "support_link":null,
    "old_price":null,
    "parent_id":null,
    "default_currency":"EUR",
    "delivery": {
      "release_date_type": "exact_date",
      "delivery_method": {
        "default": [
              "key"
              ],
              "exceptions": {
                 "drmfree": ["link","key"],
                 "steam": ["link"]
              }
      },
        'is_pre_order': false,
        'is_partner_side_processing': false
    },
    "release_date":"2016-01-01T00:00:00+00:00",
    "drm":[
        {
            "id":1,
            "name": "Steam",
            "platforms":[
                {
                    "id":1
                },
                {
                    "id":2
                }
            ],
            "prices":{
                "USD":19.99,
                "EUR":18.5
            },
            "codes": {
                "total": 0,
                "active": 0,
                "used": 0
            },
            "enabled":true
        }
    ],
    "obtain_code_from_api":false,
    "obtain_code_from_db":false,
    "files": [],
    "tips_enabled": false
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/game_delivery/{game_delivery_id}' \
-X PUT \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "sku":"GTA5",
    "name":{
        "en":"GTA V"
    },
    "description":{
        "en":"Grand Theft Auto V is an open world, action-adventure video game developed by Rockstar North and published by Rockstar Games."
    },
    "system_requirements":"OS: Windows 8.1 64 Bit, Windows 8 64 Bit, Windows 7 64 Bit Service Pack 1, Windows Vista 64 Bit Service Pack 2* (*NVIDIA video card recommended if running Vista OS)",
    "image_url":"//cdn2.xsolla.com/img/misc/merchant/default-item.png",
    "long_description":null,
    "locales_list":null,
    "publisher":null,
    "developer":null,
    "video_link":null,
    "genre":null,
    "additional_info":null,
    "forum_link":null,
    "support_link":null,
    "old_price":null,
    "parent_id":null,
    "default_currency":"EUR",
    "delivery": {
      "release_date_type": "exact_date",
      "delivery_method": {
        "default": [
              "key"
              ],
              "exceptions": {
                 "drmfree": ["link","key"],
                 "steam": ["link"]
              }
      },
        'is_pre_order': false,
        'is_partner_side_processing': false
    },
    "release_date":"2016-01-01T00:00:00+00:00",
    "drm":[
        {
            "id":1,
            "name": "Steam",
            "platforms":[
                {
                    "id":1
                },
                {
                    "id":2
                }
            ],
            "prices":{
                "USD":19.99,
                "EUR":18.5
            },
            "codes": {
                "total": 0,
                "active": 0,
                "used": 0
            },
            "enabled":true
        }
    ],
    "obtain_code_from_api":false,
    "obtain_code_from_db":false,
    "files": [],
    "tips_enabled": false
}'
Response
<?php

$response = null;
HTTP/1.1 204 No Content

Get Entities List

Lists all game delivery entities.

HTTP REQUEST

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/game_delivery

Parameter Type Description
project_id
integer Project ID.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->ListGameDeliveryEntities(array(
    'project_id' => PROJECT_ID
));
GET /merchant/v2/projects/{project_id}/game_delivery HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/game_delivery' \
-X GET \
-u merchant_id:merchant_api_key
Response
<?php

// example response
$response = array (
    array (
        array (
            'id' => 9,
            'localized_name' => 'GTA V',
            'parent_id' => NULL,
            'default_currency' => 'EUR',
            'drm' =>
                array (
                    array (
                        'id' => 1,
                        'name' => 'Steam',
                        'image' => NULL,
                        'platforms' =>
                            array (
                                array (
                                    'id' => 1,
                                    'name' => 'Windows',
                                ),
                                array (
                                    'id' => 2,
                                    'name' => 'Linux',
                                ),
                            ),
                        'prices' =>
                            array (
                                'USD' => 19.99,
                                'EUR' => 18.5,
                            ),
                        'codes' =>
                            array (
                                'total' => 1000,
                                'active' => 999,
                                'used' => 1,
                            ),
                        ),
                    array (
                        'id' => 2,
                        'name' => 'Playstation',
                        'image' => NULL,
                        'platforms' =>
                            array (
                                array (
                                    'id' => 3,
                                    'name' => 'Playstation 3',
                                ),
                                array (
                                    'id' => 4,
                                    'name' => 'Playstation 4',
                                ),
                            ),
                        'prices' =>
                            array (
                                'USD' => 19.99,
                                'EUR' => 18.5,
                            ),
                        'codes' =>
                            array (
                                'total' => 1000,
                                'active' => 999,
                                'used' => 1,
                            ),
                    ),
                ),
        ),
    )
);
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": 9,
        "localized_name": "GTA V",
        "parent_id": null,
        "default_currency": "EUR",
        "drm": [
            {
                "id": 1,
                "name": "Steam",
                "image": null,
                "platforms": [
                    {
                        "id": 1,
                        "name": "Windows"
                    },
                    {
                        "id": 2,
                        "name": "Linux"
                    }
                ],
                "prices": {
                    "USD": 19.99,
                    "EUR": 18.5
                },
                "codes": {
                    "total": 1000,
                    "active": 999,
                    "used": 1
                }
            },
            {
                "id": 2,
                "name": "Playstation",
                "image": null,
                "platforms": [
                    {
                        "id": 3,
                        "name": "Playstation 3"
                    },
                    {
                        "id": 4,
                        "name": "Playstation 4"
                    }
                ],
                "prices": {
                    "USD": 19.99,
                    "EUR": 18.5
                },
                "codes": {
                    "total": 1000,
                    "active": 999,
                    "used": 1
                }
            }
        ]
    }
]
[
    {
        "id": 9,
        "localized_name": "GTA V",
        "parent_id": null,
        "default_currency": "EUR",
        "drm": [
            {
                "id": 1,
                "name": "Steam",
                "image": null,
                "platforms": [
                    {
                        "id": 1,
                        "name": "Windows"
                    },
                    {
                        "id": 2,
                        "name": "Linux"
                    }
                ],
                "prices": {
                    "USD": 19.99,
                    "EUR": 18.5
                },
                "codes": {
                    "total": 1000,
                    "active": 999,
                    "used": 1
                }
            },
            {
                "id": 2,
                "name": "Playstation",
                "image": null,
                "platforms": [
                    {
                        "id": 3,
                        "name": "Playstation 3"
                    },
                    {
                        "id": 4,
                        "name": "Playstation 4"
                    }
                ],
                "prices": {
                    "USD": 19.99,
                    "EUR": 18.5
                },
                "codes": {
                    "total": 1000,
                    "active": 999,
                    "used": 1
                }
            }
        ]
    }
]

Get DRM List

Lists available DRM platforms.

HTTP REQUEST

GET https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/drm

Parameter Type Description
merchant_id
integer Merchant ID.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->ListGameDeliveryDrmPlatforms();
GET /merchant/v2/merchants/{merchant_id}/drm HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/drm' \
-X GET \
-u merchant_id:merchant_api_key
Response
<?php

// example response
$response = array (
    'drm' =>
        array (
            array (
                'id' => 1,
                'name' => 'Steam',
                'image' => '//cdn2.xsolla.com/misc/game_delivery/drms/set2/1.1450132085.svg',
                'platforms' =>
                    array (
                        array (
                            'id' => 1,
                            'name' => 'Windows',
                        ),
                        array (
                            'id' => 2,
                            'name' => 'Linux',
                        ),
                        array (
                            'id' => 6,
                            'name' => 'Mac',
                        ),
                    ),
            ),
            array (
                'id' => 2,
                'name' => 'Playstation',
                'image' => '//cdn2.xsolla.com/misc/game_delivery/drms/set2/2.1449183647.svg',
                'platforms' =>
                    array (
                        array (
                            'id' => 3,
                            'name' => 'Playstation 3',
                        ),
                        array (
                            'id' => 4,
                            'name' => 'Playstation 4',
                        ),
                    ),
            ),
            array (
                'id' => 3,
                'name' => 'XBox',
                'image' => '//cdn2.xsolla.com/misc/game_delivery/drms/set2/3.1449183647.svg',
                'platforms' =>
                    array (
                        array (
                            'id' => 5,
                            'name' => 'XBox One',
                        ),
                        array (
                            'id' => 7,
                            'name' => 'XBox 360',
                        ),
                    ),
            ),
            array (
                'id' => 4,
                'name' => 'Uplay',
                'image' => '//cdn2.xsolla.com/misc/game_delivery/drms/set2/4.1450201713.svg',
                'platforms' =>
                    array (
                        array (
                            'id' => 1,
                            'name' => 'Windows',
                        ),
                        array (
                            'id' => 2,
                            'name' => 'Linux',
                        ),
                        array (
                            'id' => 6,
                            'name' => 'Mac',
                        ),
                    ),
            ),
            array (
                'id' => 5,
                'name' => 'Origin',
                'image' => '//cdn2.xsolla.com/misc/game_delivery/drms/set2/5.1450201747.svg',
                'platforms' =>
                    array (
                        array (
                            'id' => 1,
                            'name' => 'Windows',
                        ),
                        array (
                            'id' => 2,
                            'name' => 'Linux',
                        ),
                        array (
                            'id' => 6,
                            'name' => 'Mac',
                        ),
                    ),
            ),
            array (
                'id' => 6,
                'name' => 'DRM Free',
                'image' => '//cdn2.xsolla.com/misc/game_delivery/drms/set2/6.1450201849.svg',
                'platforms' =>
                    array (
                        array (
                            'id' => 1,
                            'name' => 'Windows',
                        ),
                        array (
                            'id' => 2,
                            'name' => 'Linux',
                        ),
                        array (
                            'id' => 6,
                            'name' => 'Mac',
                        ),
                    )
            )
        ),
    'platforms' =>
        array (
            array (
                'id' => 1,
                'name' => 'Windows',
            ),
            array (
                'id' => 2,
                'name' => 'Linux',
            ),
            array (
                'id' => 3,
                'name' => 'Playstation 3',
            ),
            array (
                'id' => 4,
                'name' => 'Playstation 4',
            ),
            array (
                'id' => 5,
                'name' => 'XBox One',
            ),
            array (
                'id' => 6,
                'name' => 'Mac',
            ),
            array (
                'id' => 7,
                'name' => 'XBox 360',
            )
        )
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "drm":[
        {
            "id":1,
            "name":"Steam",
            "image":"//cdn2.xsolla.com/misc/game_delivery/drms/set2/1.1450132085.svg",
            "platforms":[
                {
                    "id":1,
                    "name":"Windows"
                },
                {
                    "id":2,
                    "name":"Linux"
                },
                {
                    "id":6,
                    "name":"Mac"
                }
            ]
        },
        {
            "id":2,
            "name":"Playstation",
            "image":"//cdn2.xsolla.com/misc/game_delivery/drms/set2/2.1449183647.svg",
            "platforms":[
                {
                    "id":3,
                    "name":"Playstation 3"
                },
                {
                    "id":4,
                    "name":"Playstation 4"
                }
            ]
        },
        {
            "id":3,
            "name":"XBox",
            "image":"//cdn2.xsolla.com/misc/game_delivery/drms/set2/3.1449183647.svg",
            "platforms":[
                {
                    "id":5,
                    "name":"XBox One"
                },
                {
                    "id":7,
                    "name":"XBox 360"
                }
            ]
        },
        {
            "id":4,
            "name":"Uplay",
            "image":"//cdn2.xsolla.com/misc/game_delivery/drms/set2/4.1450201713.svg",
            "platforms":[
                {
                    "id":1,
                    "name":"Windows"
                },
                {
                    "id":2,
                    "name":"Linux"
                },
                {
                    "id":6,
                    "name":"Mac"
                }
            ]
        },
        {
            "id":5,
            "name":"Origin",
            "image":"//cdn2.xsolla.com/misc/game_delivery/drms/set2/5.1450201747.svg",
            "platforms":[
                {
                    "id":1,
                    "name":"Windows"
                },
                {
                    "id":2,
                    "name":"Linux"
                },
                {
                    "id":6,
                    "name":"Mac"
                }
            ]
        },
        {
            "id":6,
            "name":"DRM Free",
            "image":"//cdn2.xsolla.com/misc/game_delivery/drms/set2/6.1450201849.svg",
            "platforms":[
                {
                    "id":1,
                    "name":"Windows"
                },
                {
                    "id":2,
                    "name":"Linux"
                },
                {
                    "id":6,
                    "name":"Mac"
                }
            ]
        }
    ],
    "platforms":[
        {
            "id":1,
            "name":"Windows"
        },
        {
            "id":2,
            "name":"Linux"
        },
        {
            "id":3,
            "name":"Playstation 3"
        },
        {
            "id":4,
            "name":"Playstation 4"
        },
        {
            "id":5,
            "name":"XBox One"
        },
        {
            "id":6,
            "name":"Mac"
        },
        {
            "id":7,
            "name":"XBox 360"
        }
    ]
}
{
    "drm":[
        {
            "id":1,
            "name":"Steam",
            "image":"//cdn2.xsolla.com/misc/game_delivery/drms/set2/1.1450132085.svg",
            "platforms":[
                {
                    "id":1,
                    "name":"Windows"
                },
                {
                    "id":2,
                    "name":"Linux"
                },
                {
                    "id":6,
                    "name":"Mac"
                }
            ]
        },
        {
            "id":2,
            "name":"Playstation",
            "image":"//cdn2.xsolla.com/misc/game_delivery/drms/set2/2.1449183647.svg",
            "platforms":[
                {
                    "id":3,
                    "name":"Playstation 3"
                },
                {
                    "id":4,
                    "name":"Playstation 4"
                }
            ]
        },
        {
            "id":3,
            "name":"XBox",
            "image":"//cdn2.xsolla.com/misc/game_delivery/drms/set2/3.1449183647.svg",
            "platforms":[
                {
                    "id":5,
                    "name":"XBox One"
                },
                {
                    "id":7,
                    "name":"XBox 360"
                }
            ]
        },
        {
            "id":4,
            "name":"Uplay",
            "image":"//cdn2.xsolla.com/misc/game_delivery/drms/set2/4.1450201713.svg",
            "platforms":[
                {
                    "id":1,
                    "name":"Windows"
                },
                {
                    "id":2,
                    "name":"Linux"
                },
                {
                    "id":6,
                    "name":"Mac"
                }
            ]
        },
        {
            "id":5,
            "name":"Origin",
            "image":"//cdn2.xsolla.com/misc/game_delivery/drms/set2/5.1450201747.svg",
            "platforms":[
                {
                    "id":1,
                    "name":"Windows"
                },
                {
                    "id":2,
                    "name":"Linux"
                },
                {
                    "id":6,
                    "name":"Mac"
                }
            ]
        },
        {
            "id":6,
            "name":"DRM Free",
            "image":"//cdn2.xsolla.com/misc/game_delivery/drms/set2/6.1450201849.svg",
            "platforms":[
                {
                    "id":1,
                    "name":"Windows"
                },
                {
                    "id":2,
                    "name":"Linux"
                },
                {
                    "id":6,
                    "name":"Mac"
                }
            ]
        }
    ],
    "platforms":[
        {
            "id":1,
            "name":"Windows"
        },
        {
            "id":2,
            "name":"Linux"
        },
        {
            "id":3,
            "name":"Playstation 3"
        },
        {
            "id":4,
            "name":"Playstation 4"
        },
        {
            "id":5,
            "name":"XBox One"
        },
        {
            "id":6,
            "name":"Mac"
        },
        {
            "id":7,
            "name":"XBox 360"
        }
    ]
}

Game Keys Widget

The widget is easy to embed and will provide the user with game details, available DRMs and platforms, and payment methods.

You can download the script from our CDN here. Use this URL to integrate the script on your website. For more information please visit our GitHub repository.

There are two options for integrating widget:

  • Basic integration
  • Advanced integration

See the integration guide to know more about the differences between the two options. Widget initialization parameters depend on the option.

Basic Integration

Script initialization parameters:

Parameter Type Description
access_data
string User and payment details (object). Required.
theme
object Widget theme.
theme.foreground
string Widget foreground color.
theme.background
string Widget background color.
target_element
boolean jQuery selector for the page element containing the widget (e.g. ‘#widget-example’). Required.

The parameters and structure for the access_data object are similar to those used for the token.

Advanced Integration

Script initialization parameters:

Parameter Type Description
access_token
string Token, received via API. Required.
sandbox
boolean Set to true to test the payment process: sandbox-secure.xsolla.com will be used instead of secure.xsolla.com.
theme
object Widget theme.
theme.foreground
string Widget foreground color.
theme.background
string Widget background color.
target_element
boolean jQuery selector for the page element containing the widget (e.g. ‘#widget-example’). Required.

The following parameters define the payment UI theme. The same parameters are used for Xsolla Pay Station Widget.

Parameter Type Description
lightbox
object Lightbox parameters (object; desktop version only).
lightbox.width
string Lightbox frame width. If null, depends on Pay Station width. Default is null.
lightbox.height
string Lightbox frame height. If null, depends on Pay Station height. Default is ‘100%’.
lightbox.zIndex
integer Defines arrangement order. Default is 1000.
lightbox.overlayOpacity
integer Overlay opacity (0 to 1). Default is ‘.6’.
lightbox.overlayBackground
string Overlay background color. Default is ‘#000000’.
lightbox.modal
boolean If true, the lightbox frame cannot be closed. Default is ‘false’.
lightbox.closeByClick
boolean If true, clicking the overlay will close the lightbox. Default is ‘true’.
lightbox.closeByKeyboard
boolean If true, pressing ESC will close the lightbox. Default is ‘true’.
lightbox.contentBackground
string Frame background color. Default is ‘#ffffff’.
lightbox.contentMargin
string Frame margin. Default is ‘10px’.
lightbox.spinner
string Type of animated loading indicator. Can be ‘xsolla’ or ‘round’. Default is ‘xsolla’.
lightbox.spinnerColor
string Spinner color. No default value.
childWindow
object Options for the child window containing the Pay Station UI. Supported in the mobile version.
childWindow.target
string Where to open the Pay Station window. Can be ‘_blank’, ‘_self’, ‘_parent’. Default is ‘_blank’.
Notice: Make sure not to call XPay2PlayWidget.create() before the DOM is fully loaded. You can track the desired event or add the script after the element containing the widget.
Copy
Full screen
  • html
Asynchronous script loading with a callback for basic integration
<script>
    var accessData = {"settings":{"project_id":14004},"purchase":{"pin_codes":{"codes":[{"digital_content":"game_sku"}]}}};
    var options = {
        access_data: accessData,
        theme : {
            foreground: 'green',
            background: 'light'
        },
        target_element: '#widget-example-element'
    };
    var s = document.createElement('script');
    s.type = "text/javascript";
    s.async = true;
    s.src = "//static.xsolla.com/embed/pay2play/2.1.5/widget.min.js";
    s.addEventListener('load', function (e) {
        var widgetInstance = XPay2PlayWidget.create(options);
    }, false);
    var head = document.getElementsByTagName('head')[0];
    head.appendChild(s);
</script>
Asynchronous script loading with a callback for advanced integration
<script>
    var options = {
        access_token: 'abcdef1234567890abcdef1234567890',
        theme : {
            foreground: 'green',
            background: 'light'
        },
        target_element: '#widget-example-element'
    };
    var s = document.createElement('script');
    s.type = "text/javascript";
    s.async = true;
    s.src = "//static.xsolla.com/embed/pay2play/2.1.5/widget.min.js";
    s.addEventListener('load', function (e) {
        var widgetInstance = XPay2PlayWidget.create(options);
    }, false);
    var head = document.getElementsByTagName('head')[0];
    head.appendChild(s);
</script>

Activate Key

Activates a game key.

HTTP REQUEST

POST https://api.xsolla.com/merchant/v2/projects/{project_id}/game_delivery/redeem_key

Parameter Type Description
digital_content_sku
string Unique key package ID.
drm_sku
string Unique DRM ID in Xsolla. Required.
key
string Activation key. Required.
user_id
string User ID. Required.
user_email
string User email. Required.
language
string User language per ISO-639-1. Required.
encoded
boolean Whether the key encryption is used. If ‘true’, the key is encrypted according to the AES-256-ECB algorithm using the project secret key. Default is ‘false’.
Copy
Full screen
  • php
  • http
  • curl
Request
<<?php
$request = array(
    'project_id' => PROJECT_ID,
    'drm_sku' => ‘drmfree’,
    'key' => ‘wqdqwwddq9099022’,
    'user_id' => ‘sample_user’,
    'user_email' => ‘sample_email@mail.com’,
    'language' => ‘en’,
    'encoded' => false,     
);
POST /merchant/v2/projects/{project_id}/game_delivery/redeem_key HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
  "drm_sku": "‘drmfree’",
  "key": "wqdqwwddq9099022",
  "user_id": "sample_user",
  "user_email": "sample_email@mail.com",
  "language": "en",
  "encoded": false
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/game_delivery/redeem_key' \
-X POST \
-u merchant_id:merchant_api_key
-d ‘{
  "drm_sku": "‘drmfree’",
  "key": "wqdqwwddq9099022",
  "user_id": "sample_user",
  "user_email": "sample_email@mail.com",
  "language": "en",
  "encoded": false
}
Response
<?php

$response = null;
HTTP/1.1 204 No content

Coupons

Get Coupon

Get coupon details by its code.

HTTP REQUEST

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/coupons/{code}

Parameter Type Description
project_id
integer Project ID.
code
string Coupon code.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->GetCoupon(array(
    'project_id' => PROJECT_ID,
    'code' => COUPON_CODE
));
GET /merchant/v2/projects/{project_id}/coupons/{code} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/coupons/{code}' \
-X GET \
-u merchant_id:merchant_api_key
Response
<?php

// example response
$response = array (
    'coupon_id' => 1,
    'project_id' => 1,
    'coupon_code' => 'CouPoNCoDe',
    'campaign_code' => 'CaMPaiGNCoDe',
    'virtual_currency_amount' => 0,
    'is_active' => 1,
    'redeems_count_remain' => 1,
    'redeems_count_for_user' => null,
    'expiration_date' => '2014-10-16 21:44:31',
    'virtual_items' =>
        array (
            'virtual_item' =>
                array (
                    'id' => 77,
                    'sku' => 'T-43-3-unique-id',
                    'item_code' => null,
                    'advertisement_type' => null,
                    'name' =>
                        array (
                            'en' => 'T-34-3',
                        ),
                    'description' =>
                        array (
                            'en' => 'This Chinese Tier VIII medium tank is a real beast in its class.',
                        ),
                    'long_description' =>
                        array (
                        ),
                    'prices' =>
                        array (
                            'USD' => 40.09,
                        ),
                    'default_currency' => 'USD',
                    'enabled' => true,
                    'permanent' => false,
                    'purchase_limit' => 1,
                    'keywords' =>
                        array (
                        ),
                    'image_url' => 'http://livedemo.xsolla.com/airplanes/tank5.jpg',
                    'groups' =>
                        array (25),
                    'item_type' => 'Expiration',
                    'expiration' => 1296000,
                    'virtual_currency_price' => null,
                ),
            'amount' => 1
        )
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "coupon_id": 1,
    "project_id": 1,
    "coupon_code": "CouPoNCoDe",
    "campaign_code": "CaMPaiGNCoDe",
    "virtual_currency_amount": 0,
    "is_active": 1,
    "redeems_count_remain": 1,
    "redeems_count_for_user": null,
    "expiration_date": "2014-10-16 21:44:31",
    "virtual_items": {
        "virtual_item": {
            "id": 77,
            "sku": "T-43-3-unique-id",
            "item_code": "chinese-medium-tank",
            "advertisement_type": null,
            "name": {
                "en": "T-34-3"
            },
            "description": {
                "en": "This Chinese Tier VIII medium tank is a real beast in its class."
            },
            "long_description": [],
            "prices": {
                "USD": 40.09
            },
            "default_currency": "USD",
            "enabled": true,
            "permanent": false,
            "purchase_limit": 1,
            "keywords": [],
            "image_url": "http:\/\/livedemo.xsolla.com\/airplanes\/tank5.jpg",
            "groups": [
                25
            ],
            "item_type": "Expiration",
            "expiration": 1296000,
            "virtual_currency_price": null,
            "item_code": null
        },
        "amount": 1
    }
}
{
    "coupon_id": 1,
    "project_id": 1,
    "coupon_code": "CouPoNCoDe",
    "campaign_code": "CaMPaiGNCoDe",
    "virtual_currency_amount": 0,
    "is_active": 1,
    "redeems_count_remain": 1,
    "redeems_count_for_user": null,
    "expiration_date": "2014-10-16 21:44:31",
    "virtual_items": {
        "virtual_item": {
            "id": 77,
            "sku": "T-43-3-unique-id",
            "item_code": "chinese-medium-tank",
            "advertisement_type": null,
            "name": {
                "en": "T-34-3"
            },
            "description": {
                "en": "This Chinese Tier VIII medium tank is a real beast in its class."
            },
            "long_description": [],
            "prices": {
                "USD": 40.09
            },
            "default_currency": "USD",
            "enabled": true,
            "permanent": false,
            "purchase_limit": 1,
            "keywords": [],
            "image_url": "http:\/\/livedemo.xsolla.com\/airplanes\/tank5.jpg",
            "groups": [
                25
            ],
            "item_type": "Expiration",
            "expiration": 1296000,
            "virtual_currency_price": null,
            "item_code": null
        },
        "amount": 1
    }
}

Redeem Coupon

Redeem a coupon by its code.

HTTP REQUEST

POST https://api.xsolla.com/merchant/v2/projects/{project_id}/coupons/{code}/redeem

Parameter Type Description
project_id
integer Project ID.
code
string Coupon code.
user_id
string User ID.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->RedeemCoupon(array(
    'project_id' => PROJECT_ID,
    'code' => COUPON_CODE,
    'request' => array(
        'user_id' => 1
    )
));
POST /merchant/v2/projects/{project_id}/coupons/{code}/redeem HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "user_id": 1
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/coupons/{code}/redeem' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "user_id": 1
}'
Response
<?php

// example response
$response = array (
    'coupon_id' => 1,
    'project_id' => 1,
    'coupon_code' => 'CouPoNCoDe',
    'campaign_code' => 'CaMPaiGNCoDe',
    'virtual_currency_amount' => 0,
    'is_active' => 1,
    'redeems_count_remain' => 1,
    'redeems_count_for_user' => null,
    'expiration_date' => '2014-10-16 21:44:31',
    'virtual_items' =>
        array (
            'virtual_item' =>
                array (
                    'id' => 77,
                    'sku' => 'T-43-3-unique-id',
                    'item_code' => null,
                    'advertisement_type' => null,
                    'name' =>
                        array (
                            'en' => 'T-34-3',
                        ),
                    'description' =>
                        array (
                            'en' => 'This Chinese Tier VIII medium tank is a real beast in its class.',
                        ),
                    'long_description' =>
                        array (
                        ),
                    'prices' =>
                        array (
                            'USD' => 40.09,
                        ),
                    'default_currency' => 'USD',
                    'enabled' => true,
                    'permanent' => false,
                    'purchase_limit' => 1,
                    'keywords' =>
                        array (
                        ),
                    'image_url' => 'http://livedemo.xsolla.com/airplanes/tank5.jpg',
                    'groups' =>
                        array (25),
                    'item_type' => 'Expiration',
                    'expiration' => 1296000,
                    'virtual_currency_price' => null,
                ),
            'amount' => 1
        )
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "coupon_id": 1,
    "project_id": 1,
    "coupon_code": "CouPoNCoDe",
    "campaign_code": "CaMPaiGNCoDe",
    "virtual_currency_amount": 0,
    "is_active": 1,
    "redeems_count_remain": 1,
    "redeems_count_for_user": null,
    "expiration_date": "2014-10-16 21:44:31",
    "virtual_items": {
        "virtual_item": {
            "id": 77,
            "sku": "T-43-3-unique-id",
            "item_code": "chinese-medium-tank",
            "advertisement_type": null,
            "name": {
                "en": "T-34-3"
            },
            "description": {
                "en": "This Chinese Tier VIII medium tank is a real beast in its class."
            },
            "long_description": [],
            "prices": {
                "USD": 40.09
            },
            "default_currency": "USD",
            "enabled": true,
            "permanent": false,
            "purchase_limit": 1,
            "keywords": [],
            "image_url": "http:\/\/livedemo.xsolla.com\/airplanes\/tank5.jpg",
            "groups": [
                25
            ],
            "item_type": "Expiration",
            "expiration": 1296000,
            "virtual_currency_price": null,
            "item_code": null
        },
        "amount": 1
    }
}
{
    "coupon_id": 1,
    "project_id": 1,
    "coupon_code": "CouPoNCoDe",
    "campaign_code": "CaMPaiGNCoDe",
    "virtual_currency_amount": 0,
    "is_active": 1,
    "redeems_count_remain": 1,
    "redeems_count_for_user": null,
    "expiration_date": "2014-10-16 21:44:31",
    "virtual_items": {
        "virtual_item": {
            "id": 77,
            "sku": "T-43-3-unique-id",
            "item_code": "chinese-medium-tank",
            "advertisement_type": null,
            "name": {
                "en": "T-34-3"
            },
            "description": {
                "en": "This Chinese Tier VIII medium tank is a real beast in its class."
            },
            "long_description": [],
            "prices": {
                "USD": 40.09
            },
            "default_currency": "USD",
            "enabled": true,
            "permanent": false,
            "purchase_limit": 1,
            "keywords": [],
            "image_url": "http:\/\/livedemo.xsolla.com\/airplanes\/tank5.jpg",
            "groups": [
                25
            ],
            "item_type": "Expiration",
            "expiration": 1296000,
            "virtual_currency_price": null,
            "item_code": null
        },
        "amount": 1
    }
}

Create Campaign

Create a new coupon campaign.

HTTP REQUEST

POST https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/coupon_promotions

Parameter Type Description
merchant_id
integer Merchant ID. Required.
campaign_code
string Campaign name. Required.
project_id
integer Project ID. Required.
campaign_names
object Object containing localized campaign names. Required.
expiration_date
datetime Campaign expiration date in the YYYY-MM-DD’T’HH:MM:SS format per ISO 8601.
virtual_currency_amount
float Virtual currency amount in a reward.
virtual_items
array Array of virtual items parameters in a reward.
virtual_items.sku
string Virtual item SKU. Required if the virtual_items array is passed.
virtual_items.quantity
integer Virtual items quantity. Required if the virtual_items array is passed.
subscription_coupon
object Object containing subscription parameters in a reward.
subscription_coupon.plan_id
integer Subscription plan ID. Required if the subscription_coupon object is passed.
subscription_coupon.product_id
integer Subscription product ID. Required if the subscription_coupon object is passed.
trial_period
integer Trial period duration in days. Required if the subscription_coupon object is passed.
redeems_count
integer Maximum number of coupon redeems. If ‘null’ is passed, the redeems number is unlimited.
redeems_count_for_user
integer Maximum number of coupon redeems per user. If ‘null’ is passed, the redeems number is unlimited.
campaign_redeems_count_for_user
integer Maximum number of coupon redeems per user within a campaign. If ‘null’ is passed, the redeems number is unlimited.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->CreateCouponPromotion(array(
    'merchant_id' => MERCHANT_ID,
    'request' => array(
        'campaign_code' => 'Sample Campaign',
        'project_id' => '27261',
        'campaign_names' =>
            array(
                'en' => 'Sample Campaign',
            ),
         'expiration_date' => null,
         'redeems_count' => 1,
         'redeems_count_for_user' => null,
         'campaign_redeems_count_for_user' => null,
         'virtual_currency_amount' => 10,
         'virtual_items' => array (),
         'subscription_coupon' => null
         ),
));
POST https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/coupon_promotions HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "campaign_code": "Sample Campaign",
    "project_id": "27261",
    "campaign_names": {
        "en": "Sample Campaign"
    },
    "expiration_date": null,
    "redeems_count": 1,
    "redeems_count_for_user": null,
    "campaign_redeems_count_for_user": null,
    "virtual_currency_amount": 10,
    "virtual_items": [],
    "subscription_coupon": null
}
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/coupon_promotions' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "campaign_code": "Sample Campaign",
    "project_id": "27261",
    "campaign_names": {
        "en": "Sample Campaign"
    },
    "expiration_date": null,
    "redeems_count": 1,
    "redeems_count_for_user": null,
    "campaign_redeems_count_for_user": null,
    "virtual_currency_amount": 10,
    "virtual_items": [],
    "subscription_coupon": null
}'
Response
<?php

$response = array (
    'id' => 8612
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 8612
}
{
    "id": 8612
}

Add Coupon to Campaign

Add a coupon code to a coupon campaign.

HTTP REQUEST

POST https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/coupon_promotions/{campaign_id}/coupons

Parameter Type Description
merchant_id
integer Merchant ID. Required.
campaign_id
integer Campaign ID. Required.
coupon_code
string Coupon code. Required.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->CreateCoupon(array(
    'merchant_id' => MERCHANT_ID,
    'campaign_id' => CAMPAIGN_ID,
    'request' => array(
        'coupon_code' => '1029384756'
     ),
));
POST https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/coupon_promotions/{campaign_id}/coupons HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "coupon_code": "1029384756"
}
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/coupon_promotions/{campaign_id}/coupons' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "coupon_code": "1029384756"
}'
Response
<?php

$response = null;
HTTP/1.1 204 No content

Attach Campaign to Promotion

Attach a coupon campaign to a specific promotion.

HTTP REQUEST

PUT https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/coupons

Parameter Type Description
merchant_id
integer Merchant ID. Required.
promotion_id
integer Promotion ID. Required.
campaigns
array of integers Array of campaigns IDs. Required.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->UpdatePromotionCampaigns(array(
    'merchant_id' => MERCHANT_ID,
    'promoiton_id' => PROMOTION_ID,
    'request' => array(
        'id' => '12345',
        'campaigns' =>
            array(
                7863,
                7180
            ),
     ),
));
PUT https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/coupons  HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "id": "12345",
    "campaigns": [
         7863,
         7180
    ]
}
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/coupons' \
-X PUT \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "id": "12345",
    "campaigns": [
         7863,
         7180
    ]
}'
Response
<?php

$response = null;
HTTP/1.1 204 No content

Promotions

Create Promotion

Create a new promotion.

HTTP REQUEST

POST https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions

Parameter Type Description
merchant_id
integer Merchant ID.
technical_name
string Technical name of the promotion.
label
array of strings Array of localized labels to show in the payment UI.
name
array of strings Array of localized promotion names.
description
array of strings Array of localized promotion descriptions.
project_id
integer Project ID.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->CreatePromotion(array(
    'request' => array (
         'technical_name' => 'Sample Promotion',
         'label' =>
              array (
                  'en' => '30% SAVE',
              ),
         'name' =>
             array (
                 'en' => '30% PayPal Discount',
             ),
         'description' =>
             array (
                 'en' => '30% PayPal Discount Sample',
             ),
         'project_id' => 1,
    )
));
POST /merchant/v2/merchants/{merchant_id}/promotions HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "technical_name": "Sample Promotion",
    "label": {
        "en": "30% SAVE"
    },
    "name": {
        "en": "30% PayPal Discount"
    },
    "description": {
        "en": "30% PayPal Discount Sample"
    },
    "project_id": 1
}
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
        "technical_name": "Sample Promotion",
        "label": {
            "en": "30% SAVE"
        },
        "name": {
            "en": "30% PayPal Discount"
        },
        "description": {
            "en": "30% PayPal Discount Sample"
        },
        "project_id": 1
    }'
Response
<?php

// example response
$response = array (
    'id' => 1
);
HTTP/1.1 201 Created

{
    "id": 1
}
{
    "id": 1
}

Get Promotion

Retrieves a promotion.

HTTP REQUEST

GET https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}

Parameter Type Description
merchant_id
integer Merchant ID.
promotion_id
integer Promotion ID.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->GetPromotion(array(
    'promotion_id' => 'PROMOTION_ID'
));
GET /merchant/v2/merchants/{merchant_id}/promotions/{promotion_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}' \
-X GET \
-u merchant_id:merchant_api_key
Response
<?php

// example response
$response = array (
    'id' => 1,
    'project_id' => 1,
    'technical_name' => 'Sample Promotion',
    'name' =>
        array (
            'en' => '30% PayPal Discount'
        ),
    'description' =>
        array (
            'en' => '30% PayPal Discount Sample'
        ),
    'read_only' => false,
    'enabled' => false
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "project_id": 1,
    "technical_name": "Sample Promotion",
    "label": {
        "en": "30% SAVE"
    },
    "name": {
        "en": "30% PayPal Discount"
    },
    "description": {
        "en": "30% PayPal Discount Sample"
    },
    "read_only": false,
    "enabled": false
}
{
    "id": 1,
    "project_id": 1,
    "technical_name": "Sample Promotion",
    "label": {
        "en": "30% SAVE"
    },
    "name": {
        "en": "30% PayPal Discount"
    },
    "description": {
        "en": "30% PayPal Discount Sample"
    },
    "read_only": false,
    "enabled": false
}

Update Promotion

Updates a promotion. If the promotion is read-only (read_only = true), you are not allowed to change “project_id” parameter.

HTTP REQUEST

PUT https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}

Parameter Type Description
merchant_id
integer Merchant ID.
promotion_id
integer Promotion ID.
technical_name
string Technical name of the promotion.
label
array of strings Array of localized labels to show in the payment UI.
name
array of strings Array of localized promotion names.
description
array of strings Array of localized promotion descriptions.
project_id
integer Project ID.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->UpdatePromotion(array(
    'request' => array (
         'technical_name' => 'Sample Promotion',
         'label' =>
              array (
                  'en' => '30% SAVE',
              ),
         'name' =>
             array (
                 'en' => '30% PayPal Discount',
             ),
         'description' =>
             array (
                 'en' => '30% PayPal Discount Sample',
             ),
         'project_id' => 1,
     )
));
PUT /merchant/v2/merchants/{merchant_id}/promotions/{promotion_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "technical_name": "Sample Promotion",
    "label": {
        "en": "30% SAVE"
    },
    "name": {
        "en": "30% PayPal Discount"
    },
    "description": {
        "en": "30% PayPal Discount Sample"
    },
    "project_id": 1
}
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}' \
-X PUT \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
        "technical_name": "Sample Promotion",
        "label": {
            "en": "30% SAVE"
        },
        "name": {
            "en": "30% PayPal Discount"
        },
        "description": {
            "en": "30% PayPal Discount Sample"
        },
        "project_id": 1
    }'
Response
<?php

$response = null;
HTTP/1.1 204 No Content

Review Promotion

You need to review a promotion before activating it. This method returns the list of errors, if any.

HTTP REQUEST

GET https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/review

Parameter Type Description
merchant_id
integer Merchant ID.
promotion_id
integer Promotion ID.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->ReviewPromotion(array(
    'promotion_id' => 'PROMOTION_ID'
));
GET /merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/review HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/review' \
-X GET \
-u merchant_id:merchant_api_key
Response
<?php

// example response
$response = array (
    array (
        'component' => 'rewards',
        'message' => 'You didn\'t select any reward'
    ),
    array (
        'component' => 'periods',
        'message' => 'Please set the promotion time periods.'
    )
);
HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "component": "rewards",
    "message": "You didn't select any reward"
  },
  {
    "component": "periods",
    "message": "Please set the promotion time periods."
  }
]
[
  {
    "component": "rewards",
    "message": "You didn't select any reward"
  },
  {
    "component": "periods",
    "message": "Please set the promotion time periods."
  }
]

Toggle Promotion

Toggles the status of a promotion from enabled to disabled and vice versa.

HTTP REQUEST

PUT https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/toggle

Parameter Type Description
merchant_id
integer Merchant ID.
promotion_id
integer Promotion ID.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->TogglePromotion(array(
    'promotion_id' => 'PROMOTION_ID'
));
PUT /merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/toggle HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/toggle' \
-X PUT \
-u merchant_id:merchant_api_key \
Response
<?php

$response = null;
HTTP/1.1 204 No Content

Delete Promotion

Deletes a promotion. You can only delete promotions with enabled = false.

HTTP REQUEST

DELETE https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}

Parameter Type Description
merchant_id
integer Merchant ID.
promotion_id
integer Promotion ID.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->DeletePromotion(array(
    'promotion_id' => 'PROMOTION_ID'
));
DELETE /merchant/v2/merchants/{merchant_id}/promotions/{promotion_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}' \
-X DELETE \
-u merchant_id:merchant_api_key
Response
<?php

$response = null;
HTTP/1.1 204 No Content

Get Promotions List

List all promotions.

HTTP REQUEST

GET https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions

Parameter Type Description
merchant_id
integer Merchant ID.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->ListPromotions(array(
));
GET /merchant/v2/merchants/{merchant_id}/promotions HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions' \
-X GET \
-u merchant_id:merchant_api_key
Response
<?php

// example response
$response = array (
    array (
        'id' => 1,
        'project' =>
            array (
                'id' => 1,
                'localized_name' => 'Demo Project'
            ),
        'technical_name' => '25% bonus',
        'read_only' => true,
        'enabled' => true,
        'is_active' => false,
        'datetime' =>
            array (
                'from' => '2014-10-15T00:00:00+04:00',
                'to' => '2014-10-16T23:59:59+04:00'
            )
    )
);
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": 1,
        "project": {
            "id": 1,
            "localized_name": "Demo Project"
        },
        "technical_name": "25% bonus",
        "read_only": true,
        "enabled": true,
        "is_active": false,
        "datetime": {
            "from": "2014-10-15T00:00:00+04:00",
            "to": "2014-10-16T23:59:59+04:00"
        }
    }
]
[
    {
        "id": 1,
        "project": {
            "id": 1,
            "localized_name": "Demo Project"
        },
        "technical_name": "25% bonus",
        "read_only": true,
        "enabled": true,
        "is_active": false,
        "datetime": {
            "from": "2014-10-15T00:00:00+04:00",
            "to": "2014-10-16T23:59:59+04:00"
        }
    }
]

Set Subject

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

HTTP REQUEST

PUT https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/subject

Parameter Type Description
merchant_id
integer Merchant ID.
promotion_id
integer Promotion ID.
purchase
boolean Whether the promotion applies to the whole purchase.
items
array Array of virtual items that the promotion applies to.
items.sku
string Item SKU.
packages
array Array of virtual currency packages that the promotion applies to.
subscriptions
object Subscription plans or products that the promotion applies to.
subscriptions.plans
array Array of subscription plans that the promotion applies to.
subscriptions.products
array Array of subscription-based products that the promotion applies to.
subscriptions.max_charges_count
integer Maximum number of billings that the promotion applies to.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->SetPromotionSubject(array(
    'request' => array (
        'purchase' => false,
        'items' => array (
            array (
                'sku' => 't-43-3-unique-id'
            )
        ),
        'packages' => null,
        'subscriptions' =>
            array (
                'plans' =>
                array (
                    array (
                            'id' => 123456
                          )
                ),
                'products' =>
                array (
                    654321
                ),
                'max_charges_count' => null,
            ),
        'digital_contents' =>
            array (
                array (
                    'id' => 1,
                    'localized_name' => 'test',
                    'drm' =>
                        array (
                            array (
                                'id' => 1,
                                'name' => 'Steam',
                            ),
                            array (
                                'id' => 2,
                                'name' => 'Playstation',
                            )
                        )
                )
            )
    )
));
PUT /merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/subject HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "purchase": false,
    "items": [
        {
            "sku":"t-43-3-unique-id"
        }
    ],
    "packages": null,
    "subscriptions": {
        "plans": [
            {
                "id":123456
            }
        ],
        "products": [
            654321
        ],
        "max_charges_count": null
    },
    "digital_contents":[
        {
            "id":1,
            "localized_name":"test",
            "drm":[
                {
                    "id":1,
                    "name":"Steam"
                },
                {
                    "id":2,
                    "name":"Playstation"
                }
            ]
        }
    ]
}
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/subject' \
-X PUT \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
        "purchase": false,
        "items": [
            {
                "sku":"t-43-3-unique-id"
            }
        ],
        "packages": null,
        "subscriptions": {
            "plans": [
            {
                "id":123456
            }
            ],
            "products": [
                654321
            ],
            "max_charges_count": null
        },
        "digital_contents":[
            {
                "id":1,
                "localized_name":"test",
                "drm":[
                    {
                        "id":1,
                        "name":"Steam"
                    },
                    {
                        "id":2,
                        "name":"Playstation"
                    }
                ]
            }
        ]
    }'
Response
<?php

$response = null;
HTTP/1.1 204 No Content

Get Subject

Gets information on the subject of a promotion.

HTTP REQUEST

GET https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/subject

Parameter Type Description
merchant_id
integer Merchant ID.
promotion_id
integer Promotion ID.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->GetPromotionSubject(array(
    'promotion_id' => 'PROMOTION_ID'
));
GET /merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/subject HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/subject' \
-X GET \
-u merchant_id:merchant_api_key
Response
<?php

// example response
$response = array (
    'id' => 1,
    'purchase' => false,
    'items' =>
        array (
            't-43-3-unique-id'
        ),
    'packages' => null,
    'subscriptions' =>
        array (
            'plans' =>
            array (
                array (
                        'id' => 123456,
                        'localized_name' => 'Subscription plan',
                        'external_id' => '894db422'
                      )
            ),
            'products' =>
            array (
                654321
            ),
            'max_charges_count' => null,
        ),
    'digital_contents' => null
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "purchase": false,
    "items": null,
    "packages": null,
    "subscriptions": {
        "plans": [
            {
                "id":123456,
                "localized_name":"Subscription plan",
                "external_id":"894db422"
            }
        ],
        "products": [
            654321
        ],
        "max_charges_count": null
    },
    "digital_contents": null
}
{
    "id": 1,
    "purchase": false,
    "items": null,
    "packages": null,
    "subscriptions": {
        "plans": [
            {
                "id":123456,
                "localized_name":"Subscription plan",
                "external_id":"894db422"
            }
        ],
        "products": [
            654321
        ],
        "max_charges_count": null
    },
    "digital_contents": null
}

Set Payment Systems

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.

HTTP REQUEST

PUT https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/payment_systems

Parameter Type Description
merchant_id
integer Merchant ID.
promotion_id
integer Promotion ID.
payment_systems
array Payment systems (array).
id
integer Payment system ID.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->SetPromotionPaymentSystems(array(
    'request' => array(
         'payment_systems' => array(
             array('id' => 24)
         )
    )
));
PUT /merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/payment_systems HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "payment_systems": [
        {
            "id": 24
        },
        {
            "id": 26
        }
    ]
}
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/payment_systems' \
-X PUT \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
        "payment_systems": [
            {
                "id": 24
            },
            {
                "id": 26
            }
        ]
    }'
Response
<?php

$response = null;
HTTP/1.1 204 No Content

Get Payment Systems

Gets payment systems supported for a promotion. If the list is empty, the promotion will apply to all payment systems.

HTTP REQUEST

GET https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/payment_systems

Parameter Type Description
merchant_id
integer Merchant ID.
promotion_id
integer Promotion ID.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->GetPromotionPaymentSystems(array(
    'promotion_id' => 'PROMOTION_ID'
));
GET /merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/payment_systems HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/payment_systems' \
-X GET \
-u merchant_id:merchant_api_key
Response
<?php

// example response
$response = array (
    'id' => 1,
    'payment_systems' =>
        array (
            array (
                'id' => 24,
                'name' => 'PayPal'
            ),
            array (
                'id' => 26,
                'name' => 'Visa / MasterCard'
            )
        )
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "payment_systems": [
        {
            "id": 24,
            "name": "PayPal"
        },
        {
            "id": 26,
            "name": "Visa / MasterCard"
        }
    ]
}
{
    "id": 1,
    "payment_systems": [
        {
            "id": 24,
            "name": "PayPal"
        },
        {
            "id": 26,
            "name": "Visa / MasterCard"
        }
    ]
}

Set Rewards

Sets the rewards for a promotion. If the promotion is read-only (read_only = true), you cannot update the rewards.

HTTP REQUEST

PUT https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/rewards

Parameter Type Description
merchant_id
integer Merchant ID.
promotion_id
integer Promotion ID.
purchase
object Set the reward for the whole purchase.
purchase.discount_percent
float Discount percentage.
package
object Set the reward for a virtual currency package.
package.bonus_percent
float Reward as a percentage of the package amount.
package.bonus_amount
float Reward as an absolute quantity of the virtual currency.
item
object Set the reward for specific virtual items.
item.discount
array Discounts for specific virtual items.
item.discount[].sku
string Item SKU.
item.discount[].discount_percent
float Discount percentage.
item.discount[].max_amount
integer Maximum number of items to apply the promotion to.
item.bonus
array Extra virtual items given as a bonus.
item.bonus[].sku
string Item SKU.
item.bonus[].amount
integer Number of virtual items given as a bonus.
subscription
object Sets the reward for a subscription.
subscription.trial_days
integer Trial period in days.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->SetPromotionRewards(array(
    'request' => array (
        'purchase' => array (
            'discount_percent' => 10
        ),
        'package' => array (
             'bonus_percent' => 5,
             'bonus_amount' => 5
        ),
        'item' => array (
            'discount' => array (
               array (
                 'sku' => 't-43-3-unique-id',
                 'name' => 'T-34-3',
                 'max_amount' => 10,
                 'discount_percent' => 5
               )
            ),
             'bonus' => array (
                array (
                     'sku' => 't-43-3-unique-id',
                     'name' => 'T-34-3',
                     'amount' => 2
                )
             )
        ),
        'subscription' =>
            array (
               'trial_days' => 30
            )
    )
));
PUT /merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/rewards HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "purchase": {
        "discount_percent": 10
    },
    "package": {
        "bonus_percent": 5,
        "bonus_amount": 5
    },
    "item": {
        "discount": [
            {
                "sku": "t-43-3-unique-id",
                "name": "T-34-3",
                "max_amount": 10,
                "discount_percent": 5
            }
        ],
        "bonus": [
            {
                "sku": "t-43-3-unique-id",
                "name": "T-34-3",
                "amount": 2
            }
        ]
    },
    "subscription": {
        "trial_days": 30
    }
}
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/rewards' \
-X PUT \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
        "purchase": {
            "discount_percent": 10
        },
        "package": {
            "bonus_percent": 5,
            "bonus_amount": 5
        },
        "item": {
            "discount": [
                {
                    "sku": "t-43-3-unique-id",
                    "name": "T-34-3",
                    "max_amount": 10,
                    "discount_percent": 5
                }
            ],
            "bonus": [
                {
                    "sku": "t-43-3-unique-id",
                    "name": "T-34-3",
                    "amount": 2
                }
            ]
        },
        "subscription": {
            "trial_days": 30
        }
    }'
Response
<?php

$response = null;
HTTP/1.1 204 No Content

Get Rewards

Gets the list of rewards associated with a promotion.

HTTP REQUEST

GET https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/rewards

Parameter Type Description
merchant_id
integer Merchant ID.
promotion_id
integer Promotion ID.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->GetPromotionRewards(array(
    'promotion_id' => 'PROMOTION_ID'
));
GET /merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/rewards HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/rewards' \
-X GET \
-u merchant_id:merchant_api_key
Response
<?php

// example response
$response = array (
    'id' => 1,
    'purchase' =>
        array (
            'discount_percent' => 10
        ),
    'package' =>
        array (
            'bonus_percent' => 5,
            'bonus_amount' => 5
        ),
    'item' =>
        array (
            'discount' =>
                array (
                    array (
                        'sku' => 't-43-3-unique-id',
                        'localized_name' => 'T-34-3',
                        'max_amount' => 10,
                        'discount_percent' => 5
                    )
                ),
            'bonus' =>
                array (
                    array (
                        'sku' => 't-43-3-unique-id',
                        'localized_name' => 'T-34-3',
                        'amount' => 2
                    )
                )
        ),
    'subscription' =>
        array (
           'trial_days' => 30
        )
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "purchase": {
        "discount_percent": 10
    },
    "package": {
        "bonus_percent": 5,
        "bonus_amount": 5
    },
    "item": {
        "discount": [
            {
                "sku": "t-43-3-unique-id",
                "localized_name": "T-34-3",
                "max_amount": 10,
                "discount_percent": 5
            }
        ],
        "bonus": [
            {
                "sku": "t-43-3-unique-id",
                "localized_name": "T-34-3",
                "amount": 2
            }
        ]
    },
    "subscription": {
        "trial_days": 30
    }
}
{
    "id": 1,
    "purchase": {
        "discount_percent": 10
    },
    "package": {
        "bonus_percent": 5,
        "bonus_amount": 5
    },
    "item": {
        "discount": [
            {
                "sku": "t-43-3-unique-id",
                "localized_name": "T-34-3",
                "max_amount": 10,
                "discount_percent": 5
            }
        ],
        "bonus": [
            {
                "sku": "t-43-3-unique-id",
                "localized_name": "T-34-3",
                "amount": 2
            }
        ]
    },
    "subscription": {
        "trial_days": 30
    }
}

Set Validity Periods

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.

HTTP REQUEST

PUT https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/periods

Parameter Type Description
merchant_id
integer Merchant ID.
promotion_id
integer Promotion ID.
periods
array Date/time ranges (array).
from
datetime Period start.
to
datetime Period end.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->SetPromotionPeriods(array(
    'request' => array(
         'periods' => array(
             array(
                 'from' => $dateTime->format(\DateTime::ISO8601),
                 'to' => $dateTime->modify('+ 1 month')->format(\DateTime::ISO8601)
             )
         )
    )
));
PUT /merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/periods HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "periods": [
        {
            "from": "2014-10-14T00:00:00+04:00",
            "to": "2014-10-15T00:00:00+04:00"
        }
    ]
}
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/periods' \
-X PUT \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
        "periods": [
            {
                "from": "2014-10-14T00:00:00+04:00",
                "to": "2014-10-15T00:00:00+04:00"
            }
        ]
    }'
Response
<?php

$response = null;
HTTP/1.1 204 No Content

Get Validity Periods

Gets date/time ranges when a promotion is valid.

HTTP REQUEST

GET https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/periods

Parameter Type Description
merchant_id
integer Merchant ID.
promotion_id
integer Promotion ID.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$response = $xsollaClient->GetPromotionPeriods(array(
    'promotion_id' => 'PROMOTION_ID'
));
GET /merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/periods HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/periods' \
-X GET \
-u merchant_id:merchant_api_key
Response
<?php

// example response
$response = array (
    'id' => 1,
    'periods' =>
        array (
            'offset' => '+05:00',
            'from' => '2014-10-14T00:00:00+04:00',
            'to' => '2014-10-15T00:00:00+04:00'
        )
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "periods": [
        {
            "offset": "+05:00",
            "from": "2014-10-14T00:00:00+04:00",
            "to": "2014-10-15T00:00:00+04:00"
        }
    ]
}
{
    "id": 1,
    "periods": [
        {
            "offset": "+05:00",
            "from": "2014-10-14T00:00:00+04:00",
            "to": "2014-10-15T00:00:00+04:00"
        }
    ]
}