コンテンツへスキップ

カタログAPI (2.0.0)

Overview

  • Version: 2.0.0
  • Servers: https://store.xsolla.com/api
  • Contact Us by Email
  • Contact URL: https://xsolla.com/
  • Required TLS version: 1.2

The Catalog API allows you to configure a catalog of in-game items on the Xsolla side and display the catalog to users in your store.

The API allows you to manage the following catalog entities:

  • Virtual items — in-game items such as weapons, skins, boosters.
  • Virtual currency — virtual money used to purchase virtual goods.
  • Virtual currency packages — predefined bundles of virtual currency.
  • Bundles — combined packages of virtual items, currency, or game keys sold as a single SKU.
  • Game keys — keys for games and DLCs distributed via platforms like Steam or other DRM providers.
  • Groups — logical groupings for organizing and sorting items within the catalog.

API calls

The API is divided into the following groups:

  • Admin — calls for creating, updating, deleting, and configuring catalog items and groups. Authenticated via basic access authentication with your merchant or project credentials. Not intended for storefront use.
  • Catalog — calls for retrieving items and building custom storefronts for end users. Designed to handle high-load scenarios. Support optional user JWT authorization to return personalized data such as user-specific limits and active promotions.

Authentication

API calls require authentication either on behalf of a user or on behalf of a project. The authentication scheme used is specified in the Security section in the description of each call.

Authentication using user's JWT

User's JWT authentication is used when a request is sent from a browser, mobile application, or game. By default, the XsollaLoginUserJWT scheme is applied. For details on how to create a token, see the Xsolla Login API documentation.

The token is passed in the Authorization header in the following format: Authorization: Bearer <user_JWT>, where <user_JWT> is the user token. The token identifies the user and provides access to personalized data.

別の方法として、決済UIを開くためのトークンを使用することも可能です。

Basic HTTP authentication

Basic HTTP authentication is used for server-to-server interactions, when an API call is sent directly from your server rather than from a user's browser or mobile application. HTTP Basic authentication with an API key is typically used.

Note

The API key is confidential and must not be stored or used in client applications.

With basic server-side authentication, all API requests must include the following header:

  • for basicAuth — Authorization: Basic <your_authorization_basic_key>, where your_authorization_basic_key is the project_id:api_key pair encoded in Base64
  • for basicMerchantAuth — Authorization: Basic <your_authorization_basic_key>, where your_authorization_basic_key is the merchant_id:api_key pair encoded in Base64

You can find the parameter values in Publisher Account:

  • merchant_id is displayed:
    • In Company settings > Company.
    • In the URL in the browser address bar on any Publisher Account page. The URL has the following format: https://publisher.xsolla.com/<merchant_id>.
  • project_id is displayed:
    • Next to the project name in Publisher Account.
    • In the URL in the browser address bar when working on a project in Publisher Account. The URL has the following format: https://publisher.xsolla.com/<merchant_id>/projects/<project_id>.
  • api_key is shown in Publisher Account only at the time of creation and must be stored securely on your side. You can create an API key in the following sections:
Notice

If a required API call doesn't include the project_id path parameter, use an API key that is valid across all company projects for authorization.

For more information about working with API keys, see the API references.

Authentication with guest access support

AuthForCart認証スキームはカートでの購入用であり、以下の2つのモードに対応しています：

  1. Authentication with a user's JWT. The token is passed in the Authorization header in the following format: Authorization: Bearer <user_JWT>, where <user_JWT> is the user token. The token identifies the user and provides access to personalized data. Alternatively, you can use a token for opening the payment UI.

  2. Simplified mode without Authorization header. This mode is used only for unauthorized users and can be applied only for game key sales. Instead of a token, the request must include the following headers:

    • x-unauthorized-id with a request ID
    • x-user with the user's email address encoded in Base64

Core entity structure

Items of all types (virtual items, bundles, virtual currency, and keys) use a similar data structure. Understanding the basic structure simplifies working with the API and helps you navigate the documentation more easily.

Note

Some calls may include additional fields but they don't change the basic structure.

Identification

  • merchant_id — company ID in Publisher Account
  • project_id — project ID in Publisher Account
  • sku — item SKU, unique within the project

Store display

  • name — item name
  • description — item description
  • image_url — image URL
  • is_enabled — item availability
  • is_show_in_store — whether the item is displayed in the catalog

For more information about managing item availability in the catalog, see the documentation.

Organization

  • type — item type, for example, a virtual item (virtual_item) or bundle (bundle)
  • groups — groups the item belongs to
  • order — display order in the catalog

Sale conditions

  • prices — prices in real or virtual currency
  • limits — purchase limits
  • periods — availability periods
  • regions — regional restrictions

Example of core entity structure:

{
  "attributes": [],
  "bundle_type": "virtual_currency_package",
  "content": [
    {
      "description": {
        "en": "Main in-game currency"
      },
      "image_url": "https://.../image.png",
      "name": {
        "en": "Crystals",
        "de": "Kristalle"
      },
      "quantity": 500,
      "sku": "com.xsolla.crystal_2",
      "type": "virtual_currency"
    }
  ],
  "description": {
    "en": "Crystals x500"
  },
  "groups": [],
  "image_url": "https://.../image.png",
  "is_enabled": true,
  "is_free": false,
  "is_show_in_store": true,
  "limits": {
    "per_item": null,
    "per_user": null,
    "recurrent_schedule": null
  },
  "long_description": null,
  "media_list": [],
  "name": {
    "en": "Medium crystal pack"
  },
  "order": 1,
  "periods": [
    {
      "date_from": null,
      "date_until": "2020-08-11T20:00:00+03:00"
    }
  ],
  "prices": [
    {
      "amount": 20,
      "country_iso": "US",
      "currency": "USD",
      "is_default": true,
      "is_enabled": true
    }
  ],
  "regions": [],
  "sku": "com.xsolla.crystal_pack_2",
  "type": "bundle",
  "vc_prices": []
}

Basic purchase flow

The Xsolla API allows you to implement in-game store logic, including retrieving the item catalog, managing the cart, creating orders, and tracking their status. Depending on the integration scenario, API calls are divided into Admin and Catalog subsections, which use different authentication schemes.

The following example shows a basic flow for setting up and operating a store, from item creation to purchase.

Create items and groups (Admin)

Create an item catalog for your store, such as virtual items, bundles, or virtual currency.

Example API calls:

Set up promotions, chains, and limits (Admin)

Configure user acquisition and monetization tools, such as discounts, bonuses, daily rewards, or offer chains.

Example API calls:

Get item information (Client)

Configure item display in your application.

Notice

Do not use API calls from the Admin subsection to build a user catalog. These API calls have rate limits and aren't intended for user traffic.

Example API calls:

Note

By default, catalog API calls return items that are currently available in the store at the time of the request. To retrieve items that are not yet available or are no longer available, include the parameter "show_inactive_time_limited_items": 1 in the catalog request.

Sell items

You can sell items using the following methods:

  • Fast purchase — sell one SKU multiple times.
  • Cart purchase — the user adds items to the cart, removes items, and updates quantities within a single order.

If an item is purchased using virtual currency instead of real money, use the Create order with specified item purchased by virtual currency API call. The payment UI is not required, as the charge is processed when the API call is executed.

For free item purchase, use the Create order with specified free item API call or the Create order with free cart API call. The payment UI is not required — the order is immediately set to the done status.

Fast purchase

Use the client-side API call to create an order with a specified item. The call returns a token used to open the payment UI.

Note

Discount information is available to the user only in the payment UI. Promo codes are not supported.

Cart purchase

Cart setup and purchase can be performed on the client or on the server side.

Set up and purchase a cart on the client

Implement the logic of adding and removing items by yourself. Before calling the API for setting up a cart, you will not have information about which promotions will be applied to the purchase. This means that the total cost and details of the added bonus items will not be known.

Implement the following cart logic:

  1. After the player has filled a cart, use the Fill cart with items API call. The call returns the current information about the selected items (prices before and after discounts, bonus items).
  2. Update the cart contents based on user actions:
Note

To get the current status of the cart, use the Get current user's cart API call.
  1. Use the Create order with all items from current cart API call. The call returns the order ID and payment token. The newly created order is set to new status by default.

Set up and purchase a cart on the server

This setup option may take longer for setting the cart up, since each change to the cart must be accompanied by API calls.

Implement the following cart logic:

  1. After the player has filled a cart, use the Fill cart with items API call. The call returns current information about the selected items (prices before and after discounts, bonus items).
  2. Use the Create order with all items from current cart API call. The call returns the order ID and payment token. The newly created order is set to new status by default.

Open payment UI

Use the returned token to open the payment UI in a new window. Other ways to open the payment UI are described in the documentation.

ActionEndpoint
Open in production environment.https://secure.xsolla.com/paystation4/?token={token}
Open in sandbox mode.https://sandbox-secure.xsolla.com/paystation4/?token={token}
Note

Use sandbox mode during development and testing. Test purchases don't charge real accounts. You can use test bank cards.

After the first real payment is made, a strict sandbox payment policy takes effect. A payment in sandbox mode is available only to users specified in Publisher Account > Company settings > Users.

Buying virtual currency and items for real currency is possible only after signing a license agreement with Xsolla. To do this, in Publisher Account, go to Agreements & Taxes > Agreements, complete the agreement form, and wait for confirmation. It may take up to 3 business days to review the agreement.

To enable or disable sandbox mode, change the value of the sandbox parameter in the request for fast purchase and cart purchase. Sandbox mode is off by default.

Possible order statuses:

  • new — order created
  • paid — payment received
  • done — item delivered
  • canceled — order canceled
  • expired — order expired

Track order status using one of the following methods:

Pagination

API calls that return large sets of records (for example, when building a catalog) return data in pages. Pagination is a mechanism that limits the number of items returned in a single API response and allows you to retrieve subsequent pages sequentially.

Use the following parameters to control the number of returned items:

  • limit — number of items per page
  • offset — index of the first item on the page (numbering starts from 0)
  • has_more — indicates whether another page is available
  • total_items_count — total number of items

Example request:

GET /items?limit=20&offset=40

Response example:

{
  "items": [...],
  "has_more": true,
  "total_items_count": 135
}

It is recommended to send subsequent requests until the response returns has_more = false.

Date and time format

Dates and time values are passed in the ISO 8601 format.

The following are supported:

  • UTC offset
  • null value when there is no time restriction for displaying an item
  • Unix timestamp (in seconds) used in some fields

Format: YYYY-MM-DDTHH:MM:SS±HH:MM

Example: 2026-03-16T10:00:00+03:00

Localization

Xsolla supports localization of user-facing fields such as item name and description. Localized values are passed as an object where the language code is used as the key. The full list of supported languages is available in the documentation.

Supported fields

Localization can be specified for the following parameters:

  • name
  • description
  • long_description

Locale format

The locale key can be specified in one of the following formats:

  • Two-letter language code: en, ru
  • Five-letter language code: en-US, ru-RU, de-DE

Examples

Example with a two-letter language code:

{
  "name": {
    "en": "Starter Pack",
    "ru": "Стартовый набор"
  }
}

Example with a five-letter language code:

{
  "description": {
    "en-US": "Premium bundle",
    "de-DE": "Premium-Paket"
  }
}

Country and currency determination

The user's country determines catalog prices, the payment currency, and available payment methods in the payment UI. Depending on the API call, the country is determined as follows:

  • In client-side API calls, the country is determined by the IP address of the request.
  • In server-side API calls, the country is determined by the value of the user.country.value parameter or by the user's IP address from the X-User-Ip header. If both are passed, the user.country.value parameter takes precedence.
Note

Only IPv4 addresses are supported for country determination. Passing an IPv6 address may result in incorrect country and currency detection. If you use the server-side API call and cannot provide the user's IPv4 address, pass the country in the user.country.value parameter.

Error response format

If an error occurs, the API returns an HTTP status and a JSON response body. The full list of store-related errors is available in the documentation.

Response example:

{
  "errorCode": 1102,
  "errorMessage": "Validation error",
  "statusCode": 422,
  "transactionId": "c9e1a..."
}
  • errorCode — error code.
  • errorMessage — short error description.
  • statusCode — HTTP response status.
  • transactionId — request ID. Returned only in some cases.
  • errorMessageExtended — additional error details, such as request parameters. Returned only in some cases.

Extended response example:

{
  "errorCode": 7001,
  "errorMessage": "Chain not found",
  "errorMessageExtended": {
    "chain_id": "test_chain_id",
    "project_id": "test_project_id",
    "step_number": 2
  },
  "statusCode": 404
}

Common HTTP status codes

  • 400 — invalid request
  • 401 — authentication error
  • 403 — insufficient permissions
  • 404 — resource not found
  • 422 — validation error
  • 429 — rate limit exceeded

Recommendations

  • Handle the HTTP status and the response body together.
  • Use errorCode to process errors related to application logic.
  • Use transactionId to identify requests more quickly when analyzing errors.
OpenAPI記述をダウンロード
index.json
index.yaml
言語
サーバー
https://store.xsolla.com/api/
Mock server
https://xsolla.redocly.app/_mock/ja/api/catalog/

概要

仮想アイテムと仮想通貨を使用してインゲームストアを構築し、ユーザーへの表示方法を設定できます。以下のアイテムタイプが利用可能です：

  • 仮想アイテム — 武器、スキン、ブースターなどのゲーム内アイテム。実際のお金または仮想通貨で販売できます。
  • 仮想通貨 — 仮想アイテムの購入に使用されるゲーム内通貨。実際のお金または仮想通貨で販売できます。
  • 仮想通貨パッケージ — 仮想通貨の固定数量パック。実際のお金または仮想通貨で販売できます。

グループは、カタログ内のアイテムを整理するために使用されます。アイテムを論理的にグループ化し、表示方法を管理することができます。

管理者サブセクションのAPIコールを使用して、アイテムの作成、更新、削除を行います。

カタログサブセクションのAPIコールを使用して、アイテムのリストを取得し、ユーザーに表示します。

注意

管理者サブセクションのAPIコールを使用してストアカタログを構築しないでください。

注意

仮想アイテムリストを取得するAPIコールは、価格や属性を含む詳細なアイテムデータを返し、ページネーションをサポートします。ストアフロントでカタログページを表示するために使用してください。

すべての仮想アイテムリストを取得するAPIコールは、ページネーションなしでアイテムSKU、名前、説明、グループIDと名前を返します。クライアント側の検索やインデックス作成に使用してください。

仮想通貨で購入する場合、仮想通貨で購入された指定アイテムで注文を作成するAPIコールを使用してください。当該APIコールの実行時に課金処理が行われるため、決済UIを表示する必要はありません。

仮想通貨での購入フローの例：

仮想通貨での購入フローの例：

管理者

操作

カタログ

操作

仮想決済

操作

概要

ゲームキーは、ユーザーがゲームプラットフォーム上でゲームやDLCにアクセスできるようにするための、使い切りのユニークな半角英数字コードです。ゲームキーは、ダイレクトリンク、ストアUI、またはウィジェットを介して販売することができます。また、特定の国でゲームキーを販売するために、地域別制限を設定することも可能です。詳細については、ゲームキーパッケージセクションを参照してください。

ゲームキーを販売する際、ユーザー認証は必須ではありません。キーは、ユーザーがチェックアウト時に指定したメールアドレス宛に送信されます。また、認証を設定することで、個人用設定、購入制限、エンタイトルメントシステムといった追加のシナリオを有効にすることも可能です。詳細については、ゲームキー販売時の認証設定方法セクションを参照してください。

ゲームキーの販売フロー：

  1. ゲームを作成するAPIコールを使用して、ゲームを作成します。
  2. 地域制限を設定します。
  3. コードをアップロードするAPIコールを使用してゲームキーパッケージにキーをアップロードし、購入可能な状態にします。
  4. ゲームリストを取得するAPIコールを使用して、ユーザーの地域に応じた価格とともにゲームカタログを表示します。
  5. 注文を作成します。素早く購入できるようにするには、ゲームキーのSKUを渡し、現在のカート内の全アイテムを含む注文を作成するAPIコールを使用できます。レスポンスとして、決済UIを開くためのトークンが返されます。
  6. 注文の支払いを行うために、決済UIを開く処理を実装します。

決済完了の通知をタイムリーに受け取り、ユーザーにアイテムを付与するには、たとえば、ウェブフックを使用して注文ステータスのトラッキングを設定してください。キーは、ユーザーがチェックアウト時に指定したメールアドレス宛に送信され、注文ステータスはdoneに移行します。

ゲームキー

カタログ

操作

資格

操作

管理者

操作

概要

バンドルとは、複数のアイテムを1つの単位としてセット販売するものです。バンドルには、仮想アイテム、仮想通貨、仮想通貨パッケージ、ゲームキー、および他のバンドルを含めることができます。バンドルを活用することで、スターターパック、季節限定オファー、特別セールなどを作成できます。

バンドルを操作するには、以下のAPIコールグループを使用します：

  • バンドルの作成、更新、削除、およびそれらの公開状態を管理するには、管理者サブセクションのAPIコールを使用します。
  • バンドルの情報取得には、カタログサブセクションのAPIコールを使用します。

購入制限は、バンドルの作成または更新時にlimitsオブジェクトを介して設定します。詳細については、制限の概要を参照してください。また、特定の国でアイテムを販売するために、地域制限を設定することも可能です。

注意

バンドルの設定に関する詳細情報については、バンドルセクションを参照してください。

バンドル管理のシナリオ：

  1. バンドルを作成する APIコールを使用して、バンドルを作成します。作成したバンドルを検証するには、バンドルを取得するAPIコールを使用します。プロジェクト内のすべてのバンドルを取得するには、バンドルリストを取得するAPIコールを使用します。
  2. 必要に応じて、バンドルを更新するAPIコールを使用し、バンドルの内容や設定を変更します。
  3. バンドルリストを取得する、指定したバンドルを取得する、または指定したグループのバンドルリストを取得するAPIコールを使用して、ストアフロントにバンドルの表示ロジックを実装します。
  4. カートと決済セクションを使用して注文を作成します。たとえば、素早く購入できるようにするには、バンドルのSKUを渡し、指定したアイテムを含む注文を作成するAPIコールを使用できます。応答には、決済UIを開くためのトークンが含まれています。
  5. 注文の支払いを行うために、決済UIを開く処理を実装します。
  6. 決済が完了したアイテムのデータをタイムリーに受け取り、ユーザーにそれらを付与するために、たとえばウェブフックを使用して注文ステータスのトラッキングを設定します。

バンドル管理のシナリオ

管理者

操作

カタログ

操作

概要

カートは、複数のアイテムを1つの注文にまとめることができる購入メカニズムです。ユーザーは、任意のタイプのアイテムを任意の数量で実際通貨で購入でき、プロモーションコードも使用できます。

カートはエクソーラ側で保存されます。セッションをまたいでカートを保存できるかどうかは、ユーザーが認証されているかによって異なります。

  • 認証されたユーザーの場合、カートは特定のユーザーに紐付けられ、同じユーザーとしてリクエストが送信される限り、セッションをまたいで保存されます。

  • 未認証ユーザーの場合、カートの保存はx-unauthorized-idヘッダーの成否に依存します。未認証ユーザーのカートをセッション間で保持するには、すべてのリクエストで同じx-unauthorized-idを渡してください。なお、このオプションはゲームキーの販売時のみ利用可能です。

カートを特定する方法は2つあります。ユーザーのJWTによる自動特定、またはカートID（cart_id）による特定です。

カート管理は、クライアント側とサーバー側の両方で利用可能です。

サーバー側では、ユーザーセッションを復元する場合などに、カートにアイテムを入れることができます。クライアント側では、以下の操作が利用可能です：

  • 現在のユーザーのカートまたはIDによるカートを取得する
  • カートにアイテムを追加する
  • カート内のアイテムを更新する
  • カートからアイテムを削除する

カートからアイテムを購入するには、注文作成のためのクライアントとサーバーのコールが使用されます。

カートの有効期限（TTL）は、デフォルトで72時間です。新しいアイテムが追加されるなど、カートの内容が変更されると、TTLは延長されます。

決済が成功した後も、カートは自動的にはクリアされません。カートをクリアするには、クライアントサイドの以下のAPIコールを使用してください：

カート使用シナリオ：

  1. ユーザーがアイテムを選択するストアUIを実装します。

  2. ユーザーがストアでアイテムを選択した際、たとえば カートへアイテムを追加するコールを使用してアイテムをカートに追加します。アイテム配列には、SKUと必要なアイテムの数量を渡す必要があります。

  3. カート表示UIを実装します。ユーザーがカートに移動した際、現在のユーザーのカートを取得するコールを使用してカートの内容を表示します。応答には、割引や適用されたプロモーションを含むアイテムの最終価格に関する情報が返されます。

  4. 注文の支払いを行うために、決済UIを開く処理を実装します。たとえば、特定のカートの全アイテムを含む注文を作成するコールを使用できます。応答には、決済UIを開くためのトークンが返されます。

  5. 決済が完了したアイテムのデータをタイムリーに受け取り、ユーザーにそれらを付与するために、たとえばウェブフックを使用して注文状況の追跡を設定します。

注意

ゲーム内およびオンラインでのアイテム販売を実装するには、統合ガイドを参照してください。

カートと決済フロー

注文のライフサイクル

注文のライフサイクルを理解することは、注文の追跡や、アイテムの付与といった購入後ロジックの正確な実装に役立ちます。

注文は以下のステータスを遷移します：

ステータス説明備考
new注文が作成されました。システムは支払い完了の確認を待っています。トランザクションステータスの説明は、ペイステーションAPIに関するドキュメントで確認できます。
paid注文の支払いが完了し（トランザクションがdoneステータスに移行）、ユーザーにアイテムを付与できる状態です支払いが確認されるまで、注文はnewステータスのままとなります。
doneアイテムがユーザーに付与されました。 —
canceled支払いが返金されました。トランザクションステータスがrefundedに変更されると、注文はこのステータスに移行します。
expired制限 付きアイテム、プロモーションコード、またはプロモーションに対して新しい注文を作成すると、そのアイテムを含む過去の未払いの注文はすべてexpiredステータスに移行します。支払いが可能なのは最新の注文のみです。ユーザーが有効期限切れの注文に対して支払いを試みた場合、支払いUIに 2002 エラーが表示され、決済は失敗します。

注文のライフサイクル

注意

ユーザーが支払いを完了する間に注文がexpiredステータスに移行した場合でも、決済自体が成功したときは、注文はexpiredからpaidステータスに移行します。ただし、これが適用されるのは、決済時にその注文アイテムの購入制限数を超えない場合に限られます。

カート（クライアント側）

このセクションのコールを使用して、クライアント側でカートを管理します。

操作

カート（サーバー側）

このセクションのコールを使用して、サーバー側でカートを管理します。

操作

決済（クライアント側）

このセクションのコールを使用して、クライアント側で決済トークンを作成します。

操作

決済（サーバー側）

このセクションのコールを使用して、サーバー側で決済トークンを作成します。

操作

注文

このセクションのコールを使用して、注文に関する情報を取得します。

操作

無料アイテム

ユーザーに無料アイテムを付与するには、このセクションのコールを使用してください。

操作

無料カートで注文を作成Client-side

リクエスト

無料カートのすべてのアイテムを含む注文を作成します。作成された注文はdoneという注文状況を取得します。

セキュリティ
AuthForCart
パス
project_idinteger必須

プロジェクトID。このパラメータは、パブリッシャーアカウントのプロジェクト名の横、またはプロジェクトの作業中にブラウザのアドレスバーで確認できます。URLの形式は以下の通りです：https://publisher.xsolla.com/<merchant_id>/projects/<project_id>。

例: 44056
ボディapplication/json
currencystring

注文価格の通貨。3文字の通貨コードISO4217 規格詳細については、ドキュメントを参照してください。エクソーラでサポートされている通貨。

localestring

応答言語。

sandboxboolean

サンドボックスモードで注文を作成します。このオプションは、会社のユーザーリストに指定されているユーザーに使用できます。

デフォルト false
settingsobject

ユーザーの支払いプロセスと決済UIを構成するための設定。

settings.​uiobject

インターフェイス設定。

settings.​ui.​themestring

決済UIのテーマ。ライトテーマ（デフォルト）の場合は63295a9a2e47fab76f7708e1、ダークテーマの場合は63295aab2e47fab76f7708e3を指定できます。カスタムテーマを作成して、そのIDをこのパラメータに渡すこともできます。

デフォルト "63295a9a2e47fab76f7708e1"
Enum"63295a9a2e47fab76f7708e1""63295aab2e47fab76f7708e3"
settings.​ui.​desktopobject

デスクトップ版のインターフェース設定。

settings.​ui.​desktop.​headerobject

ヘッダー設定。

settings.​ui.​desktop.​header.​is_visibleboolean

決済インターフェースにヘッダーを表示するかどうかを示します。

settings.​ui.​desktop.​header.​visible_logoboolean

trueの場合、ロゴはヘッダーに表示されます。画像をアップロードするには、パブリッシャーアカウントでプロジェクトを開き、ペイステーション > 設定セクションにアクセスしてください。

settings.​ui.​desktop.​header.​visible_nameboolean

ヘッダーにプロジェクト名を表示するかどうかを示します。

settings.​ui.​desktop.​header.​visible_purchaseboolean

ヘッダーに購入説明（purchase.description.value）を表示するか示します。デフォルトはtrueです。

デフォルト true
settings.​ui.​desktop.​header.​typestring

ヘッダーを表示する方法。compact（プロジェクト名とユーザーIDを隠す）またはnormal（デフォルト）に指定できます。

デフォルト "normal"
Enum"compact""normal"
settings.​ui.​desktop.​header.​close_buttonboolean

デスクトップ決済UIに閉じるボタンを表示するかどうか。このボタンは決済UIを閉じて、settings.return_urlパラメータで指定したURLにリダイレクトします。デフォルトはfalseです。

デフォルト false
settings.​ui.​modestring

決済UIのインターフェースモード。user_accountのみに指定できます：ヘッダーにはユーザーアカウントのナビゲーションメニューのみが含まれています。ユーザーは商品を選択したり、決済を行うことはできません。このモードは、デスクトップ上でのみ使用できます。

値"user_account"
settings.​ui.​user_accountobject

ユーザーアカウントの詳細。

settings.​ui.​user_account.​payment_accountsobject

お客様の決済アカウント サブメニュー。

settings.​ui.​user_account.​payment_accounts.​enableboolean必須

サブメニューを表示するかどうかを示します。デフォルトではfalseです。

デフォルト false
settings.​ui.​user_account.​infoobject

私のアカウント ページ。

settings.​ui.​user_account.​info.​enableboolean必須

サブメニューを表示するかどうかを示します。デフォルトではfalseです。

デフォルト false
settings.​ui.​user_account.​info.​orderinteger>= 1必須

メニュー内のサブメニューの位置。

settings.​ui.​user_account.​subscriptionsobject

サブスクリプションの管理 サブメニュー。

settings.​ui.​user_account.​subscriptions.​enableboolean必須

サブメニューを表示するかどうかを示します。デフォルトではfalseです。

デフォルト false
settings.​ui.​user_account.​subscriptions.​orderinteger>= 1必須

メニュー内のサブメニューの位置。

settings.​ui.​headerobject
settings.​ui.​header.​visible_virtual_currency_balanceboolean

この要素を決済インターフェースで非示にできるかどうかを示します。

デフォルト true
settings.​ui.​mobileobject
settings.​ui.​mobile.​headerobject
settings.​ui.​mobile.​header.​close_buttonboolean

モバイル決済UIに閉じるボタンを表示するかどうか。このボタンは決済UIを閉じて、settings.return_urlパラメータで指定したURLにリダイレクトします。

デフォルト false
settings.​ui.​is_prevent_external_link_openboolean

リンクを外部リソースにリダイレクトするかどうかを無効にします。外部リンクをクリックすると、external-link-openイベントがpostMessageメカニズムを介して送信されます。urlパラメータには、リダイレクト先のリンクのアドレスが渡されます。

デフォルト false
settings.​ui.​is_payment_methods_list_modeboolean

決済UIを開く際に、ユーザーの国で利用可能な決済方法のリストを表示するかどうか。falseの場合（デフォルト）、settings.payment_methodパラメータで渡された決済方法、またはPayRankアルゴリズムで選択された方法が表示されます。

デフォルト false
settings.​ui.​is_independent_windowsboolean

埋め込みランチャーのブラウザ（WebView）から、ユーザーのデフォルトのブラウザにリダイレクトして購入させるかどうか。

デフォルト false
settings.​ui.​currency_formatstring

codeに設定すると、決済UIに3 文字のISO 4217通貨コードが表示されます。 デフォルトでは、3文字の通貨コードの代わりに通貨記号が表示されます。

settings.​ui.​is_show_close_widget_warningboolean

支払いページを閉じる前に、×アイコンの上にカーソルを置いたときに取引処理に関する警告を表示するかどうか。falseが渡された場合、またはパラメータが渡されなかった場合、警告は表示されません。

デフォルト true
settings.​ui.​layoutstring

決済UIの主要要素の位置。ゲーム内で決済UIを開いたり、注文や決済方法に関する情報の列を入れ替えたりすることができます。詳細については、カスタマイズに関する説明を参照してください。

Enum"embed""column_reverse""embed_column_reverse"
settings.​ui.​is_three_ds_independent_windowsboolean

3-Dセキュア検証が新しいブラウザウィンドウで開くかどうか。セットアップでコンテンツセキュリティポリシー（CSP）が適用される場合は、trueに設定します。

デフォルト false
settings.​ui.​is_cart_open_by_defaultboolean

モバイル版の決済UIを開いた時のカート内のアイテムリストの表示。trueの場合、リストは拡張ビューで表示されます。false（デフォルト）またはパラメータが渡されない場合、リストは折りたたまれたビューで表示されます。

デフォルト false
settings.​payment_methodinteger>= 1

決済方法ID。決済方法によっては特定の通貨のみをサポートする場合があるため、決済インターフェースにおける通貨の表示を決定します。

settings.​return_urlstring(uri)<= 1000 characters

決済完了後にユーザーがリダイレクトされるページ。リンクにはuser_id、foreigninvoice、invoice_id、およびstatusパラメータが自動的に追加されます。

settings.​redirect_policyobject
settings.​redirect_policy.​redirect_conditionsstring

ユーザーがリターンURLにリダイレクトする引き金となる決済状態。

Enum"none""successful""successful_or_canceled""any"
例: "none"
settings.​redirect_policy.​delayinteger

ユーザーが自動的に戻り先URLにリダイレクトされるまでの遅延期間。

例: 0
settings.​redirect_policy.​status_for_manual_redirectionstring

ユーザーをリターンURLにリダイレクトしてボタンクリックの表示をトリガーする決済状態。

Enum"none""successful""successful_or_canceled""any"
例: "none"
settings.​redirect_policy.​redirect_button_captionstring

ローカライズされたリダイレクトボタンのキャプション。

例: "Text button"
custom_parametersobject[ 1 .. 200 ] properties

プロジェクト特有のパラメータ。

curl -i -X POST \
  https://store.xsolla.com/api/v2/project/44056/free/cart \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "sandbox": true,
    "settings": {
      "ui": {
        "theme": "63295a9a2e47fab76f7708e1",
        "desktop": {
          "header": {
            "is_visible": true,
            "visible_logo": true,
            "visible_name": true,
            "visible_purchase": true,
            "type": "normal",
            "close_button": false
          }
        }
      }
    },
    "custom_parameters": {
      "character_id": "ingameUsername"
    }
  }'

レスポンス

無料注文が正常に作成されました。

ボディapplication/json
order_idinteger

注文ID。

レスポンス
application/json
{
  "order_id": 641
}

特定の無料カートで注文を作成Client-side

リクエスト

特定の無料カートのすべてのアイテムを含む注文を作成します。作成された注文はdoneという注文状況を取得します。

セキュリティ
AuthForCart
パス
project_idinteger必須

プロジェクトID。このパラメータは、パブリッシャーアカウントのプロジェクト名の横、またはプロジェクトの作業中にブラウザのアドレスバーで確認できます。URLの形式は以下の通りです：https://publisher.xsolla.com/<merchant_id>/projects/<project_id>。

例: 44056
cart_idstring必須

カートID。

例: custom_id
ボディapplication/json
currencystring

注文価格の通貨。3文字の通貨コードISO4217 規格詳細については、ドキュメントを参照してください。エクソーラでサポートされている通貨。

localestring

応答言語。

sandboxboolean

サンドボックスモードで注文を作成します。このオプションは、会社のユーザーリストに指定されているユーザーに使用できます。

デフォルト false
settingsobject

ユーザーの支払いプロセスと決済UIを構成するための設定。

settings.​uiobject

インターフェイス設定。

settings.​ui.​themestring

決済UIのテーマ。ライトテーマ（デフォルト）の場合は63295a9a2e47fab76f7708e1、ダークテーマの場合は63295aab2e47fab76f7708e3を指定できます。カスタムテーマを作成して、そのIDをこのパラメータに渡すこともできます。

デフォルト "63295a9a2e47fab76f7708e1"
Enum"63295a9a2e47fab76f7708e1""63295aab2e47fab76f7708e3"
settings.​ui.​desktopobject

デスクトップ版のインターフェース設定。

settings.​ui.​desktop.​headerobject

ヘッダー設定。

settings.​ui.​desktop.​header.​is_visibleboolean

決済インターフェースにヘッダーを表示するかどうかを示します。

settings.​ui.​desktop.​header.​visible_logoboolean

trueの場合、ロゴはヘッダーに表示されます。画像をアップロードするには、パブリッシャーアカウントでプロジェクトを開き、ペイステーション > 設定セクションにアクセスしてください。

settings.​ui.​desktop.​header.​visible_nameboolean

ヘッダーにプロジェクト名を表示するかどうかを示します。

settings.​ui.​desktop.​header.​visible_purchaseboolean

ヘッダーに購入説明（purchase.description.value）を表示するか示します。デフォルトはtrueです。

デフォルト true
settings.​ui.​desktop.​header.​typestring

ヘッダーを表示する方法。compact（プロジェクト名とユーザーIDを隠す）またはnormal（デフォルト）に指定できます。

デフォルト "normal"
Enum"compact""normal"
settings.​ui.​desktop.​header.​close_buttonboolean

デスクトップ決済UIに閉じるボタンを表示するかどうか。このボタンは決済UIを閉じて、settings.return_urlパラメータで指定したURLにリダイレクトします。デフォルトはfalseです。

デフォルト false
settings.​ui.​modestring

決済UIのインターフェースモード。user_accountのみに指定できます：ヘッダーにはユーザーアカウントのナビゲーションメニューのみが含まれています。ユーザーは商品を選択したり、決済を行うことはできません。このモードは、デスクトップ上でのみ使用できます。

値"user_account"
settings.​ui.​user_accountobject

ユーザーアカウントの詳細。

settings.​ui.​user_account.​payment_accountsobject

お客様の決済アカウント サブメニュー。

settings.​ui.​user_account.​payment_accounts.​enableboolean必須

サブメニューを表示するかどうかを示します。デフォルトではfalseです。

デフォルト false
settings.​ui.​user_account.​infoobject

私のアカウント ページ。

settings.​ui.​user_account.​info.​enableboolean必須

サブメニューを表示するかどうかを示します。デフォルトではfalseです。

デフォルト false
settings.​ui.​user_account.​info.​orderinteger>= 1必須

メニュー内のサブメニューの位置。

settings.​ui.​user_account.​subscriptionsobject

サブスクリプションの管理 サブメニュー。

settings.​ui.​user_account.​subscriptions.​enableboolean必須

サブメニューを表示するかどうかを示します。デフォルトではfalseです。

デフォルト false
settings.​ui.​user_account.​subscriptions.​orderinteger>= 1必須

メニュー内のサブメニューの位置。

settings.​ui.​headerobject
settings.​ui.​header.​visible_virtual_currency_balanceboolean

この要素を決済インターフェースで非示にできるかどうかを示します。

デフォルト true
settings.​ui.​mobileobject
settings.​ui.​mobile.​headerobject
settings.​ui.​mobile.​header.​close_buttonboolean

モバイル決済UIに閉じるボタンを表示するかどうか。このボタンは決済UIを閉じて、settings.return_urlパラメータで指定したURLにリダイレクトします。

デフォルト false
settings.​ui.​is_prevent_external_link_openboolean

リンクを外部リソースにリダイレクトするかどうかを無効にします。外部リンクをクリックすると、external-link-openイベントがpostMessageメカニズムを介して送信されます。urlパラメータには、リダイレクト先のリンクのアドレスが渡されます。

デフォルト false
settings.​ui.​is_payment_methods_list_modeboolean

決済UIを開く際に、ユーザーの国で利用可能な決済方法のリストを表示するかどうか。falseの場合（デフォルト）、settings.payment_methodパラメータで渡された決済方法、またはPayRankアルゴリズムで選択された方法が表示されます。

デフォルト false
settings.​ui.​is_independent_windowsboolean

埋め込みランチャーのブラウザ（WebView）から、ユーザーのデフォルトのブラウザにリダイレクトして購入させるかどうか。

デフォルト false
settings.​ui.​currency_formatstring

codeに設定すると、決済UIに3 文字のISO 4217通貨コードが表示されます。 デフォルトでは、3文字の通貨コードの代わりに通貨記号が表示されます。

settings.​ui.​is_show_close_widget_warningboolean

支払いページを閉じる前に、×アイコンの上にカーソルを置いたときに取引処理に関する警告を表示するかどうか。falseが渡された場合、またはパラメータが渡されなかった場合、警告は表示されません。

デフォルト true
settings.​ui.​layoutstring

決済UIの主要要素の位置。ゲーム内で決済UIを開いたり、注文や決済方法に関する情報の列を入れ替えたりすることができます。詳細については、カスタマイズに関する説明を参照してください。

Enum"embed""column_reverse""embed_column_reverse"
settings.​ui.​is_three_ds_independent_windowsboolean

3-Dセキュア検証が新しいブラウザウィンドウで開くかどうか。セットアップでコンテンツセキュリティポリシー（CSP）が適用される場合は、trueに設定します。

デフォルト false
settings.​ui.​is_cart_open_by_defaultboolean

モバイル版の決済UIを開いた時のカート内のアイテムリストの表示。trueの場合、リストは拡張ビューで表示されます。false（デフォルト）またはパラメータが渡されない場合、リストは折りたたまれたビューで表示されます。

デフォルト false
settings.​payment_methodinteger>= 1

決済方法ID。決済方法によっては特定の通貨のみをサポートする場合があるため、決済インターフェースにおける通貨の表示を決定します。

settings.​return_urlstring(uri)<= 1000 characters

決済完了後にユーザーがリダイレクトされるページ。リンクにはuser_id、foreigninvoice、invoice_id、およびstatusパラメータが自動的に追加されます。

settings.​redirect_policyobject
settings.​redirect_policy.​redirect_conditionsstring

ユーザーがリターンURLにリダイレクトする引き金となる決済状態。

Enum"none""successful""successful_or_canceled""any"
例: "none"
settings.​redirect_policy.​delayinteger

ユーザーが自動的に戻り先URLにリダイレクトされるまでの遅延期間。

例: 0
settings.​redirect_policy.​status_for_manual_redirectionstring

ユーザーをリターンURLにリダイレクトしてボタンクリックの表示をトリガーする決済状態。

Enum"none""successful""successful_or_canceled""any"
例: "none"
settings.​redirect_policy.​redirect_button_captionstring

ローカライズされたリダイレクトボタンのキャプション。

例: "Text button"
custom_parametersobject[ 1 .. 200 ] properties

プロジェクト特有のパラメータ。

curl -i -X POST \
  https://store.xsolla.com/api/v2/project/44056/free/cart/custom_id \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "sandbox": true,
    "settings": {
      "ui": {
        "theme": "63295a9a2e47fab76f7708e1",
        "desktop": {
          "header": {
            "is_visible": true,
            "visible_logo": true,
            "visible_name": true,
            "visible_purchase": true,
            "type": "normal",
            "close_button": false
          }
        }
      }
    },
    "custom_parameters": {
      "character_id": "ingameUsername"
    }
  }'

レスポンス

無料注文が正常に作成されました。

ボディapplication/json
order_idinteger

注文ID。

レスポンス
application/json
{
  "order_id": 641
}

指定された無料アイテムで注文を作成Client-side

リクエスト

指定された無料アイテムで注文を作成します。作成された注文は、doneの注文ステータスになります。

注意

認証なしで使用した場合、このAPIコールは一般的なアイテムカタログデータを返します。認証を使用して、アイテムに関連する制限やプロモーションなどのパーソナライズされたユーザーデータを取得します。これを行うには、ユーザーのJWTをAuthorizationヘッダーに渡してください。ユーザーJWTの詳細については、このコールのセキュリティブロックを参照してください。
セキュリティ
XsollaLoginUserJWT
パス
project_idinteger必須

プロジェクトID。このパラメータは、パブリッシャーアカウントのプロジェクト名の横、またはプロジェクトの作業中にブラウザのアドレスバーで確認できます。URLの形式は以下の通りです：https://publisher.xsolla.com/<merchant_id>/projects/<project_id>。

例: 44056
item_skustring必須

アイテムSKU。

例: booster_mega_1
ボディapplication/json
currencystring

注文価格の通貨。3文字の通貨コードISO4217 規格詳細については、ドキュメントを参照してください。エクソーラでサポートされている通貨。

localestring

応答言語。

sandboxboolean

サンドボックスモードで注文を作成します。このオプションは、会社のユーザーリストに指定されているユーザーに使用できます。

デフォルト false
quantityinteger>= 1

アイテム数量。

デフォルト 1
promo_codestring

支払いによりプロモーションコードキャンペーンのコードを引き換えます。

settingsobject

ユーザーの支払いプロセスと決済UIを構成するための設定。

settings.​uiobject

インターフェイス設定。

settings.​ui.​themestring

決済UIのテーマ。ライトテーマ（デフォルト）の場合は63295a9a2e47fab76f7708e1、ダークテーマの場合は63295aab2e47fab76f7708e3を指定できます。カスタムテーマを作成して、そのIDをこのパラメータに渡すこともできます。

デフォルト "63295a9a2e47fab76f7708e1"
Enum"63295a9a2e47fab76f7708e1""63295aab2e47fab76f7708e3"
settings.​ui.​desktopobject

デスクトップ版のインターフェース設定。

settings.​ui.​desktop.​headerobject

ヘッダー設定。

settings.​ui.​desktop.​header.​is_visibleboolean

決済インターフェースにヘッダーを表示するかどうかを示します。

settings.​ui.​desktop.​header.​visible_logoboolean

trueの場合、ロゴはヘッダーに表示されます。画像をアップロードするには、パブリッシャーアカウントでプロジェクトを開き、ペイステーション > 設定セクションにアクセスしてください。

settings.​ui.​desktop.​header.​visible_nameboolean

ヘッダーにプロジェクト名を表示するかどうかを示します。

settings.​ui.​desktop.​header.​visible_purchaseboolean

ヘッダーに購入説明（purchase.description.value）を表示するか示します。デフォルトはtrueです。

デフォルト true
settings.​ui.​desktop.​header.​typestring

ヘッダーを表示する方法。compact（プロジェクト名とユーザーIDを隠す）またはnormal（デフォルト）に指定できます。

デフォルト "normal"
Enum"compact""normal"
settings.​ui.​desktop.​header.​close_buttonboolean

デスクトップ決済UIに閉じるボタンを表示するかどうか。このボタンは決済UIを閉じて、settings.return_urlパラメータで指定したURLにリダイレクトします。デフォルトはfalseです。

デフォルト false
settings.​ui.​modestring

決済UIのインターフェースモード。user_accountのみに指定できます：ヘッダーにはユーザーアカウントのナビゲーションメニューのみが含まれています。ユーザーは商品を選択したり、決済を行うことはできません。このモードは、デスクトップ上でのみ使用できます。

値"user_account"
settings.​ui.​user_accountobject

ユーザーアカウントの詳細。

settings.​ui.​user_account.​payment_accountsobject

お客様の決済アカウント サブメニュー。

settings.​ui.​user_account.​payment_accounts.​enableboolean必須

サブメニューを表示するかどうかを示します。デフォルトではfalseです。

デフォルト false
settings.​ui.​user_account.​infoobject

私のアカウント ページ。

settings.​ui.​user_account.​info.​enableboolean必須

サブメニューを表示するかどうかを示します。デフォルトではfalseです。

デフォルト false
settings.​ui.​user_account.​info.​orderinteger>= 1必須

メニュー内のサブメニューの位置。

settings.​ui.​user_account.​subscriptionsobject

サブスクリプションの管理 サブメニュー。

settings.​ui.​user_account.​subscriptions.​enableboolean必須

サブメニューを表示するかどうかを示します。デフォルトではfalseです。

デフォルト false
settings.​ui.​user_account.​subscriptions.​orderinteger>= 1必須

メニュー内のサブメニューの位置。

settings.​ui.​headerobject
settings.​ui.​header.​visible_virtual_currency_balanceboolean

この要素を決済インターフェースで非示にできるかどうかを示します。

デフォルト true
settings.​ui.​mobileobject
settings.​ui.​mobile.​headerobject
settings.​ui.​mobile.​header.​close_buttonboolean

モバイル決済UIに閉じるボタンを表示するかどうか。このボタンは決済UIを閉じて、settings.return_urlパラメータで指定したURLにリダイレクトします。

デフォルト false
settings.​ui.​is_prevent_external_link_openboolean

リンクを外部リソースにリダイレクトするかどうかを無効にします。外部リンクをクリックすると、external-link-openイベントがpostMessageメカニズムを介して送信されます。urlパラメータには、リダイレクト先のリンクのアドレスが渡されます。

デフォルト false
settings.​ui.​is_payment_methods_list_modeboolean

決済UIを開く際に、ユーザーの国で利用可能な決済方法のリストを表示するかどうか。falseの場合（デフォルト）、settings.payment_methodパラメータで渡された決済方法、またはPayRankアルゴリズムで選択された方法が表示されます。

デフォルト false
settings.​ui.​is_independent_windowsboolean

埋め込みランチャーのブラウザ（WebView）から、ユーザーのデフォルトのブラウザにリダイレクトして購入させるかどうか。

デフォルト false
settings.​ui.​currency_formatstring

codeに設定すると、決済UIに3 文字のISO 4217通貨コードが表示されます。 デフォルトでは、3文字の通貨コードの代わりに通貨記号が表示されます。

settings.​ui.​is_show_close_widget_warningboolean

支払いページを閉じる前に、×アイコンの上にカーソルを置いたときに取引処理に関する警告を表示するかどうか。falseが渡された場合、またはパラメータが渡されなかった場合、警告は表示されません。

デフォルト true
settings.​ui.​layoutstring

決済UIの主要要素の位置。ゲーム内で決済UIを開いたり、注文や決済方法に関する情報の列を入れ替えたりすることができます。詳細については、カスタマイズに関する説明を参照してください。

Enum"embed""column_reverse""embed_column_reverse"
settings.​ui.​is_three_ds_independent_windowsboolean

3-Dセキュア検証が新しいブラウザウィンドウで開くかどうか。セットアップでコンテンツセキュリティポリシー（CSP）が適用される場合は、trueに設定します。

デフォルト false
settings.​ui.​is_cart_open_by_defaultboolean

モバイル版の決済UIを開いた時のカート内のアイテムリストの表示。trueの場合、リストは拡張ビューで表示されます。false（デフォルト）またはパラメータが渡されない場合、リストは折りたたまれたビューで表示されます。

デフォルト false
settings.​payment_methodinteger>= 1

決済方法ID。決済方法によっては特定の通貨のみをサポートする場合があるため、決済インターフェースにおける通貨の表示を決定します。

settings.​return_urlstring(uri)<= 1000 characters

決済完了後にユーザーがリダイレクトされるページ。リンクにはuser_id、foreigninvoice、invoice_id、およびstatusパラメータが自動的に追加されます。

settings.​redirect_policyobject
settings.​redirect_policy.​redirect_conditionsstring

ユーザーがリターンURLにリダイレクトする引き金となる決済状態。

Enum"none""successful""successful_or_canceled""any"
例: "none"
settings.​redirect_policy.​delayinteger

ユーザーが自動的に戻り先URLにリダイレクトされるまでの遅延期間。

例: 0
settings.​redirect_policy.​status_for_manual_redirectionstring

ユーザーをリターンURLにリダイレクトしてボタンクリックの表示をトリガーする決済状態。

Enum"none""successful""successful_or_canceled""any"
例: "none"
settings.​redirect_policy.​redirect_button_captionstring

ローカライズされたリダイレクトボタンのキャプション。

例: "Text button"
custom_parametersobject[ 1 .. 200 ] properties

プロジェクト特有のパラメータ。

curl -i -X POST \
  https://store.xsolla.com/api/v2/project/44056/free/item/booster_mega_1 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "sandbox": true,
    "quantity": 5,
    "promo_code": "discount_code",
    "settings": {
      "ui": {
        "theme": "63295a9a2e47fab76f7708e1",
        "desktop": {
          "header": {
            "is_visible": true,
            "visible_logo": true,
            "visible_name": true,
            "visible_purchase": true,
            "type": "normal",
            "close_button": false
          }
        }
      }
    },
    "custom_parameters": {
      "character_id": "ingameUsername"
    }
  }'

レスポンス

無料注文が正常に作成されました。

ボディapplication/json
order_idinteger

注文ID。

レスポンス
application/json
{
  "order_id": 641
}

概要

購入制限を使用すると、単一のユーザーまたはすべてのユーザーが購入できるアイテム数量を制限できます。スケジュールされた制限リセットを設定することもできます。

制限はエクソーラ側に保存され、パブリッシャーアカウントで個々のアイテムレベルで設定されるか、以下のAPIコールのlimitsオブジェクトを介して設定されます：

制限情報は、アイテムカタログを取得するための以下のAPIコールでitems.limitsオブジェクトに返されます：

制限グループの管理サブセクションに属するAPIコールにより、制限の現在状態の取得、および指定したユーザーに対する制限値の更新が可能となります（例：クエスト完了時におけるカウンターのリセット、残存数量の手動調整など）。

注意

カタログでの制限設定の詳細については、アイテム購入制限セクションを参照してください。

管理

操作

管理者

操作

先行予約

操作

マーチャント

操作

カタログ

このAPIは販売可能なアイテムや特定のアイテムを取得することができます。

操作

共通地域

地域別の販売制限を使用すると、特定の国または国グループにおけるアイテムの可用性を管理できます。例えば、ライセンスの制約により、特定の国だけでゲームを販売するといったことが可能です。

制限の設定には「地域」を使用します。各地域は、1つ以上の国を単一のregion_idでまとめたものです。アイテムを1つ以上の地域に関連付けることができます。

アイテムの可用性は、以下のように判定されます：

  • アイテムに地域の指定がない場合、すべての国で購入可能です。
  • アイテムに地域が指定されており、ユーザーの国がそのいずれかに含まれている場合、そのユーザーはアイテムを購入できます。
  • アイテムに地域が指定されており、ユーザーの国がどの地域にも含まれていない場合、そのユーザーはアイテムを購入できません。

ユーザーの国は、カタログセクションからのAPIコールを通じてカタログをリクエストする際、countryパラメータとして渡されます。このパラメータが渡されない場合は、ユーザーのIPアドレスに基づいて国が判定されます。

ユーザーの国とアイテムの地域との照合は、カタログのリクエスト時と注文作成時の2回行われます。購入不可のアイテムはカタログのレスポンスには含まれず、そのようなアイテムを含む注文が作成されることはありません。

地域の作成、更新、および削除には、共通地域グループのAPIコールを使用します。

地域別の販売制限のセットアップフロー：

  1. 地域を作成するAPIコールを使用して、対象となる国のリストを指定して地域を作成します。レスポンスには、次のステップで必要となるregion_idが返されます。
  2. アイテムを作成する際、または更新する際に、regions配列にそのregion_idを渡すことで、仮想アイテムを地域に関連付けます。
  3. カタログセクションのAPIコール（例：仮想アイテムリストを取得するAPIコール）を使用して、ユーザーにカタログを表示します。ユーザーの国はcountryパラメータによって決定されます。このパラメータが提供されない場合は、ユーザーのIPアドレスに基づいて判定されます。ユーザーの国で利用不可のアイテムは、カタログの応答には含まれません。
  4. ユーザーがアイテムまたはカートの決済に進む際に、注文を作成します：

レスポンスには、決済UIを開くためのトークンが含まれています。

注意

エクソーラは、ユーザーの国がアイテムに指定された地域に含まれているかを確認します。国がアイテムの地域に含まれていない場合、注文を作成することはできません。

  1. 注文を支払うための決済UIを開く処理を実装します。

Common regions

操作

ウェブフック

操作

管理者

操作

管理者

操作

カタログ

操作