CURL
HTTP
PHP
JS

Introduction

Xsolla API uses the REST architecture. The API has predictable, resource-oriented URLs and uses HTTP response codes to indicate API errors.

The API uses built-in HTTP features such as HTTP authentication and HTTP verbs, which can be interpreted by off-the-shelf HTTP clients. It also supports cross-origin resource sharing, allowing you to access it securely from a client web application.

The API always responds in the JSON format, including in case of errors.

Endpoint paths

Xsolla API endpoints are located at https://api.xsolla.com. For example, the full path of the List Projects endpoint is https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/projects.

Most endpoint paths include the merchant_id parameter. This indicates that the application is working on your behalf.

Xsolla Login API endpoints are located at https://login.xsolla.com.

API Endpoint

https://api.xsolla.com
https://api.xsolla.com
https://api.xsolla.com

Request and response

Requests to Xsolla API endpoints must include the following HTTP headers: Authorization, Accept.

POST and PUT requests must include one additional header: Content-Type: application/json

By default, all endpoint responses have JSON data in the response body and include a Content-Type: application/json header.

Headers

Authorization: Basic AUTHORIZATION_BASE64_ENCODED_STRING
Accept: application/json
Content-Type: application/json
Authorization: Basic AUTHORIZATION_BASE64_ENCODED_STRING
Accept: application/json
Content-Type: application/json
Authorization: Basic AUTHORIZATION_BASE64_ENCODED_STRING
Accept: application/json
Content-Type: application/json

API Changes

Xsolla may change the API functionality as follows:

  • Add new API resources;
  • Add optional request parameters;
  • Add new properties to existing API responses;
  • Add new values for existing parameters with enumerable values;
  • Add new webhook types and JSON parameters;
  • Add optional HTTP request headers;
  • Reject any request in which valid parameters contain invalid values;
  • Reject improperly formed requests that were previously accepted due to lenient parsing, if the parsing logic is changed. Add, change, or remove undocumented functionality at any time.

Your client should remain functional regardless of such changes. For example, new JSON parameters that aren’t recognized by your client should not hinder its normal operation.

Versioning

All Xsolla API methods support versioning. We will issue a new version every time there are changes incompatible with the current version. The version is identified by "v1"/"v2"/etc. following the "/merchant" prefix in the URL.

If this is your first time working with the API, use the latest version. If you omit the version, we will use the first version by default. Keep in mind that we can only guarantee API integrity within the same version.

Authentication

Xsolla uses HTTP Basic Authentication. Provide your Merchant ID as the basic auth username and the API key (see Xsolla Publisher Account > Settings) as the password.

All API requests must be sent over HTTPS. Requests via HTTP will not work. Make sure to include authentication details with each request.

Please also note that you must use TLS 1.2 or higher in order to use the API.

Example

<?php

use Xsolla\SDK\API\XsollaClient;

$xsollaClient = XsollaClient::factory(array(
    'merchant_id' => MERCHANT_ID,
    'api_key' => API_KEY
));
GET /merchant/v2/merchants/{merchant_id}/events/messages 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}/events/messages' \
-X GET \
-u merchant_id:merchant_api_key

Endpoint types

The type of an endpoint indicates what kind of data it handles and what action it performs on it. The most common actions are:

Action HTTP method Description
Create
POST Creates and saves an entity of the specified type.
List
GET Returns a list of entities matching the query. To get details on an entity, first find out its ID using the corresponding List endpoint, and then provide this ID to the corresponding Retrieve endpoint.
Retrieve
GET Provides details on the entity with the specified ID.
Replace
PUT Modifies all fields of the entity with the specified ID.
Update
PATCH Modifies specified fields of the entity with the specified ID.
Delete
DELETE Deletes the entity with the specified ID.

Date format

All dates are specified as strings according to ISO 8601. You can specify date strings either in UTC (e.g., 2013-01-15T00:00:00Z), or indicating the UTC offset (e.g., 2013-01-15T00:00:00-08:00 for eight hours behind UTC). In the latter case, make sure to take into account the daylight saving time, if applicable.

Pagination

List endpoints might paginate the results they return. This means that, instead of returning all results in a single response, these endpoints might return some of the results, along with a response header that links to the next set of results. For this purpose we use offset and limit parameters.

Send a follow-up request (including all usual headers) to the next URL to fetch the next set of results. Repeat until you receive a response without any subsequent URL.

Errors handling

Xsolla uses conventional HTTP response codes to indicate whether the API request was successful. In general, 2xx indicates success, 4xx indicates an error in the provided information (e.g., a required parameter missing, failed authorization, etc.), and 5xx indicates a problem with Xsolla's servers.

But not all errors perfectly match HTTP response codes. For example, if a request was valid but failed, the API will return the 422 error code.

All API error responses provide a JSON object with the following fields:

Name Type Description
http_status_code
int HTTP code.
message
string A human-readable message describing the error. This message is always in English. Do not rely on this value for any particular error, because it might change in the future.
extended_message
string More detailed error description.
request_id
string Unique request ID that we might use for troubleshooting.

List of supported HTTP errors:

  • 200, 201, 204 — No error.
  • 400 Bad Request — This often indicates a required parameter missing. Refer to the response body for details.
  • 401 Unauthorized — No valid API key provided.
  • 402 Request Failed — Request failed despite valid parameters.
  • 403 Forbidden — No permission. Refer to the response body for details.
  • 404 Not Found — The requested item doesn't exist.
  • 409, 422 — Invalid request parameters.
  • 412 Precondition Failed — The project has not been activated yet (used in the Get Token method).
  • 415 Unsupported Media Type — "Content-Type: application/json" missing in HTTP header.
  • 500, 502, 503, 504 Server Errors — Something went wrong.

Error response example:

  • {
  • "http_status_code": 500,
  • "message": "Internal Server Error",
  • "extended_message": null,
  • "request_id": "6445b85"
  • }

Token

In order to enable secure payments, Xsolla Payment API handles payment parameters within a token instead of receiving them directly through GET requests to the payment page. You have to obtain a new token before rendering the payment page. A token is valid for 24 hours.

You can create a token with arbitrary user parameters. You send these parameters when obtaining the token, and we send them back to you after a successful payment. A token can only contain parameters either described in this document or predefined by the partner.

Parameter Type Description
user
object User details (object)
user.id
object User ID (object). Required.
user.id.value
string User ID.
user.id.hidden
boolean Whether or not this element can be hidden on Payment UI. 'True' by default.
user.id.allow_modify
boolean Whether or not user can modify the field on Payment UI. 'False' by default.
user.name
object User screen name (object).
user.name.value
string User screen name.
user.name.hidden
boolean Whether or not this element can be hidden on Payment UI. 'True' by default.
user.name.allow_modify
boolean Whether or not user can modify the field on Payment UI. 'False' by default.
user.email
object User email (object).
user.email.value
string User email.
user.email.hidden
boolean Whether or not this element can be hidden on Payment UI. 'True' by default.
user.email.allow_modify
boolean Whether or not user can modify the field on Payment UI. 'False' by default.
user.phone
object User phone number (object).
user.phone.value
string User phone number.
user.phone.hidden
boolean Whether or not this element can be hidden on Payment UI. 'True' by default.
user.phone.allow_modify
boolean Whether or not user can modify the field on Payment UI. 'False' by default.
user.country
object User country (object).
user.country.value
string 2-letter uppercase country code per ISO 3166-1 alpha-2.
user.country.allow_modify
boolean Whether or not user can change the country on Payment UI. 'False' by default.
user.attributes
object User attributes for filtering the item list, represented as a valid JSON set of key-value pairs.
user.steam_id
object User's steam ID (object).
user.steam_id.value
string Steam ID.
user.tracking_id
object User tracking ID (object).
user.tracking_id.value
string Unique tracking ID (used in marketing campaigns).
user.public_id.value
string Parameter that uniquely identifies the user and is known to the user (email, screen name, etc). Allows the user to make purchases outside the game store (e.g., via cash kiosks).
user.utm
object Traffic attributes (object).
user.utm.utm_source
string Traffic source.
user.utm.utm_medium
string Traffic channel (contextual ads, media ads, email lists, etc.).
user.utm.utm_campaign
string Campaign title, transliterated or translated to English.
user.utm.utm_term
string Campaign keyword. If set, statistics will be based on the keywords used for ad targeting rather than on specific search queries. In Google Analytics, the specified utm_term is part of the general search terms report.
user.utm.utm_content
string Campaign content.
settings
object Custom project settings (object).
settings.external_id
string Transaction’s external ID.
settings.project_id
int Game’s Xsolla ID. Can be found in the Publisher Account. Required.
settings.language
string Interface language. 2-letter lowercase language code per ISO 639-1.
settings.return_url
string Page to redirect the user to after payment. Parameters "user_id", "foreinginvoice", "invoice_id" and "status" will be automatically added to the link.
settings.currency
string Preferred payment currency. Three-letter currency code per ISO 4217.
settings.mode
string Set to "sandbox" to test out the payment process. In this case, use https://sandbox-secure.xsolla.com to access the test payment UI.
settings.payment_method
int Payment method identifier.
settings.payment_widget
string Payment widget. Can be 'paybycash' or 'giftcard'. If the parameter is set, the user is redirected to the Pay by Cash or Gift Cards widget, respectively.
settings.ui
object Interface settings (object).
settings.ui.theme
string Payment UI theme. Can be 'default' (default) or 'dark'.
settings.ui.size
string Payment UI size. Can be:
  • small: the least possible size of the payment UI. Use this value when the window size is strictly limited (dimensions: 620 x 630)
  • medium: recommended size. Use this value to display the Payment UI in a lightbox (dimensions: 740 x 760)
  • large: the optimal size for displaying the Payment UI in a new window or tab (dimensions: 820 x 840)
settings.ui.version
string Device type. Can be 'desktop' (default) or 'mobile'.
settings.ui.desktop
object Interface settings for the desktop version (object).
settings.ui.desktop.header
object Header settings (object).
settings.ui.desktop.header.is_visible
boolean Whether to show the header in the payment UI.
settings.ui.desktop.header.visible_logo boolean If true, the header will show your logo (please first provide the image to your account manager).
settings.ui.desktop.header.visible_name
boolean Whether to show the project name in the header.
settings.ui.desktop.header.type
string How to show the header. Can be 'compact' (hides project name and user ID) or 'normal' (default).
settings.ui.desktop.subscription_list
object Settings for the list of subscription plans (object).
settings.ui.desktop.subscription_list.layout
string List template. Can be 'list' (default) or 'grid'.
settings.ui.desktop.subscription_list.description
string Any text to show above the list of available subscription plans in the payment UI.
settings.ui.desktop.subscription_list.display_local_price
boolean If true, and if the user's local currency is different from the one set for the subscription plan, the user will be able to see both prices: one in the local and one in the basic currency.
settings.ui.desktop.virtual_item_list
object Settings for the list of virtual items (object).
settings.ui.desktop.virtual_item_list.layout
string List template. Can be 'list' (default) or 'grid'.
settings.ui.desktop.virtual_item_list.button_with_price
boolean If true, the price will be shown on the button. If false, the price will be shown on the left of the button. False by default.
settings.ui.desktop.virtual_items_list.view
string Display virtual item groups as a vertical/horizontal menu. Can be 'horizontal_navigation' or 'vertical' (default).
settings.ui.desktop.virtual_currency_list
object Settings for the list of virtual currencies (object).
settings.ui.desktop.virtual_currency_list.description
string Any text to show above the list of virtual currencies.
settings.ui.desktop.virtual_currency_list.button_with_price
boolean If true, the price will be shown on the button. If false, the price will be shown on the left of the button. False by default.
settings.ui.header.visible_virtual_currency_balance
boolean Whether or not this element can be hidden on Payment UI. ‘True’ by default.
settings.ui.mobile.mode
string A user can only pay using their saved payment methods. Can be 'saved_accounts'.
settings.ui.mobile.header.close_button
boolean Whether to show the cross button by pressing which the payment interface closes and the user is redirected to the URL specified in the 'settings.return_url' parameter (False by default).
settings.ui.mobile.footer.is_visible
boolean Whether to hide the footer in the mobile version of the payment UI.
settings.ui.license_url
string Link to the EULA.
settings.ui.components
object Menu settings (object).
settings.ui.components.virtual_items
object Virtual items submenu.
settings.ui.components.virtual_items.order
int Position of the submenu in the menu.
settings.ui.components.virtual_items.hidden
boolean Whether to show the submenu.
settings.ui.components.virtual_items.selected_group
string Group to show after opening the virtual items tab.
settings.ui.components.virtual_items.selected_item
string Item to show after opening the virtual items tab (item SKU).
settings.ui.components.virtual_currency
object Virtual currency submenu.
settings.ui.components.virtual_currency.custom_amount
boolean Whether the user can enter an arbitrary quantity of the virtual currency in the payment UI.
settings.ui.components.virtual_currency.order
int Position of the submenu in the menu.
settings.ui.components.virtual_currency.hidden
boolean Whether to show the submenu.
settings.ui.components.subscriptions
object Subscription plans submenu (object).
settings.ui.components.subscriptions.order
int Position of the submenu in the menu.
settings.ui.components.subscriptions.hidden
boolean Whether to show the submenu.
settings.ui.mode
string Interface mode in Pay Station. Can be 'user_account' only: The header contains only the account navigation menu, and the user cannot select a product or make a payment. This mode is only available on the desktop.
settings.ui.user_account
oblect User account details (object).
settings.ui.user_account.info
object Page 'My account'.
settings.ui.user_account.info.order
int Position of the submenu in the menu.
settings.ui.user_account.info.enable
boolean Whether to show the submenu. 'False' by default.
settings.ui.user_account.history
object History submenu.
settings.ui.user_account.history.order
int Position of the submenu in the menu.
settings.ui.user_account.history.enable
boolean Whether to show the submenu. 'False' by default.
settings.ui.user_account.payment_accounts
object "My payment accounts" submenu.
settings.ui.user_account.payment_accounts.order
int Position of the submenu in the menu.
settings.ui.user_account.payment_accounts.enable
boolean Whether to show the submenu. 'False' by default.
settings.ui.user_account.subscriptions
object "Manage subscriptions" submenu.
settings.ui.user_account.subscriptions.order
int Position of the submenu in the menu.
settings.ui.user_account.subscriptions.enable
boolean Whether to show the submenu. 'False' by default.
settings.shipping_enabled
boolean Whether to display the delivery address form. 'False' by default.
purchase
object Object containing purchase details.
purchase.virtual_currency
object Object containing virtual currency details.
purchase.virtual_currency.quantity
float Purchase amount in the virtual currency.
purchase.virtual_currency.currency
string Currency of the virtual currency package to use in all calculations.
purchase.virtual_items
object Object with data about the virtual items in purchase.
purchase.virtual_items.currency
string Currency of the ordered items to use in all calculations.
purchase.virtual_items.items
array Item data (array).
purchase.virtual_items.items.sku
string Item ID.
purchase.virtual_items.items.amount
int Item quantity.
purchase.virtual_items.available_groups
array Item groups IDs (array). The payment UI will only include items within the specified group.
purchase.subscription
object Subscription data (object).
purchase.subscription.plan_id
string Plan ID.
purchase.subscription.product_id
string Product ID.
purchase.subscription.currency
string Currency of the subscription plan to use in all calculations.
purchase.subscription.available_plans
string Subscription plans (array) to show in the Payment UI.
purchase.subscription.trial_days
int Trial period in days. Used only when creating a subscription and only for plans without a trial period defined.
purchase.pin_codes
object PIN codes (object).
purchase.pin_codes.currency
string Currency of a PIN code within the order to use in all calculations.
purchase.pin_codes.codes
array PIN codes (array).
purchase.pin_codes.codes.digital_content
string Game SKU set in the Publisher Account.
purchase.pin_codes.codes.drm
string DRM platform used to distribute the game. Can be 'steam', 'playstation', 'xbox', 'uplay', 'origin', or 'drmfree'. Make sure to have configured the required DRM platforms in your Publisher Account. If not passed in the token, will be chosen by the user in the payment UI.
purchase.checkout
object Object containing checkout details.
purchase.checkout.currency
string Currency of the purchase. Three-letter currency code per ISO 4217.
purchase.checkout.amount
float Purchase amount.
purchase.description
object Purchase description (object).
purchase.description.value
string Purchase description. to include in the UI and email receipts.
purchase.gift
object Object with data about the gift.
purchase.gift.giver_id
string Giver ID.
purchase.gift.message
string Message from the giver.
purchase.gift.hide_giver_from_receiver
string Whether to hide the giver identity from the recipient ('true' by default)
purchase.gift.friends
array Array with data on friends.
purchase.gift.friends.id
string ID.
purchase.gift.friends.name
string Nickname.
purchase.gift.friends.email
string Gift recipient email.
custom_parameters
object Your custom parameters, represented as a valid JSON set of key-value pairs.

If any parameter is sent in the wrong format or has the wrong type, no token will be issued. You will receive a 422 HTTP code with the error description in the JSON body. In "extended_message" we will provide you an information what exactly parameters have been send incorrectly. { "extended_message": { "global_errors": [], "property_errors": { "settings.project_id": [ "string value found, but an integer is required" ] } } }

Request

<?php

use Xsolla\SDK\API\XsollaClient;
use Xsolla\SDK\API\PaymentUI\TokenRequest;

$tokenRequest = new TokenRequest($projectId, $userId);
$tokenRequest->setUserEmail('email@example.com')
    ->setExternalPaymentId('12345')
    ->setSandboxMode(true)
    ->setUserName('USER_NAME')
    ->setCustomParameters(array('key1' => 'value1', 'key2' => 'value2'));

$xsollaClient = XsollaClient::factory(array(
    'merchant_id' => MERCHANT_ID,
    'api_key' => API_KEY
));
$token = $xsollaClient->createPaymentUITokenFromRequest($tokenRequest);
POST /merchant/v2/merchants/{merchant_id}/token HTTP/1.1
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
  "user": {
          "id": {
              "value": "1234567",
              "hidden": true
          },
          "email": {
              "value": "email@example.com",
              "allow_modify": true,
              "hidden": false
          },
          "country": {
              "value": "US"
          }
      },
      "settings": {
          "project_id": 14004,
          "language":"en",
          "currency":"USD",
          "ui": {
              "size":"medium"
          }
      },
      "purchase": {
          "virtual_currency": {
              "quantity": 100
          },
          "virtual_items": {
              "items": [{
                  "sku":"SKU01",
                  "amount":1
              }]
          },
          "description": {
              "value": "Test Purchase"
          }
      },
      "custom_parameters": {
          "parameter1": "value1"
      }
}
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "user": {
      "id": {
          "value": "1234567",
          "hidden": true
      },
      "email": {
          "value": "email@example.com",
          "allow_modify": true,
          "hidden": false
      },
      "country": {
          "value": "US"
      }
  },
  "settings": {
      "project_id": 14004,
      "language":"en",
      "currency":"USD",
      "ui": {
          "size":"medium"
      }
  },
  "purchase": {
      "virtual_currency": {
          "quantity": 100
      },
      "virtual_items": {
          "items": [{
              "sku":"SKU01",
              "amount":1
          }]
      },
      "description": {
          "value": "Test Purchase"
      }
  },
  "custom_parameters": {
      "parameter1": "value1"
  }
    }'

Response

<?php

// example response
$token = 'uV0iCEvWkUGVqWerTgbrndWePOMiLAfO';
HTTP/1.1 200 OK
Content-Type: application/json

{
    "token": "uV0iCEvWkUGVqWerTgbrndWePOMiLAfO"
}
{
    "token": "uV0iCEvWkUGVqWerTgbrndWePOMiLAfO"
}

List Additional Parameters

You can pass additional parameters in the token in order to configure anti-fraud filters. The recommended parameters are shown in the table below. You can extend the list as needed.

Name Type Description
registration_date
string Account creation date per ISO 8601.
total_hours
int Total number of in-game hours.
total_characters
int Number of in-game characters.
social_networks_added
boolean Whether the player has connected social media profiles.
profile_image_added
boolean Whether the player has uploaded a profile image.
last_active_date
string Last seen date per ISO 8601.
total_friends
int Number of friends.
additional_verification
boolean Whether the player uses account verification procedures.
win_rate
int Win rate.
last_change_password_date
string Last password change date per ISO 8601.
chat_activity
boolean Whether the player uses the chat function.
forum_activity
boolean Whether the player has uploaded a profile image.
total_bans
int Number of times the player was banned in the chat/forum.
profile_completed
boolean Whether the player added additional information to their profile.
notifications_enabled
boolean Whether the player enabled notifications.
user_level
int Player’s level, reputation, or rank.
karma_points
int Player’s karma.
total_sum
float Total amount of payments.
non_premium_currency
float Amount of non-premium currency.
total_game_events
int Number of in-game events the player took part in.
total_gifts
int Number of in-game gifts the player has sent/received.
tutorial_completed
boolean Whether the player has completed the game’s tutorial.
completed_tasks
int Number of tasks/objectives completed.
items_used
boolean Whether the player uses purchased in-game items.
pvp_activity
boolean Whether the player takes part in PvP battles.
total_clans
int Number of clans the player is a member of.
unlocked_achievements
int Number of achievements unlocked.
total_inventory_value
float Total inventory value (in-game currency).
character_customized
boolean Whether the player has customized their character.
session_time
string Average session time per ISO 8601.

Pay Station UI

Pay Station is a complete payment UI that allows your users to purchase games and items on your website. To easily implement the payment UI on your website, download the following script from our CDN: link. Use this URL to integrate the script on your website. For more information please visit our GitHub repository.

Script initialization parameters:

Parameter Type Description
access_token
string Pay Station 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.
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
int Defines arrangement order. Default is 1000.
lightbox.overlayOpacity
int 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'.

The script allows you to track payment UI events. Depending on the event type, you can perform various actions on the web page.

List of events:

Parameter Description
init
Widget initialized.
open
Widget opened.
load
Payment UI (Pay Station) loaded.
close
Payment UI (Pay Station) closed.
status
User is on the status page.
status-invoice
User is on the status page; payment in progress.
status-delivering
Event when the user was moved on the status page, payment was completed, and we're sending payment notification.
status-done
User is on the status page; payment credited to the user's account.
status-troubled
Event when the user was moved on the status page, but the payment failed.

If you want to initialize the opening of the payment UI by yourself, use this link: https://secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN, where ACCESS_TOKEN is the token received in the previous step

Example: Asynchronous script loading with a callback

<html>
<head lang="en">
    <meta charset="UTF-8">
</head>
<body>
    <button data-xpaystation-widget-open>Buy Credits</button>

    <?php \Xsolla\SDK\API\PaymentUI\PaymentUIScriptRenderer::send($paymentUIToken, $isSandbox = true); ?>
</body>
</html>
<script>
    var options = {
        access_token: 'abcdef1234567890abcdef1234567890'
    };
    var s = document.createElement('script');
    s.type = "text/javascript";
    s.async = true;
    s.src = "https://static.xsolla.com/embed/paystation/1.0.7/widget.min.js";
    s.addEventListener('load', function (e) {
        XPayStationWidget.init(options);
    }, false);
    var head = document.getElementsByTagName('head')[0];
    head.appendChild(s);
</script>

<button data-xpaystation-widget-open>Buy Credits</button>

List of Test Credit Cards

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

Card Number Exp. Date CVV2 3D-Secure Card Type
4111111111111111
12/20 123 No VISA
5555555555554444
11/19 321 No MasterCard
4000000000000010
12/20 123 Yes VISA
5200000000000114
11/19 321 Yes MasterCard
6759649826438453
12/25 321 Yes Maestro

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

Card Number Exp. Date CVV2 3D-Secure Card Type Description
4000000000000002
12/20 123 No VISA Insufficient funds
5200000000000007
11/19 321 No MasterCard Insufficient funds
4000000000000036
12/20 123 Yes VISA Declined
5200000000000031
11/19 321 Yes MasterCard Declined

Pay2Play Widget

Pay2Play Widget makes it easier for you to implement a payment UI on your website. 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 ourGitHub repository.

There are two options for integrating Pay2Play:

  1. Simple Integration
  2. Advanced Integration

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

Simple 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 for the widget, received viaAPI. 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
int Defines arrangement order. Default is 1000.
lightbox.overlayOpacity
int 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'.

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.

Example: Asynchronous script loading with a callback for simple 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.0/widget.min.js";
    s.addEventListener('load', function (e) {
        var widgetInstance = XPay2PlayWidget.create(options);
    }, false);
    var head = document.getElementsByTagName('head')[0];
    head.appendChild(s);
</script>
<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.0/widget.min.js";
    s.addEventListener('load', function (e) {
        var widgetInstance = XPay2PlayWidget.create(options);
    }, false);
    var head = document.getElementsByTagName('head')[0];
    head.appendChild(s);
</script>

Example: 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.0/widget.min.js";
    s.addEventListener('load', function (e) {
        var widgetInstance = XPay2PlayWidget.create(options);
    }, false);
    var head = document.getElementsByTagName('head')[0];
    head.appendChild(s);
</script>
<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.0/widget.min.js";
    s.addEventListener('load', function (e) {
        var widgetInstance = XPay2PlayWidget.create(options);
    }, false);
    var head = document.getElementsByTagName('head')[0];
    head.appendChild(s);
</script>

List of Errors

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
Serverless integration prohibited
0010-0001
Digital content not found
0010-0003
Digital content has no DRM configured
1000-0003
No payment modules turned on for the project

List Storefront Virtual Currency Packages

Lists all virtual currency packages for the storefront.

HTTP REQUEST

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

Request Parameters:

Parameter Type Description
project_id
int Project ID. Required.
user_id
string User ID. Required.
currency
string Currency of the virtual currency package. Three-letter currency code per ISO 4217. Required.
language
string Interface language. Two-letter lowercase language code per ISO 639-1. Required.

Response Parameters:

Parameter Type Description
packages
array Virtual currency packages (array of objects).
packages.id
int Virtual currency package ID in Xsolla database.
packages.quantity
float Virtual currency quantity.
packages.quantity_without_discount
float Undiscounted quantity (in case of promotion).
packages.bonus_quantity
float Virtual currency quantity given as a bonus (in case of promotion).
packages.amount
float Virtual currency package price (in the currency defined in the request).
packages.amount_without_discount
float Undiscounted virtual currency package price (in case of promotion).
packages.currency
string Currency used to purchase the virtual currency package. Three-letter currency code per ISO 4217.
packages.image
string URL of the image to be used for the package.
packages.description
string Package description (in the language defined in the request).
packages.bonus_items
array Virtual items to be given as a bonus (in case of promotion).
packages.bonus_items.name
string Item name.
packages.bonus_items.quantity
int Quantity.
packages.advertisement_label
object Package label (object).
packages.advertisement_label.type
string Label type. Can be "recommended", "best_deal", "special_offer", or null.
packages.advertisement_label.name
string Localized label name, depending on packages.advertisement_label.type.
packages.offer_label
string Promotion label.

Request

<?php

$response = $xsollaClient->GetStorefrontVirtualCurrency(array(
    'project_id' => PROJECT_ID,
    'language' => LANGUAGE_ISO,
    'currency' => CURRENCY_ISO,
    'user_id' => USER_ID
));
GET /merchant/v2/projects/{project_id}/storefront/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}/storefront/virtual_currency' \
-X GET \
-u merchant_id:merchant_api_key

Response

<?php

// example response
$response = array (
    'packages' =>
        array (
            array (
                'id' => 16913,
                'quantity' => 500,
                'quantity_without_discount' => 500,
                'bonus_quantity' => 10,
                'amount' => 4,
                'amount_without_discount' => 4.99,
                'currency' => 'USD',
                'image' => '//cdn2.xsolla.com/img/misc/images/5df58528dee219c2ab48e003f8f1a8f1.jpg',
                'description' => '500 Gold',
                'bonus_items' =>
                    array (
                        array (
                            'name' => 'Rabbit',
                            'quantity' => 1,
                        ),
                    ),
                'advertisement_label' =>
                    array (
                        'type' => 'recommended',
                        'name' => 'Most Popular',
                    ),
                'offer_label' => '',
            ),
        ),
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "packages": [
        {
            "id": 16913,
            "quantity": 500,
            "quantity_without_discount": 500,
            "bonus_quantity": 10,
            "amount": 4,
            "amount_without_discount": 4.99,
            "currency": "USD",
            "image": "\/\/cdn2.xsolla.com\/img\/misc\/images\/5df58528dee219c2ab48e003f8f1a8f1.jpg",
            "description": "500 Gold",
            "bonus_items": [
                {
                    "name": "Rabbit",
                    "quantity": 1
                }
            ],
            "advertisement_label": {
                "type": "recommended",
                "name": "Most Popular"
            },
            "offer_label": ""
         }
    ]
}
{
    "packages": [
        {
            "id": 16913,
            "quantity": 500,
            "quantity_without_discount": 500,
            "bonus_quantity": 10,
            "amount": 4,
            "amount_without_discount": 4.99,
            "currency": "USD",
            "image": "\/\/cdn2.xsolla.com\/img\/misc\/images\/5df58528dee219c2ab48e003f8f1a8f1.jpg",
            "description": "500 Gold",
            "bonus_items": [
                {
                    "name": "Rabbit",
                    "quantity": 1
                }
            ],
            "advertisement_label": {
                "type": "recommended",
                "name": "Most Popular"
            },
            "offer_label": ""
         }
    ]
}

List Storefront Groups

Lists all groups of virtual items.

HTTP REQUEST

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

Request Parameters:

Parameter Type Description
project_id
int Project ID. Required.
user_id
string User ID. Required.
currency
string Currency of the virtual currency package. Three-letter currency code per ISO 4217. Required.
language
string Interface language. Two-letter lowercase language code per ISO 639-1. Required.

Response Parameters:

Parameter Type Description
groups
array Groups of virtual items.
groups.id
int Group ID in Xsolla database.
groups.external_id
string Group external ID.
groups.name
string Localized group name.
groups.description
string Localized group description.
groups.level
int Group level.
groups.children
array Child groups, each having the same structure as the parent group.

Request

<?php

$response = $xsollaClient->GetStorefrontVirtualGroups(array(
    'project_id' => PROJECT_ID,
    'language' => LANGUAGE_ISO,
    'currency' => CURRENCY_ISO,
    'user_id' => USER_ID
));
GET /merchant/v2/projects/{project_id}/storefront/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}/storefront/virtual_items/groups' \
-X GET \
-u merchant_id:merchant_api_key

Response

<?php

// example response
$response = array (
    'groups' =>
        array (
            array (
                'id' => 1,
                'external_id' => '21',
                'name' => 'Group name 21',
                'description' => 'Group description 21',
                'children' =>
                    array (),
                'level' => 0,
            ),
            array (
                'id' => 2,
                'external_id' => '22',
                'name' => 'Group name 22',
                'description' => 'Group description 22',
                'children' =>
                    array (
                        array (
                            'id' => 3,
                            'external_id' => NULL,
                            'name' => 'Child group 1',
                            'description' => 'Child group 1',
                            'children' =>
                                array (),
                            'level' => 1,
                        ),
                        array (
                            'id' => 8,
                            'external_id' => NULL,
                            'name' => 'Child group 2',
                            'description' => 'Child group 2',
                            'children' =>
                                array (),
                            'level' => 1,
                        ),
                    ),
                'level' => 0,
            ),
        ),
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "groups": [
        {
            "id": 1,
            "external_id": "21",
            "name": "Group name 21",
            "description": "Group description 21",
            "children": [],
            "level": 0
        },
        {
            "id": 2,
            "external_id": "22",
            "name": "Group name 22",
            "description": "Group description 22",
            "children": [
                {
                    "id": 3,
                    "external_id": null,
                    "name": "Child group 1",
                    "description": "Child group 1",
                    "children": [],
                    "level": 1
                },
                {
                    "id": 8,
                    "external_id": null,
                    "name": "Child group 2",
                    "description": "Child group 2",
                    "children": [],
                    "level": 1
                }
            ],
            "level": 0
        }
    ]
}
{
    "groups": [
        {
            "id": 1,
            "external_id": "21",
            "name": "Group name 21",
            "description": "Group description 21",
            "children": [],
            "level": 0
        },
        {
            "id": 2,
            "external_id": "22",
            "name": "Group name 22",
            "description": "Group description 22",
            "children": [
                {
                    "id": 3,
                    "external_id": null,
                    "name": "Child group 1",
                    "description": "Child group 1",
                    "children": [],
                    "level": 1
                },
                {
                    "id": 8,
                    "external_id": null,
                    "name": "Child group 2",
                    "description": "Child group 2",
                    "children": [],
                    "level": 1
                }
            ],
            "level": 0
        }
    ]
}

List Storefront Virtual Items

Lists all virtual items in the storefront.

HTTP REQUEST

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

Request Parameters:

Parameter Type Description
project_id
int Project ID. Required.
user_id
string User ID. Required.
group_id
int Virtual item group ID. Required.
currency
string Currency of the virtual currency package. Three-letter currency code per ISO 4217. Required.
language
string Interface language. Two-letter lowercase language code per ISO 639-1. Required.

Response Parameters:

Parameter Type Description
items
array Virtual items (array of objects).
items.id
int Virtual item ID in Xsolla database.
items.sku
string Virtual item SKU.
items.name
string Localized name.
items.image_url
string URL of the image to be used for the virtual item.
items.description
string Localized description.
items.long_description
string Extended localized description.
items.currency
string Currency to be used for purchasing the virtual item. Three-letter currency code per ISO 4217.
items.amount
float Virtual item price (in the currency defined in the request).
items.amount_without_discount
float Undiscounted virtual item price (in case of promotion).
items.vc_amount
float Virtual item price in the virtual currency.
items.vc_amount_without_discount
float Undiscounted virtual item price in the virtual currency (in case of promotion).
items.bonus_virtual_currency
object Virtual currency given as a bonus (in case of promotion).
items.bonus_virtual_currency.vc_amount
float Quantity of the virtual currency.
items.bonus_virtual_items
array Virtual items given as a bonus (in case of promotion).
items.bonus_virtual_items.name
string Localized name.
items.bonus_virtual_items.quantity
int Quantity.
items.advertisement_label
object Virtual item label (object).
items.advertisement_label.type
string Label type. Can be "recommended", "best_deal", "special_offer", or null.
items.advertisement_label.name
string Localized label name, depending on items.advertisement_label.type.
items.offer_label
string Promotion label.

Request

<?php

$response = $xsollaClient->GetStorefrontVirtualItems(array(
    'project_id' => PROJECT_ID,
    'language' => LANGUAGE_ISO,
    'currency' => CURRENCY_ISO,
    'user_id' => USER_ID,
    'group_id' => GROUP_ID
));
GET /merchant/v2/projects/{project_id}/storefront/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}/storefront/virtual_items/items' \
-X GET \
-u merchant_id:merchant_api_key

Response

<?php

// example response
$response = array (
    'items' =>
        array (
            array (
                'id' => 1678,
                'sku' => '1468',
                'name' => 'Rabbit',
                'image_url' => 'https://cdn3.xsolla.com/img/misc/merchant-digital-goods/4376c004fa33dc74483906561d617cb3.png',
                'description' => 'Rabbits are small mammals in the family Leporidae',
                'long_description' => NULL,
                'currency' => 'USD',
                'amount' => 0,
                'amount_without_discount' => 0,
                'vc_amount' => 2,
                'vc_amount_without_discount' => 2,
                'bonus_virtual_currency' => NULL,
                'bonus_virtual_items' =>
                    array (),
                'advertisement_label' => NULL,
                'offer_label' => '',
            ),
        ),
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "items": [
        {
            "id": 1678,
            "sku": "1468",
            "name": "Rabbit",
            "image_url": "https:\/\/cdn3.xsolla.com\/img\/misc\/merchant-digital-goods\/4376c004fa33dc74483906561d617cb3.png",
            "description": "Rabbits are small mammals in the family Leporidae",
            "long_description": null,
            "currency": "USD",
            "amount": 0,
            "amount_without_discount": 0,
            "vc_amount": 2,
            "vc_amount_without_discount": 2,
            "bonus_virtual_currency": null,
            "bonus_virtual_items": [],
            "advertisement_label": null,
            "offer_label": ""
        }
    ]
}
{
    "items": [
        {
            "id": 1678,
            "sku": "1468",
            "name": "Rabbit",
            "image_url": "https:\/\/cdn3.xsolla.com\/img\/misc\/merchant-digital-goods\/4376c004fa33dc74483906561d617cb3.png",
            "description": "Rabbits are small mammals in the family Leporidae",
            "long_description": null,
            "currency": "USD",
            "amount": 0,
            "amount_without_discount": 0,
            "vc_amount": 2,
            "vc_amount_without_discount": 2,
            "bonus_virtual_currency": null,
            "bonus_virtual_items": [],
            "advertisement_label": null,
            "offer_label": ""
        }
    ]
}

List Storefront Subscription Plans

Retrieves the list of all subscription plans.

HTTP REQUEST

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

Request Parameters:

Parameter Type Description
project_id
int Project ID. Required.
user_id
string User ID. Required.
currency
string Currency of the virtual currency package. Three-letter currency code per ISO 4217. Required.
language
string Interface language. Two-letter lowercase language code per ISO 639-1. Required.

Response parameters:

Parameter Type Description
packages
array Subscription plans (array of objects).
packages.id
int Subscription plan ID in Xsolla database.
packages.is_active
boolean Whether the plan is active.
packages.charge_amount
float Plan price.
packages.charge_amount_without_discount
float Non-discounted plan price (in case of promotion).
packages.charge_currency
string Plan currency. Three-letter currency code per ISO 4217.
packages.period
int Billing cycle (number of time units).
packages.period_unit
string Time unit for the billing cycle (day/month).
packages.name
string Localized name.
packages.description
string Localized description.
packages.bonus_virtual_currency
object Virtual currency given as a bonus (in case of promotion).
packages.bonus_virtual_currency.vc_amount
float Quantity of the virtual currency.
packages.bonus_virtual_items
array Virtual items given as a bonus (in case of promotion).
packages.bonus_virtual_items.name
string Localized name.
packages.bonus_virtual_items.quantity
int Quantity.
packages.offer_label
string Promotion label.
packages.is_trial
boolean Whether to use a trial period for the plan.
packages.period_trial
int Trial period in days.
active_user_package
object User's active subscriptions (object).
active_user_package.date_next_charge
string Next billing date for an active subscription. Date and time per ISO 8601.
active_user_package.id
string Active subscription plan ID.

Request

<?php

$response = $xsollaClient->GetStorefrontSubscriptions(array(
    'project_id' => PROJECT_ID,
    'language' => LANGUAGE_ISO,
    'currency' => CURRENCY_ISO,
    'user_id' => USER_ID
));
GET /merchant/v2/projects/{project_id}/storefront/subscriptions 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}/storefront/subscriptions' \
-X GET \
-u merchant_id:merchant_api_key

Response

<?php

// example response
$response = array (
    'packages' =>
        array (
            array (
                'id' => '2.99_1_months',
                'is_active' => true,
                'charge_amount' => 2.99,
                'charge_amount_without_discount' => 2.99,
                'charge_currency' => 'USD',
                'period' => 1,
                'period_unit' => 'month',
                'name' => 'Silver Status',
                'description' => NULL,
                'bonus_virtual_currency' => NULL,
                'bonus_virtual_items' =>
                    array (),
                'offer_label' => '',
                'is_trial' => false,
                'period_trial' => 0,
            ),
            array (
                'id' => '4.99_1_months',
                'is_active' => true,
                'charge_amount' => 4.99,
                'charge_amount_without_discount' => 4.99,
                'charge_currency' => 'USD',
                'period' => 1,
                'period_unit' => 'month',
                'name' => 'Gold Status',
                'description' => NULL,
                'bonus_virtual_currency' => NULL,
                'bonus_virtual_items' =>
                    array (),
                'offer_label' => '',
                'is_trial' => false,
                'period_trial' => 0,
            ),
        ),
    'active_user_package' =>
        array (
            'date_next_charge' => '2016-06-28T06:35:02+00:00',
            'id' => '2.99_1_months'
        )
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "packages": [
        {
            "id": "2.99_1_months",
            "is_active": true,
            "charge_amount": 2.99,
            "charge_amount_without_discount": 2.99,
            "charge_currency": "USD",
            "period": 1,
            "period_unit": "month",
            "name": "Silver Status",
            "description": null,
            "bonus_virtual_currency": null,
            "bonus_virtual_items": [],
            "offer_label": "",
            "is_trial": false,
            "period_trial": 0
        },
        {
            "id": "4.99_1_months",
            "is_active": true,
            "charge_amount": 4.99,
            "charge_amount_without_discount": 4.99,
            "charge_currency": "USD",
            "period": 1,
            "period_unit": "month",
            "name": "Gold Status",
            "description": null,
            "bonus_virtual_currency": null,
            "bonus_virtual_items": [],
            "offer_label": "",
            "is_trial": false,
            "period_trial": 0
        }
    ],
    "active_user_package": {
            "date_next_charge": "2016-06-28T06:35:02+00:00",
            "id": "2.99_1_months"
        }
}
{
    "packages": [
        {
            "id": "2.99_1_months",
            "is_active": true,
            "charge_amount": 2.99,
            "charge_amount_without_discount": 2.99,
            "charge_currency": "USD",
            "period": 1,
            "period_unit": "month",
            "name": "Silver Status",
            "description": null,
            "bonus_virtual_currency": null,
            "bonus_virtual_items": [],
            "offer_label": "",
            "is_trial": false,
            "period_trial": 0
        },
        {
            "id": "4.99_1_months",
            "is_active": true,
            "charge_amount": 4.99,
            "charge_amount_without_discount": 4.99,
            "charge_currency": "USD",
            "period": 1,
            "period_unit": "month",
            "name": "Gold Status",
            "description": null,
            "bonus_virtual_currency": null,
            "bonus_virtual_items": [],
            "offer_label": "",
            "is_trial": false,
            "period_trial": 0
        }
    ],
    "active_user_package": {
            "date_next_charge": "2016-06-28T06:35:02+00:00",
            "id": "2.99_1_months"
        }
}

Get Storefront Promotion

Retrieves the currently active promotion.

HTTP REQUEST

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

Request Parameters:

Parameter Type Description
project_id
int Project ID. Required.
user_id
string User ID. Required.
currency
string Currency of the virtual currency package. Three-letter currency code per ISO 4217. Required.
language
string Interface language. Two-letter lowercase language code per ISO 639-1. Required.

Response parameters:

Parameter Type Description
seconds
int Seconds left till the end of the promotion.
name
string Localized promotion name.
description
string Localized promotion description.

Request

<?php

$response = $xsollaClient->GetStorefrontBonus(array(
    'project_id' => PROJECT_ID,
    'language' => LANGUAGE_ISO,
    'currency' => CURRENCY_ISO,
    'user_id' => USER_ID
));
GET /merchant/v2/projects/{project_id}/storefront/bonus 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}/storefront/bonus' \
-X GET \
-u merchant_id:merchant_api_key

Response

<?php

// example response
$response = array (
    'seconds' => 619513283,
    'name' => 'Promotion name',
    'description' => 'Promotion description',
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "seconds": 619513283,
    "name": "Promotion name",
    "description": "Promotion description"
}
{
    "seconds": 619513283,
    "name": "Promotion name",
    "description": "Promotion description"
}

List Saved Payment Accounts

Lists saved payment accounts of a given user.

HTTP REQUEST

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

Parameter Type Description
project_id
int Game ID.
user_id
string ID user.

Request

<?php

$response = $xsollaClient->ListPaymentAccounts(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID
));
GET /merchant/v2/projects/{project_id}/users/{user_id}/payment_accounts 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}/payment_accounts' \
-X GET \
-u merchant_id:merchant_api_key

Response

<?php

// example response
$response = array (
    array (
        'type' => 'card',
        'id' => 1,
        'name' => '411111******1111',
        'payment_system' =>
            array (
                'id' => 1380,
                'name' => 'Credit/Debit Cards',
            ),
    ),
);
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "type": "card",
        "id": 1,
        "name": "411111******1111",
        "payment_system": {
            "id": 1380,
            "name": "Credit/Debit Cards"
        }
    }
]
[
    {
        "type": "card",
        "id": 1,
        "name": "411111******1111",
        "payment_system": {
            "id": 1380,
            "name": "Credit/Debit Cards"
        }
    }
]

Charge via Saved Payment Account

Charges a user via a saved payment account.

HTTP REQUEST

POST https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/payments/{type}/{account_id}

Parameter Type Description
project_id
int Game ID. Required.
user_id
int User ID. Required.
type
string Type of payment account: card / PayPal. Required.
account_id
int ID of the saved account in Xsolla database. Required.
user
object Object containing user details.
user.ip
string User IP address. Required.
user.name
string User name.
purchase
object Object containing purchase details.
purchase.virtual_currency
object Object containing virtual currency details.
purchase.virtual_currency.quantity
float Purchase amount in the virtual currency.
purchase.checkout
object Object containing checkout details.
purchase.checkout.currency
string Currency of the purchase. Three-letter currency code per ISO 4217.
purchase.checkout.amount
float Purchase amount.
settings
object Object containing purchase settings.
settings.mode
string Set to "sandbox" to test out the payment process. Remove the parameter for real payments.

Request

<?php

$response = $xsollaClient->ChargePaymentAccount(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID,
    'type' => TYPE,
    'account_id' => ACCOUNT_ID,
    'request' => array (
         'user' =>
             array (
                 'ip' => '127.0.0.1',
                 'name' => 'John Smith',
             ),
         'purchase' =>
             array (
                 'virtual_currency' =>
                     array (
                         'quantity' => 100,
                     ),
                 'description' =>
                     array (
                         'value' => 'Test Purchase',
                     ),
             ),
         'settings' =>
             array (
                 'mode' => 'sandbox',
             ),
    )
));
POST /merchant/v2/projects/{project_id}/users/{user_id}/payments/{type}/{account_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

{
    "user": {
        "ip": "127.0.0.1",
        "name": "John Smith"
    },
    "purchase": {
        "virtual_currency": {
            "quantity": 100
        },
        "description": {
            "value": "Test Purchase"
        }
    },
    "settings": {
        "mode": "sandbox"
    }
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/payments/{type}/{account_id}' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "user": {
        "ip": "127.0.0.1",
        "name": "John Smith"
    },
    "purchase": {
        "virtual_currency": {
            "quantity": 100
        },
        "description": {
            "value": "Test Purchase"
        }
    },
    "settings": {
        "mode": "sandbox"
    }
}'

Response

<?php

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

{
    "transaction_id": 119478390
}
{
    "transaction_id": 119478390
}

Delete Saved Payment Account

Deletes a saved payment account.

HTTP REQUEST

DELETE https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id}

Parameter Type Description
project_id
int Game ID.
user_id
string User ID.
type
string Type of payment account: card / PayPal.
account_id
int ID of the saved account in Xsolla database.

Request

<?php

$response = $xsollaClient->DeletePaymentAccount(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID,
    'type' => TYPE,
    'account_id' => ACCOUNT_ID
));
DELETE /merchant/v2/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_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}/users/{user_id}/payment_accounts/{type}/{account_id}' \
-X DELETE \
-u merchant_id:merchant_api_key

Response

<?php

// example response
$response = null;
HTTP/1.1 204 No Content

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
int Game 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.
charge
object Billing details (object).
charge.period
object Billing period (object).
charge.period.value
int 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
int Validity time.
expiration.type
string Time unit: day / month.
trial
object Trial period details (object). Optional.
trial.value
int Trial period.
trial.type
string Time unit: day.
grace_period
object Grace period details. Optional.
grace_period.value
int Grace period.
grace_period.type
string Time unit: day.

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' => '',
             ),
     )

));
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": ""
    }
}
$ 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": ""
    }
}'

Response

<?php

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

{
    "plan_id": 54
}
{
    "plan_id": 54
}

Update Plan

Updates a subscription plan.

HTTP REQUEST

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

Parameter Type Description
project_id
int Game ID.
plan_id
int 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.
charge
object Billing details (object).
charge.period
object Billing period (object).
charge.period.value
int 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
int Validity time.
expiration.type
string Time unit: day / month.
trial
object Trial period details (object). Optional.
trial.value
int Trial period.
trial.type
string Time unit: day.
grace_period
object Grace period details. Optional.
grace_period.value
int Grace period.
grace_period.type
string Time unit: day.

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' => '',
             ),
     )
));
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": ""
    }
}
$ 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": ""
    }
}'

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

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
int Game ID.
plan_id
int Plan ID.

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

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
int Game ID.
plan_id
int Plan ID.

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

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
int Game ID.
plan_id
int Plan ID.

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

List Plans

Lists all subscription plans.

HTTP REQUEST

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

Parameter Type Description
project_id
int Game ID.
external_id
string Plan external ID.
limit
int Maximum number of records to retrieve.
offset
int Offset of the first record to retrieve.
group_id
string ID of a group the plans are linked to.
product_id
int ID of a product the plans are linked to.

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'
            ),
        '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"
        },
        "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"
        },
        "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
int Game ID.
name
string Product name.
group_id
string Group ID.

Request

<?php

$response = $xsollaClient->CreateSubscriptionProduct(array(
    'project_id' => PROJECT_ID,
    'request' => array(
        'name' => 'Demo Product',
        'group_id' => '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"
}
$ 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"
    }'

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
int Game ID.
product_id
int Product ID.
name
string Product name.
group_id
string Group ID.

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
int Game ID.
product_id
int Product ID.

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

List 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
int Game ID.
group_id
string ID of a group the products are linked to.
product_id
int Product id.
limit
int Maximum number of records to retrieve.
offset
int Offset of the first record to retrieve.

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

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
int Game ID.
subscription_id
int 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 (object).
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.

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

List Subscriptions

Lists all recurrent subscriptions.

HTTP REQUEST

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

Parameter Type Description
project_id
int Game ID. Required.
user_id
string User ID in the game. Required.
status
string Status: active / canceled / non_renewing / new.
limit
int Maximum number of records to retrieve.
offset
int Offset of the first record to retrieve.
datetime_from
datetime Period start.
datetime_to
datetime Period end.
plan_id
string Plan ID.
product_id
string Product ID.

Request


<?php

$response = $xsollaClient->ListSubscriptions(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID
));
GET /merchant/v2/projects/{project_id}/users/{user_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}/users/{user_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 (
        '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,
                                'canceled' => 0,
                                'expired' => 0
                            )
                    )
            ),
        'user' =>
            array (
                'id' => '20'
            ),
        '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' => null,
        'status' => 'active'
    )
);
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": "disabled",
                "counters": {
                    "active": 0,
                    "canceled": 0,
                    "expired": 0
                }
            }
        },
        "user": {
            "id": "20"
        },
        "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": null,
        "status": "active"
    }
]
[
    {
        "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,
                    "canceled": 0,
                    "expired": 0
                }
            }
        },
        "user": {
            "id": "20"
        },
        "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": null,
        "status": "active"
    }
]

List Payments

Lists all subscription payments.

HTTP REQUEST

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

Parameter Type Description
project_id
int Game ID.
user_id
string User ID in the game.
status
string Status: processing / canceled / done.
limit
int Maximum number of records to retrieve.
offset
int Offset of the first record to retrieve.
datetime_from
datetime Period start.
datetime_to
datetime Period end.
subscription_id
int Subscription ID.

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

List Payments of a User

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
int Game ID.
user_id
string User ID in the game.
status
string Status: processing / canceled / done.
limit
int Maximum number of records to retrieve.
offset
int Offset of the first record to retrieve.
datetime_from
datetime Period start.
datetime_to
datetime Period end.
subscription_id
int Subscription ID.

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

List 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
int Game ID.

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

List User Attributes

Lists all user attributes.

HTTP REQUEST

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

Parameter Type Description
project_id
int Game ID.

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

Get User 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
int Game ID.
user_attribute_id
int User attribute ID.

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
}

Create User Attribute

Creates a user attribute.

HTTP REQUEST

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

Parameter Type Description
project_id
int Game 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.

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
}

Update User 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
int Game ID.
user_attribute_id
int User attribute ID.
key
string User attribute key. Not updated.
name
array of strings Localized user attribute names (array).
type
string Key type. Can be 'int', 'string', 'enum', or 'date'. Not updated.
list_of_values
array Array of possible values for enum type.
skip_condition_on_nonexistent_key
boolean Whether to skip the condition if key doesn't exist.

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 User 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
int Game ID.
user_attribute_id
int User attribute ID.

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

Create Virtual 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
int Game ID.
sku
string Unique ID of the item. The SKU may only contain lowercase Latin characters, digits, 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 long descriptions of the item (array).
prices
array Item prices (array).
default_currency
string Default purchase currency. Three-letter currency code per ISO 4217.
enabled
boolean Whether the product can be purchased.
permanent
boolean If true, the item can only be bought once.
image_url
string Image URL.
item_type
string Type of Item: Consumable / Expiration / Permanent / Lootboxes / Physical
expiration
int Expiration time in seconds. Used only for "Expiration" Item Type.
groups
array of integers Groups that the item belongs to (array).
deleted
boolean Whether the item has been deleted.
user_attribute_conditions
array of objects List of conditions on the user attribute.
user_attribute_conditions.right_operand
array Values to compare with the user attribute.
user_attribute_conditions.user_attribute_key
string Key of the user attribute condition.
user_attribute_conditions.operation
string Type of comparison operation. Can be 'greater', 'greaterOrEqual', 'equal', 'notEqual', 'less', 'lessOrEqual', 'between', 'in', 'notIn'.
user_attribute_conditions.action
string Type of action. Can be 'hide', 'block', or 'warning'.
advertisement_type
string A special label to show in the payment UI. Can be 'recommended', 'best_deal', 'special_offer', or null.
virtual_currency_price
int Price of this item in virtual currency. 'Null' if item can be purchased only for real currency.
purchase_limit
int Number of times you can buy this item. 'Null' if no limits.
keywords
array Keywords that can be used to find the item in the payment UI.

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 Virtual 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
int Item ID.

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 Virtual 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
int Item ID.
sku
string Unique ID of the item. The SKU may only contain lowercase Latin characters, digits, 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 long descriptions of the item (array).
prices
array Item prices (array).
default_currency
string Default purchase currency. Three-letter currency code per ISO 4217.
enabled
boolean Whether the product can be purchased.
permanent
boolean If true, the item can only be bought once.
image_url
string Image URL.
item_type
string Type of Item: Consumable / Expiration / Permanent / Lootboxes / Physical
expiration
int Expiration time in seconds. Used only for "Expiration" Item Type.
groups
array of integers Groups that the item belongs to (array).
deleted
boolean Whether the item has been deleted.
user_attribute_conditions
array of objects List of conditions on the user attribute.
user_attribute_conditions.right_operand
array Values to compare with the user attribute.
user_attribute_conditions.user_attribute_key
string Key of the user attribute condition.
user_attribute_conditions.operation
string Type of comparison operation. Can be 'greater', 'greaterOrEqual', 'equal', 'notEqual', 'less', 'lessOrEqual', 'between', 'in', 'notIn'.
user_attribute_conditions.action
string Type of action. Can be 'hide', 'block', or 'warning'.
advertisement_type
string A special label to show in the payment UI. Can be 'recommended', 'best_deal', 'special_offer', or null.
virtual_currency_price
int Price of this item in virtual currency. 'Null' if item can be purchased only for real currency.
purchase_limit
int Number of times you can buy this item. 'Null' if no limits.
keywords
array Keywords that can be used to find the item in the payment UI.

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 Virtual 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
int ID item.

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

List Virtual Items

Lists all virtual items.

HTTP REQUEST

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

Parameter Type Description
project_id
int Game ID.
offset
int Offset of the first record to retrieve.
limit
int Maximum number of records to retrieve.
has_price
string Price type: 'virtual_currency' or 'real_currency' if the item can be purchased for virtual or real currency, respectively.

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 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
int Game ID.
name
array of strings Localized group names (array).
description
array of strings Localized group descriptions (array).
enabled
boolean Enables the group.
parent_id
int Parent group ID.
code
int Group's unique code.

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 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
int Group ID.

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 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
int 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
int Parent group ID.
code
int Group's unique code.

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 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
int Group ID.

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

List Groups

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
int Game ID.

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

Lootboxes (BETA)

Create Lootbox

Creates a lootbox.

HTTP REQUEST

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

Parameter Type Description
project_id
int Game ID.
sku
string Item's unique ID. The SKU may only contain lowercase Latin alphanumeric characters, dashes, and underscores.
item_code
string Item's additional code. Optional.
name
array of strings Localized item names.
description
array of strings Localized item descriptions.
long_description
array of strings Localized long descriptions of the item.
prices
array Item prices.
default_currency
string Default order currency. Three-digit code per ISO 4217.
enabled
boolean Enables the item.
permanent
boolean If true, the item can only be purchased once.
image_url
string Item image URL.
item_type
string Item type: 'lootbox'
expiration
int Lifetime in seconds. For Expiration-type items only
groups
array of integers Groups the item belongs to.
deleted
boolean Whether the item was deleted.
user_attribute_conditions
array of objects Conditions for user attributes.
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
int Price in the in-game currency. If 'null', the item can only be purchased for real currency.
purchase_limit
int 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.
key_virtual_item_id
int ID of a virtual item that opens the lootbox.
opening_price_vc
int Price to open the lootbox in the virtual currency.
slots
array Lootbox slots. An array specifying the set of items that can be dropped in each slot.
slots.id
int Slot ID.
slots.value
object Slot contents. The sum of drop_rate for each slot must be 100%.
slots.value.virtual_item
array Virtual items that can be dropped in the slot.
slots.value.virtual_item.id
int Item ID.
slots.value.virtual_item.amount
float Item quantity.
slots.value.virtual_item.drop_rate
decimal Probability of the item’s being dropped in the slot (accurate to 2 decimal places).
slots.value.virtual_currency
object Virtual currencies that can be dropped in the slot.
slots.value.virtual_currency.amount
float Currency quantity.
slots.value.virtual_currency.drop_rate
decimal Probability of the item’s being dropped in the slot (accurate to 2 decimal places).
slots.value.attribute
array Attributes for items that can be dropped in the slot.
slots.value.attribute.type
int Attribute type to be used to select what item to drop to a lootbox.
slots.value.attribute.value
string Attribute value. E.g., "rare".
slots.value.attribute.drop_rate
string Probability of an item with that attribute to be dropped in the slot (accurate to 2 decimal places).
slots.compensation_for_duplicate_percent
int Compensation for a duplicate item in virtual currency (percentage of item price).
slots.compensation_for_duplicate_value
float Compensation for a duplicate item in virtual currency (absolute value).
limits
object Constraints on the quantity of items in the lootbox.
limits.virtual_item
object Constraints for virtual items.
limits.virtual_item.id
int Item ID.
limits.virtual_item.max_items
int Maximum number of times the item can be dropped in the lootbox.
limits.attribute
object Constraints for attributes.
limits.attribute.type
int Attribute type to be used for the constraint.
limits.attribute.value
string Attribute value. to be used for the constraint.
limits.attribute.max_items
int Maximum number of times an item with that attribute can be dropped in the lootbox.

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' => 'lootbox',
'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": "lootbox",
"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,
"slots":[
{
"id":123,
"value":{
"virtual_items":[
{
"id":123,
"amount":10,
"drop_rate":20
},
{
"id":321,
"amount":15,
"drop_rate":50
}
],
"attribute":[
{
"type":1,
"value":"rare",
"drop_rate":20
}
],
"virtual_currency":[
{
"amount":100,
"drop_rate":10
}
]
},
"compensation_for_duplicate_percent":10,
"compensation_for_duplicate_value":50
}
],
"limits":{
"virtual_item":{
"id":123,
"max_items":5
},
"attribute":{
"type":1,
"value":"rare",
"max_items":5
}
}
}
$ 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": "lootbox",
"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,
"slots":[
{
"id":123,
"value":{
"virtual_items":[
{
"id":123,
"amount":10,
"drop_rate":20
},
{
"id":321,
"amount":15,
"drop_rate":50
}
],
"attribute":[
{
"type":1,
"value":"rare",
"drop_rate":20
}
],
"virtual_currency":[
{
"amount":100,
"drop_rate":10
}
]
},
"compensation_for_duplicate_percent":10,
"compensation_for_duplicate_value":50
}
],
"limits":{
"virtual_item":{
"id":123,
"max_items":5
},
"attribute":{
"type":1,
"value":"rare",
"max_items":5
}
}
}'

Response

<?php

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

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

Update Lootbox

Updates a lootbox.

HTTP REQUEST

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

Parameter Type Description
project_id
int Game ID.
sku
string Item's unique ID. The SKU may only contain lowercase Latin alphanumeric characters, dashes, and underscores.
item_code
string Item's additional code. Optional.
name
array of strings Localized item names.
description
array of strings Localized item descriptions.
long_description
array of strings Localized long descriptions of the item.
prices
array Item prices.
default_currency
string Default order currency. Three-digit code per ISO 4217.
enabled
boolean Enables the item.
permanent
boolean If true, the item can only be purchased once.
image_url
string Item image URL.
item_type
string Item type: 'lootbox'
expiration
int Lifetime in seconds. For Expiration-type items only
groups
array of integers Groups the item belongs to.
deleted
boolean Whether the item was deleted.
user_attribute_conditions
array of objects Conditions for user attributes.
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
int Price in the in-game currency. If 'null', the item can only be purchased for real currency.
purchase_limit
int 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.
key_virtual_item_id
int ID of a virtual item that opens the lootbox.
opening_price_vc
int Price to open the lootbox in the virtual currency.
slots
array Lootbox slots. An array specifying the set of items that can be dropped in each slot.
slots.id
int Slot ID.
slots.value
object Slot contents. The sum of drop_rate for each slot must be 100%.
slots.value.virtual_item
array Virtual items that can be dropped in the slot.
slots.value.virtual_item.id
int Item ID.
slots.value.virtual_item.amount
float Item quantity.
slots.value.virtual_item.drop_rate
decimal Probability of the item’s being dropped in the slot (accurate to 2 decimal places).
slots.value.virtual_currency
object Virtual currencies that can be dropped in the slot.
slots.value.virtual_currency.amount
float Currency quantity.
slots.value.virtual_currency.drop_rate
decimal Probability of the item’s being dropped in the slot (accurate to 2 decimal places).
slots.value.attribute
array Attributes for items that can be dropped in the slot.
slots.value.attribute.type
int Attribute type to be used to select what item to drop to a lootbox.
slots.value.attribute.value
string Attribute value. E.g., "rare".
slots.value.attribute.drop_rate
string Probability of an item with that attribute to be dropped in the slot (accurate to 2 decimal places).
slots.compensation_for_duplicate_percent
int Compensation for a duplicate item in virtual currency (percentage of item price).
slots.compensation_for_duplicate_value
float Compensation for a duplicate item in virtual currency (absolute value).
limits
object Constraints on the quantity of items in the lootbox.
limits.virtual_item
object Constraints for virtual items.
limits.virtual_item.id
int Item ID.
limits.virtual_item.max_items
int Maximum number of times the item can be dropped in the lootbox.
limits.attribute
object Constraints for attributes.
limits.attribute.type
int Attribute type to be used for the constraint.
limits.attribute.value
string Attribute value. to be used for the constraint.
limits.attribute.max_items
int Maximum number of times an item with that attribute can be dropped in the lootbox.

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' => 'lootbox',
'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": "lootbox",
"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": "lootbox",
"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

Get Lootbox

Retrieves information about a lootbox.

HTTP REQUEST

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

Parameter Type Description
item_id
int Item ID.

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' => 'lootbox',
'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": "lootbox",
"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": "lootbox",
"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
}

List Lootboxes

Gets a list of lootboxes.

HTTP REQUEST

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

Parameter Type Description
project_id
int Game ID.
offset
int Page number.
limit
int Records per page.
has_price
string Kind of currency that can be used to purchase the item. Can be 'virtual_currency' or 'real_currency' for items that can be purchased for virtual or real currency, respectively.

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

Open Lootbox

HTTP REQUEST

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

Parameter Type Description
slots
array Lootbox slots. An array specifying the set of items that can be dropped in each slot.
slots.id
int Slot ID.
slots.value
object Slot contents. The sum of drop_rate for each slot must be 100%.
slots.value.virtual_item
array Virtual items that can be dropped in the slot.
slots.value.virtual_item.id
int Item ID.
slots.value.virtual_item.amount
float Item quantity.
slots.value.virtual_item.drop_rate
decimal Probability of the item’s being dropped in the slot (accurate to 2 decimal places).
slots.value.virtual_currency
object Virtual currencies that can be dropped in the slot.
slots.value.virtual_currency.amount
float Currency quantity.
slots.value.virtual_currency.drop_rate
decimal Probability of the item’s being dropped in the slot (accurate to 2 decimal places).
slots.value.attribute
array Attributes for items that can be dropped in the slot.
slots.value.attribute.type
int Attribute type to be used to select what item to drop to a lootbox.
slots.value.attribute.value
string Attribute value. E.g., "rare".
slots.value.attribute.drop_rate
string Probability of an item with that attribute to be dropped in the slot (accurate to 2 decimal places).
slots.compensation_for_duplicate_percent
int Compensation for a duplicate item in virtual currency (percentage of item price).
slots.compensation_for_duplicate_value
float Compensation for a duplicate item in virtual currency (absolute value).

Request

<?php

$response = $xsollaClient->GetVirtualItem(array(
'project_id' => PROJECT_ID,
'item_id' => ITEM_ID
));
POST /merchant/v2/projects/{project_id}/virtual_items/items/{item_id}/open 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}/open' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \

Response

<?php
HTTP/1.1 200 OK

Delete Lootbox

Deletes a lootbox.

HTTP REQUEST

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

Parameter Type Description
item_id
int Item ID.

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

List Virtual Currency 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
int Game ID.

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 Virtual Currency 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
int Game 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 file 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.

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

Wallet

This section describes methods applicable to game user balances, such as check balance, recharge, withdraw funds, and other user-related operations.

Create User

Creates a new user.

HTTP REQUEST

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

Parameter Type Description
project_id
int Game ID. Required.
user_id
string User ID. Required.
user_name
string User name.
user_custom
string Custom parameter for user identification.
email
string Email.

Request

<?php

$response = $xsollaClient->CreateWalletUser(array(
    'project_id' => PROJECT_ID,
    'request' => array(
        'user_id' => USER_ID
    )
));
POST /merchant/v2/projects/{project_id}/users 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}/users' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "user_id": 1
}'

Response

<?php

$response = null;
HTTP/1.1 204 No Content

Get User

Retrieves user details.

HTTP REQUEST

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

Parameter Type Description
project_id
int Game ID.
user_id
string User’s ID in the game.

Request

<?php

$response = $xsollaClient->GetWalletUser(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID
));
GET /merchant/v2/projects/{project_id}/users/{user_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}/users/{user_id}' \
-X GET \
-u merchant_id:merchant_api_key

Response

<?php

// example response
$response = array (
    'user_id' => 0,
    'user_name' => 'John',
    'user_custom' => 'Smith',
    'email' => 'email@example.com',
    'register_date' => '2014-10-08T21:44:32+04:00',
    'balance' => 100,
    'wallet_amount' => 1.5,
    'wallet_currency' => 'USD',
    'enabled' => true
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "user_id": 0,
    "user_name": "John",
    "user_custom": "Smith",
    "email": "email@example.com",
    "register_date": "2014-10-08T21:44:32-08:00",
    "balance": 100,
    "wallet_amount": 1.5,
    "wallet_currency": "USD",
    "enabled": true
}
{
    "user_id": 0,
    "user_name": "John",
    "user_custom": "Smith",
    "email": "email@example.com",
    "register_date": "2014-10-08T21:44:32-08:00",
    "balance": 100,
    "wallet_amount": 1.5,
    "wallet_currency": "USD",
    "enabled": true
}

Update User

Updates user details.

HTTP REQUEST

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

Parameter Type Description
project_id
int Game ID. Required.
user_id
string User ID in the game. Required.
user_name
string User name.
user_custom
string Custom parameter for user identification.
email
string Email.
enabled
boolean Whether the user is enabled. Required.

Request

<?php

$response = $xsollaClient->UpdateWalletUser(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID,
    'request' => array(
        'enabled' => true
    )
));
PUT /merchant/v2/projects/{project_id}/users/{user_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

{
    "enabled": true
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}' \
-X PUT \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "enabled": true
}'

Response

<?php

$response = null;
HTTP/1.1 204 No Content

List Users

Lists all users.

HTTP REQUEST

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

Parameter Type Description
project_id
int Game ID. Required.
user_requisites
string User ID or name.
email
string User email.
offset
int Offset of the first record to retrieve. Required.
limit
int Maximum number of records to retrieve. Required.

Request

<?php

$response = $xsollaClient->ListWalletUsers(array(
    'project_id' => PROJECT_ID,
    'limit' => 1,
    'offset' => 0
));
GET /merchant/v2/projects/{project_id}/users?offset=1&limit=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}/users?offset=1&limit=1' \
-X GET \
-u merchant_id:merchant_api_key

Response

<?php

// example response
$response = array (
    'recordsTotal' => 1,
    'data' =>
        array (
            array (
                'user_id' => 0,
                'user_name' => 'John',
                'user_custom' => 'Smith',
                'email' => 'email@example.com',
                'register_date' => '2014-10-08T21:44:32-08:00',
                'balance' => 100,
                'wallet_amount' => 1.5,
                'wallet_currency' => 'USD',
                'enabled' => true
            )
        )
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "recordsTotal": 1,
    "data": [
        {
            "user_id": 0,
            "user_name": "John",
            "user_custom": "Smith",
            "email": "email@example.com",
            "register_date": "2014-10-08T21:44:32-08:00",
            "balance": 100,
            "wallet_amount": 1.5,
            "wallet_currency": "USD",
            "enabled": true
        }
    ]
}
{
    "recordsTotal": 1,
    "data": [
        {
            "user_id": 0,
            "user_name": "John",
            "user_custom": "Smith",
            "email": "email@example.com",
            "register_date": "2014-10-08T21:44:32-08:00",
            "balance": 100,
            "wallet_amount": 1.5,
            "wallet_currency": "USD",
            "enabled": true
        }
    ]
}

List Transactions

Lists all transactions of a user.

HTTP REQUEST

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

Parameter Type Description
project_id
int Game ID. Required.
user_id
string User ID in the game. Required.
datetime_from
datetime Period start. Required.
datetime_to
datetime Period end. Required.
transaction_type
string Type of transaction, can be "payment", "coupon", "inGamePurchase", "internal", or "cancellation".

Request

<?php

$response = $xsollaClient->ListWalletUserOperations(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID,
    'datetime_from' => '2015-01-01T00:00:00Z',
    'datetime_to' => '2016-01-01T00:00:00Z'
));
GET /merchant/v2/projects/{project_id}/users/{user_id}/transactions?datetime_from=2014-10-14T00%3A00%3A00Z&datetime_to=2014-10-15T00%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}/transactions?datetime_from=2014-10-14T00%3A00%3A00Z&datetime_to=2014-10-15T00%3A00%3A00Z' \
-X GET \
-u merchant_id:merchant_api_key

Response

<?php

// example response
$response = array (
    array (
        'operation_id' => 647287,
        'transaction_id' => 1234567,
        'coupon_id' => null,
        'coupon_code' => null,
        'transaction_type' => 'invoice',
        'comment' => 'Incoming payment',
        'date' => '2014-10-28T12:00:00+04:00',
        'amount' => 1000,
        'sum' => 10,
        'currency' => 'USD',
        'status' => 'notified',
        'user_balance' => 100,
        'user_id' => '1234567'
    ),
    array (
        'operation_id' => 647288,
        'transaction_id' => null,
        'coupon_id' => null,
        'coupon_code' => 'DemoCoupon',
        'transaction_type' => 'coupon',
        'comment' => 'Coupon Redeem',
        'date' => '2014-10-28T14:00:00+04:00',
        'amount' => 0,
        'sum' => null,
        'currency' => null,
        'status' => 'failed',
        'user_balance' => 100,
        'user_id' => '1234567'
    )
);
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "operation_id": 647287,
        "transaction_id": 1234567,
        "coupon_id": null,
        "coupon_code": null,
        "transaction_type": "invoice",
        "comment": "Incoming payment",
        "date": "2014-10-28T12:00:00+04:00",
        "amount": 1000,
        "sum": 10,
        "currency": "USD",
        "status": "notified",
        "user_balance": 100,
        "user_id": "1234567"
    },
    {
        "operation_id": 647288,
        "transaction_id": null,
        "coupon_id": 12345,
        "coupon_code": "DemoCoupon",
        "transaction_type": "coupon",
        "comment": "Coupon Redeem",
        "date": "2014-10-28T14:00:00+04:00",
        "amount": 0,
        "sum": null,
        "currency": null,
        "status": "failed",
        "user_balance": 100,
        "user_id": "1234567"
    }
]
[
    {
        "operation_id": 647287,
        "transaction_id": 1234567,
        "coupon_id": null,
        "coupon_code": null,
        "transaction_type": "invoice",
        "comment": "Incoming payment",
        "date": "2014-10-28T12:00:00+04:00",
        "amount": 1000,
        "sum": 10,
        "currency": "USD",
        "status": "notified",
        "user_balance": 100,
        "user_id": "1234567"
    },
    {
        "operation_id": 647288,
        "transaction_id": null,
        "coupon_id": 12345,
        "coupon_code": "DemoCoupon",
        "transaction_type": "coupon",
        "comment": "Coupon Redeem",
        "date": "2014-10-28T14:00:00+04:00",
        "amount": 0,
        "sum": null,
        "currency": null,
        "status": "failed",
        "user_balance": 100,
        "user_id": "1234567"
    }
]

Update Balance

Updates the balance of a user.

HTTP REQUEST

POST https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/recharge

Parameter Type Description
project_id
int Game ID.
user_id
string User’s ID in the game.
int
float Virtual currency quantity.
comment
string Reason for changing the balance.

Request

<?php

$response = $xsollaClient->RechargeWalletUserBalance(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID,
    'request' => array(
        'amount' => 10,
        'comment' => 'Incoming payment'
    )
));
POST /merchant/v2/projects/{project_id}/users/{user_id}/recharge HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "amount": 10,
    "comment": "Incoming payment"
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/recharge' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "amount": 10,
    "comment": "Incoming payment"
}'

Response

<?php

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

{
    "amount": 110
}
{
    "amount": 110
}

List Virtual Items of a User

Retrieves a list of virtual items owned by a user.

HTTP REQUEST

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

Parameter Type Description
project_id
int Game ID.
user_id
string User’s ID in the game.
offset
int Offset of the first record to retrieve.
limit
int Maximum number of records to retrieve.

Request

<?php

$response = $xsollaClient->ListWalletUserVirtualItems(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID,
    'limit' => 1,
    'offset' => 0
));
GET /merchant/v2/projects/{project_id}/users/{user_id}/virtual_items?offset=1&limit=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}/users/{user_id}/virtual_items?offset=1&limit=1' \
-X GET \
-u merchant_id:merchant_api_key

Response

<?php

// example response
$response = array (
    array (
        'id' => 1,
        'sku' => 'item1',
        'quantity' => 10
    ),
    array (
        'id' => 2,
        'sku' => 'item2',
        'quantity' => 5
    ),
);
HTTP/1.1 200 OK
Content-Type: application/json

[
         {
            "id": 1,
            "sku": "item1",
            "quantity": 10
         },
         {
            "id": 2,
            "sku": "item2",
            "quantity": 5
         }
]
[
         {
            "id": 1,
            "sku": "item1",
            "quantity": 10
         },
         {
            "id": 2,
            "sku": "item2",
            "quantity": 5
         }
]

List Virtual Items of All Users

Get virtual items of all the project's users.

HTTP REQUEST

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

Parameter Type Description
project_id
int Game ID.
user_id
string User’s ID in the game.
offset
int Offset of the first record to retrieve.
limit
int Maximum number of records to retrieve.

Request

<?php

$response = $xsollaClient->ListWalletUserVirtualItems(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID,
    'limit' => 1,
    'offset' => 0
));
GET /merchant/v2/projects/{project_id}/users/{user_id}/virtual_items?offset=1&limit=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}/users/{user_id}/virtual_items?offset=1&limit=1' \
-X GET \
-u merchant_id:merchant_api_key

Response

<?php

// example response
$response = array (
  array (
      'user_id' => 'V1',
      'virtual_items' =>
          array (
              'id' => 1,
              'sku' => 'item1',
              'quantity' => '10'
            ),
            array (
                'id' => 2,
                'sku' => 'item2',
                'quantity' => '5'
              ),
        ),   
  array (
      'user_id' => 'V2',
      'virtual_items' =>
          array (
              'id' => 1,
              'sku' => 'item1',
              'quantity' => '9'
              ),
        ),            
);
HTTP/1.1 200 OK
Content-Type: application/json

[
{
   "user_id": "V1",
   "virtual_items": [
      {
         "id": 1,
         "sku": "item1",
         "quantity": 10
      },
      {
         "id": 2,
         "sku": "item2",
         "quantity": 5
      }
   ]
},
{
   "user_id": "V2",
   "virtual_items": [
      {
         "id": 1,
         "sku": "item1",
         "quantity": 9
      }
   ]      
}
]
[
{
   "user_id": "V1",
   "virtual_items": [
      {
         "id": 1,
         "sku": "item1",
         "quantity": 10
      },
      {
         "id": 2,
         "sku": "item2",
         "quantity": 5
      }
   ]
},
{
   "user_id": "V2",
   "virtual_items": [
      {
         "id": 1,
         "sku": "item1",
         "quantity": 9
      }
   ]
}
]

Give Virtual Items to a User

Adds virtual items to a user's account.

HTTP REQUEST

POST https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/virtual_items/add

Parameter Type Description
project_id
int Game ID.
user_id
string User’s ID in the game.
virtual_items
array Virtual items (array).
virtual_items.virtual_item
object Virtual item details (object).
virtual_items.virtual_item.sku
string Unique item ID.
virtual_items.amount
int Item quantity.

Request

<?php

$response = $xsollaClient->AddVirtualItemToWalletUser(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID,
    'request' => array(
        'virtual_items' => array(
            array(
                'virtual_item' => array(
                    'sku' => 'ar23_shop_expiration_3'
                ),
                'amount' => 2
            )
        )
    )
));
POST /merchant/v2/projects/{project_id}/users/{user_id}/virtual_items/add HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "virtual_items": [
        {
            "virtual_item":
                {
                    "sku" : "ar23_shop_expiration_3"
                },
            "amount": 2
        }
    ]
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/virtual_items/add' \
-X POST \
-u merchant_id:merchant_api_key
-d '{
        "virtual_items": [
            {
                "virtual_item":
                    {
                        "sku" : "ar23_shop_expiration_3"
                    },
                "amount": 2
            }
        ]
    }'

Response

<?php

$response = null;
HTTP/1.1 204 No Content

Remove Items from a User

Removes virtual items from a user's account.

HTTP REQUEST

POST https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/virtual_items/remove

Parameter Type Description
project_id
int Game ID.
user_id
string User’s ID in the game.
virtual_items
array Virtual items (array).
virtual_items.virtual_item
object Virtual item details (object).
virtual_items.virtual_item.sku
string Unique item ID.
virtual_items.amount
int Item quantity.

Request

<?php

$response = $xsollaClient->DeleteVirtualItemFromWalletUser(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID,
    'request' => array(
        'virtual_items' => array(
            array(
                'virtual_item' => array(
                    'sku' => 'ar23_shop_expiration_3'
                ),
                'amount' => 2,
            )
        )
    )
));
POST /merchant/v2/projects/{project_id}/users/{user_id}/virtual_items/remove HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "virtual_items": [
        {
            "virtual_item":
                {
                    "sku" : "ar23_shop_expiration_3"
                },
            "amount": 2
        }
    ]
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/virtual_items/remove' \
-X POST \
-u merchant_id:merchant_api_key
-d '{
        "virtual_items": [
            {
                "virtual_item":
                    {
                        "sku" : "ar23_shop_expiration_3"
                    },
                "amount": 2
            }
        ]
    }'

Response

<?php

$response = null;
HTTP/1.1 204 No Content

Create Game Delivery 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
int Project ID.
sku
string Unique ID of the game delivery entity. The SKU may only contain lowercase Latin characters, digits, 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.
video_link string Link to a video featuring the game. Optional.
genre
string Game genre. Optional.
additional_info
string Additional info about the game. Optional.
forum_link string Link to a discussion forum. Optional.
support_link string Link to a support page. Optional.
old_price
string Old price of the game. Optional.
parent_id
int ID of a parent game. Optional.
default_currency
string Default purchase currency. Three-letter currency code per ISO 4217.
release_date
string Expected date of release. Optional.
drm
array Array with DRM data.
drm.id
int ID of an available DRM.
drm.prices
array Array of game prices for DRM. Optional.
drm.platforms
array Array with data about DRM platforms.
drm.platforms.id
int Platform ID for that DRM.
drm.enabled
boolean Whether DRM is in use for this game.
obtain_code_from_db
boolean Whether to use PIN codes from Xsolla database. Optional.
obtain_code_from_api
boolean Whether to use PIN codes received via API. Optional.

Request

<?php

$response = $xsollaClient->CreateGameDeliveryEntity(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',
         'drm' =>
             array (
                 array (
                     'id' => 1,
                     'platforms' =>
                         array (
                             array (
                                 'id' => 1,
                             ),
                             array (
                                 'id' => 2,
                             ),
                         ),
                     'prices' =>
                         array (
                             'USD' => 19.99,
                             'EUR' => 18.5,
                         ),
                     'enabled' => true
                 ),
             ),
         'obtain_code_from_api' => false,
         'obtain_code_from_db' => 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",
    "release_date":"2016-01-01T00:00:00+00:00",
    "drm":[
        {
            "id":1,
            "platforms":[
                {
                    "id":1
                },
                {
                    "id":2
                }
            ],
            "prices":{
                "USD":19.99,
                "EUR":18.5
            },
            "enabled":true
        }
    ],
    "obtain_code_from_api":false,
    "obtain_code_from_db":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",
    "release_date":"2016-01-01T00:00:00+00:00",
    "drm":[
        {
            "id":1,
            "platforms":[
                {
                    "id":1
                },
                {
                    "id":2
                }
            ],
            "prices":{
                "USD":19.99,
                "EUR":18.5
            },
            "enabled":true
        }
    ],
    "obtain_code_from_api":false,
    "obtain_code_from_db":false
}'

Response

<?php

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

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

Get Game Delivery 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
int Project ID.
game_delivery_id
int ID of the game delivery entity.

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 (
        'id' => 9,
        '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',
        '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' => 0,
                            'active' => 0,
                            'used' => 0,
                        ),
                ),
            ),
        'obtain_code_from_api' => false,
        'obtain_code_from_db' => 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",
    "release_date": "2016-01-01T00:00:00+00:00",
    "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": 0,
                "active": 0,
                "used": 0
            }
        },
        {
            "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": 0,
                "active": 0,
                "used": 0
            }
        }
    ],
    "obtain_code_from_api": false,
    "obtain_code_from_db": 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",
    "release_date": "2016-01-01T00:00:00+00:00",
    "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": 0,
                "active": 0,
                "used": 0
            }
        },
        {
            "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": 0,
                "active": 0,
                "used": 0
            }
        }
    ],
    "obtain_code_from_api": false,
    "obtain_code_from_db": false
}

Update Game Delivery 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
int Project ID.
game_delivery_id
int ID of the game delivery entity.
sku
string Unique ID of the game delivery entity. The SKU may only contain lowercase Latin characters, digits, 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.
video_link string Link to a video featuring the game. Optional.
genre
string Game genre. Optional.
additional_info
string Additional info about the game. Optional.
forum_link string Link to a discussion forum. Optional.
support_link string Link to a support page. Optional.
old_price
string Old price of the game. Optional.
parent_id
int ID of a parent game. Optional.
default_currency
string Default purchase currency. Three-letter currency code per ISO 4217.
release_date
string Expected date of release. Optional.
drm
array Array with DRM data.
drm.id
int ID of an available DRM.
drm.prices
array Array of game prices for DRM. Optional.
drm.platforms
array Array with data about DRM platforms.
drm.platforms.id
int Platform ID for that DRM.
drm.enabled
boolean Whether DRM is in use for this game.
obtain_code_from_db
boolean Whether to use PIN codes from Xsolla database. Optional.
obtain_code_from_api
boolean Whether to use PIN codes received via API. Optional.

Request

<?php

$response = $xsollaClient->UpdateGameDeliveryEntity(array(
    'project_id' => PROJECT_ID,
    'game_delivery_id' => GAME_DELIVERY_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',
         'drm' =>
             array (
                 array (
                     'id' => 1,
                     'platforms' =>
                         array (
                             array (
                                 'id' => 1,
                             ),
                             array (
                                 'id' => 2,
                             ),
                         ),
                     'prices' =>
                         array (
                             'USD' => 19.99,
                             'EUR' => 18.5,
                         ),
                     'enabled' => true
                 ),
             ),
         'obtain_code_from_api' => false,
         'obtain_code_from_db' => 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",
    "release_date":"2016-01-01T00:00:00+00:00",
    "drm":[
        {
            "id":1,
            "platforms":[
                {
                    "id":1
                },
                {
                    "id":2
                }
            ],
            "prices":{
                "USD":19.99,
                "EUR":18.5
            },
            "enabled":true
        }
    ],
    "obtain_code_from_api":false,
    "obtain_code_from_db":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",
    "release_date":"2016-01-01T00:00:00+00:00",
    "drm":[
        {
            "id":1,
            "platforms":[
                {
                    "id":1
                },
                {
                    "id":2
                }
            ],
            "prices":{
                "USD":19.99,
                "EUR":18.5
            },
            "enabled":true
        }
    ],
    "obtain_code_from_api":false,
    "obtain_code_from_db":false
}'

Response

<?php

$response = null;
HTTP/1.1 204 No Content

List Game Delivery Entities

Lists all game delivery entities.

HTTP REQUEST

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

Parameter Type Description
project_id
int Project ID.

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

List DRMs

Lists available DRM platforms.

HTTP REQUEST

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

Parameter Type Description
merchant_id
int Merchant ID.

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

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
int Game ID.
code
string Coupon code.

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 a 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
int Game ID.
code
string Coupon code.
user_id
string User’s ID in the game.

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 Promotion

Create a new promotion.

HTTP REQUEST

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

Parameter Type Description
merchant_id
int 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
int ID of the game that the promotion applies to.

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
int Merchant ID.
promotion_id
int Promotion ID.

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
int Merchant ID.
promotion_id
int 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
int ID of the game that the promotion applies to.

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
int Merchant ID.
promotion_id
int Promotion ID.

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
int Merchant ID.
promotion_id
int Promotion ID.

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
int Merchant ID.
promotion_id
int Promotion ID.

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

List Promotions

List all promotions.

HTTP REQUEST

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

Parameter Type Description
merchant_id
int Merchant ID.

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

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
int Merchant ID.
promotion_id
int Promotion ID.

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 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
int Merchant ID.
promotion_id
int Promotion ID.
purchase
boolean Whether the promotion applies to the whole purchase.
items
array of virtual items SKU (object) or null Array of virtual items that the promotion applies to.
items.sku
string Item SKU.
packages
array of the virtual currency amounts (float) or null Array of virtual currency packages that the promotion applies to.
subscriptions
object/null 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
int Maximum number of billings that the promotion applies to.

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

List 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
int Merchant ID.
promotion_id
int Promotion ID.

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 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
int Merchant ID.
promotion_id
int Promotion ID.
payment_systems
array Payment systems (array).
int
int Payment system ID.

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

List 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
int Merchant ID.
promotion_id
int Promotion ID.

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

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
int Merchant ID.
promotion_id
int Promotion ID.
periods
array Date/time ranges (array).
from
datetime Period start.
to
datetime Period end.

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

List 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
int Merchant ID.
promotion_id
int Promotion ID.

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 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
int Merchant ID.
promotion_id
int 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
int 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
int Number of virtual items given as a bonus.
subscription
object Sets the reward for a subscription.
subscription.trial_days
int Trial period in days.

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

Fulfillment (BETA)

Create Fulfillment

HTTP REQUEST

POST https://api.xsolla.com/merchant/v2/merchants/project/{project_id}/order/{order_id}/fulfillments/create

Parameter Type Description
project_id
int Project ID.
order_id
int Order ID.
status
string Fulfillment status.
user_id
int User ID.
shopping_cart_id
int Shopping cart ID.
fulfillment_centers
object Available fulfillment centers (object).
fulfillment_centers.fulfillment_center_id
int Fulfillment center ID.
fulfillment_centers.fulfillment_center_name
string Fulfillment center name.
shipping_method
object Order shipping method (object).
shipping_method.shipping_method_id
int Shipping method ID.
shipping_method.shipping_method_name
string Name.
shipping_method.tracking_numbers
array Order tracking numbers.
shipping_method.tracking_numbers
array Order tracking URLs.
pricing
object Pricing details (object).
pricing.subtotal
object Subtotal (object).
pricing.subtotal.amount
string Amount.
pricing.subtotal.currency
string Currency.
pricing.shipping
object Shipping cost (object).
pricing.shipping.amount
string Amount.
pricing.shipping.currency
string Currency.
pricing.tax
object Tax (object).
pricing.tax.amount
string Amount.
pricing.tax.currency
string Currency.
pricing.ordertotal
object Order total (object).
pricing.ordertotal.amount
string Amount.
pricing.ordertotal.currency
string Currency.
pricing.discount
object Discount (object).
pricing.discount.amount
string Amount.
pricing.discount.currency
string Currency.

Request


POST merchant/v2/merchants/
project/{project_id}/order/{order_id}/fulfillments/create 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": "pending shipped",
  "user_id":123,
  "shopping_cart_id":123456,
  "fulfillment_centers":{
  "fulfillment_center_id": 1234,
  "fulfillment_center_name": "Fulfillment Name",
  "shipping method":{
    "shipping_method_id":1,
    "shipping_method_name":"Fedex",
    "tracking_numbers": [
      "123456789"
    ],
    "tracking_urls": [
      "http:\/\/test.amazon.com\/home\/track\/home_index?trackNums=123456789"
    ],
      }
    },
  "pricing":{
    "subtotal":{
      "amount":10.99,
      "currency":"USD"
      },
    "shipping":{
      "amount":0,
      "currency":"USD"
      },
    "tax":{
      "amount":0,
      "currency":"USD"
      },
    "ordertotal":{
      "amount":10.99,
      "currency":"USD"
      },
    "discount":{
      "amount":10.99,
      "currency":"USD"
      }
    }
  }
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/project/{project_id}/order/{order_id}/fulfillments/create' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "status": "pending shipped",
  "user_id":123,
  "shopping_cart_id":123456,
  "fulfillment_centers":{
  "fulfillment_center_id": 1234,
  "fulfillment_center_name": "Fulfillment Name",
  "shipping method":{
    "shipping_method_id":1,
    "shipping_method_name":"Fedex",
    "tracking_numbers": [
      "123456789"
    ],
    "tracking_urls": [
      "http:\/\/test.amazon.com\/home\/track\/home_index?trackNums=123456789"
    ],
      }
    },
  "pricing":{
    "subtotal":{
      "amount":10.99,
      "currency":"USD"
      },
    "shipping":{
      "amount":0,
      "currency":"USD"
      },
    "tax":{
      "amount":0,
      "currency":"USD"
      },
    "ordertotal":{
      "amount":10.99,
      "currency":"USD"
      },
    "discount":{
      "amount":10.99,
      "currency":"USD"
      }
    }
  }'

Response


HTTP/1.1 201 Created
Content-Type: application/json

{
  "fulfillment_id": 1
  }
{
  "fulfillment_id": 1
  }

Update Fulfillment

HTTP REQUEST

PUT https://api.xsolla.com/merchant/v2/merchants/project/{project_id}/order/{order_id}/fulfillments/{fulfillments_id}

Parameter Type Description
project_id
int Project ID.
order_id
int Order ID.
status
string Fulfillment status.
user_id
int User ID.
shopping_cart_id
int Shopping cart ID.
fulfillment_centers
object Available fulfillment centers (object).
fulfillment_centers.fulfillment_center_id