コンテンツへスキップ

Subscriptions API (2.0)

概要

  • Version: 2.0
  • Servers: https://api.xsolla.com/merchant/v2/

このAPIリファレンスでは、サブスクリプション、クーポン、およびプロモーションを管理するためのエンドポイントについて説明します。 サブスクリプションの詳細については、製品ガイドおよび用語集を参照してください。

OpenAPI記述をダウンロード
言語
サーバー
Mock server
https://xsolla.redocly.app/_mock/ja/api/subscriptions/
操作
操作
操作

Subscription management

操作

サブスクリプションの一覧

リクエスト

すべての定期サブスクリプションを一覧表示します。

通知

この API メソッドは高負荷時には使用できません。最大負荷は 1 分あたり 20 リクエストです。

通知

APIコールにproject_idパスパラメータが含まれていないため、会社の全プロジェクトで有効なAPIキーを使用して認可を設定する必要があります。

セキュリティ
basicAuth
パス
merchant_idinteger必須

マーチャントID。

クエリ
offsetinteger

リスト生成元のエレメントの番号です(カウントは0から始まります)。

limitinteger必須

ページにあるエレメント数の制限。

user_idstring

ユーザーID。

project_id[]Array of integers

プロジェクトIDのリスト。

plan_id[]Array of integers

サブスクリプションプランIDのリスト。

product_id[]Array of integers

プランがリンクされている製品IDのリスト。

group_id[]Array of strings

プランがリンクされているグループIDのリスト。

status[]Array of strings

ステータス。

アイテム 列挙型"active""canceled""non_renewing"
datetime_fromstring(datetime)

サンプル日付。リクエストよりも後に作成されたサブスクリプションを見つけるのに役立ちます。

datetime_tostring(datetime)

サンプル日付。リクエストよりも後に作成されたサブスクリプションを見つけるのに役立ちます。

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

レスポンス

OK。

ボディapplication/jsonArray [
charge_amountnumber(float)

請求額。

commentstring

サブスクリプション状態を変更する理由

currencystring

購入通貨。ISO 4217に基づく3文字の通貨コード。

date_createstring(datetime)

ISO 8601に基づくYYYY-MM-DD’T’HH:MM:SSフォーマットのサブスクリプション作成日。

date_endstring(datetime)

ISO 8601に基づくYYYY-MM-DD’T’HH:MM:SSフォーマットのサブスクリプション終了日。

date_last_chargestring or null(datetime)

ISO 8601に基づくYYYY-MM-DD’T’HH:MM:SSフォーマットのサブスクリプション最終請求日。

date_next_chargestring or null(datetime)

ISO 8601に基づくYYYY-MM-DD’T’HH:MM:SSフォーマットの次回のサブスクリプション請求日。

idinteger

サブスクリプションID

planobject
plan.​billing_retryobject

請求再試行の詳細。

plan.​billing_retry.​valueinteger必須

請求の再試行回数。

plan.​chargeobject

請求の詳細。

plan.​charge.​amountnumber(float)

請求額。

plan.​charge.​currencystring

購入通貨。ISO 4217に準拠した3文字の通貨コード。

plan.​charge.​periodobject必須

請求期間。

plan.​charge.​period.​typestring必須

時間の単位。daymonthまたはlifetimeにすることができます。

列挙型"day""month""lifetime"
plan.​charge.​period.​valueinteger必須

時間単位の数。値はタイプパラメータに依存し、次のようになります:
-typedayの場合 、1から366まで
-typemonthの場合、1から12まで、
-typelifetimeの場合、0です

plan.​charge.​pricesArray of objects

異なる通貨での価格を一覧表示します。

plan.​charge.​prices[].​amountnumber(float)必須

請求額。

plan.​charge.​prices[].​currencystring必須

購入通貨。ISO 4217に準拠した3文字の通貨コード。

plan.​charge.​prices[].​setup_feenumber(float)

最初の請求書の一部として請求される1回のセットアップ費用。

plan.​descriptionobject

プランの説明文。"localization":"plan description"のペアで構成されます。

plan.​description.​arstring

アラビア語。

plan.​description.​bgstring

ブルガリア語。

plan.​description.​cnstring

中国語(簡体字)。

plan.​description.​csstring

チェコ語。

plan.​description.​destring

ドイツ語。

plan.​description.​enstring

英語。

plan.​description.​esstring

スペイン語。

plan.​description.​frstring

フランス語。

plan.​description.​hestring

ヘブライ語。

plan.​description.​itstring

イタリア語。

plan.​description.​jastring

日本語。

plan.​description.​kostring

韓国語。

plan.​description.​plstring

ポーランド語。

plan.​description.​ptstring

ポルトガル語。

plan.​description.​rostring

ルーマニア語。

plan.​description.​rustring

ロシア語。

plan.​description.​thstring

タイ語。

plan.​description.​trstring

トルコ語。

plan.​description.​twstring

中国語(繁体字)。

plan.​description.​vistring

ベトナム語。

plan.​expirationobject

サブスクリプションの有効期限の詳細。

plan.​expiration.​typestring必須

時間の単位。dayまたはmonthにすることができます。

列挙型"day""month"
plan.​expiration.​valueinteger or null必須

有効期間。

plan.​external_idstring

プラン外部ID(32文字)。

plan.​grace_periodobject

猶予期間の詳細。

plan.​grace_period.​typestring必須

時間の単位。dayにすることができます。

"day"
plan.​grace_period.​valueinteger必須

時間単位の数。

plan.​group_idstring or null

プランがリンクされているグループID。

plan.​idinteger

サブスクリプションプラン ID。

plan.​nameobject

プラン名。"localization":"plan name"のペアで構成されます。

plan.​name.​arstring

アラビア語。

plan.​name.​bgstring

ブルガリア語。

plan.​name.​cnstring

中国語(簡体字)。

plan.​name.​csstring

チェコ語。

plan.​name.​destring

ドイツ語。

plan.​name.​enstring

英語。

plan.​name.​esstring

スペイン語。

plan.​name.​frstring

フランス語。

plan.​name.​hestring

ヘブライ語。

plan.​name.​itstring

イタリア語。

plan.​name.​jastring

日本語。

plan.​name.​kostring

韓国語。

plan.​name.​plstring

ポーランド語。

plan.​name.​ptstring

ポルトガル語。

plan.​name.​rostring

ルーマニア語。

plan.​name.​rustring

ロシア語。

plan.​name.​thstring

タイ語。

plan.​name.​trstring

トルコ語。

plan.​name.​twstring

中国語(繁体字)。

plan.​name.​vistring

ベトナム語。

plan.​project_idinteger

プロジェクトID。

plan.​refund_periodinteger or null

ユーザーがサブスクリプションプランの支払いを返金できる期間(日単位)。

plan.​statusobject
plan.​status.​valuestring

サブスクリプションプランのステータス

列挙型"active""disabled"
plan.​tagsArray of strings

プランのタグ。

plan.​trialobject

試用期間の詳細。

plan.​trial.​typestring必須

時間の単位。dayにすることができます。

"day"
plan.​trial.​valueinteger必須

時間単位の数。

productobject or null
product.​idinteger or null

プランがリンクされている製品のID。

product.​descriptionobject

ローカライズされたアイテムの説明。

product.​description.​arstring

アラビア語。

product.​description.​bgstring

ブルガリア語。

product.​description.​cnstring

中国語(簡体字)。

product.​description.​csstring

チェコ語。

product.​description.​destring

ドイツ語。

product.​description.​enstring

英語。

product.​description.​esstring

スペイン語。

product.​description.​frstring

フランス語。

product.​description.​hestring

ヘブライ語。

product.​description.​itstring

イタリア語。

product.​description.​jastring

日本語。

product.​description.​kostring

韓国語。

product.​description.​plstring

ポーランド語。

product.​description.​ptstring

ポルトガル語。

product.​description.​rostring

ルーマニア語。

product.​description.​rustring

ロシア語。

product.​description.​thstring

タイ語。

product.​description.​trstring

トルコ語。

product.​description.​twstring

中国語(繁体字)。

product.​description.​vistring

ベトナム語。

product.​group_idstring

製品がリンクされているグループID。

product.​namestring

製品名。

statusstring

状態

列挙型"new""active""canceled""non_renewing""freeze"
userobject
user.​idstring

ユーザーID

user.​namestring

ユーザー名

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

リクエスト

IDで特定のサブスクリプションの詳細を取得。

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

プロジェクトID。

subscription_idinteger必須

サブスクリプションID。

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

レスポンス

OK。

ボディapplication/json
charge_amountnumber(float)

請求額。

commentstring

サブスクリプション状態を変更する理由

currencystring

購入通貨。ISO 4217に基づく3文字の通貨コード。

date_createstring(datetime)

ISO 8601に基づくYYYY-MM-DD’T’HH:MM:SSフォーマットのサブスクリプション作成日。

date_endstring(datetime)

ISO 8601に基づくYYYY-MM-DD’T’HH:MM:SSフォーマットのサブスクリプション終了日。

date_last_chargestring or null(datetime)

ISO 8601に基づくYYYY-MM-DD’T’HH:MM:SSフォーマットのサブスクリプション最終請求日。

date_next_chargestring or null(datetime)

ISO 8601に基づくYYYY-MM-DD’T’HH:MM:SSフォーマットの次回のサブスクリプション請求日。

idinteger

サブスクリプションID

planobject
plan.​billing_retryobject

請求再試行の詳細。

plan.​billing_retry.​valueinteger必須

請求の再試行回数。

plan.​chargeobject

請求の詳細。

plan.​charge.​amountnumber(float)

請求額。

plan.​charge.​currencystring

購入通貨。ISO 4217に準拠した3文字の通貨コード。

plan.​charge.​periodobject必須

請求期間。

plan.​charge.​period.​typestring必須

時間の単位。daymonthまたはlifetimeにすることができます。

列挙型"day""month""lifetime"
plan.​charge.​period.​valueinteger必須

時間単位の数。値はタイプパラメータに依存し、次のようになります:
-typedayの場合 、1から366まで
-typemonthの場合、1から12まで、
-typelifetimeの場合、0です

plan.​charge.​pricesArray of objects

異なる通貨での価格を一覧表示します。

plan.​charge.​prices[].​amountnumber(float)必須

請求額。

plan.​charge.​prices[].​currencystring必須

購入通貨。ISO 4217に準拠した3文字の通貨コード。

plan.​charge.​prices[].​setup_feenumber(float)

最初の請求書の一部として請求される1回のセットアップ費用。

plan.​descriptionobject

プランの説明文。"localization":"plan description"のペアで構成されます。

plan.​description.​arstring

アラビア語。

plan.​description.​bgstring

ブルガリア語。

plan.​description.​cnstring

中国語(簡体字)。

plan.​description.​csstring

チェコ語。

plan.​description.​destring

ドイツ語。

plan.​description.​enstring

英語。

plan.​description.​esstring

スペイン語。

plan.​description.​frstring

フランス語。

plan.​description.​hestring

ヘブライ語。

plan.​description.​itstring

イタリア語。

plan.​description.​jastring

日本語。

plan.​description.​kostring

韓国語。

plan.​description.​plstring

ポーランド語。

plan.​description.​ptstring

ポルトガル語。

plan.​description.​rostring

ルーマニア語。

plan.​description.​rustring

ロシア語。

plan.​description.​thstring

タイ語。

plan.​description.​trstring

トルコ語。

plan.​description.​twstring

中国語(繁体字)。

plan.​description.​vistring

ベトナム語。

plan.​expirationobject

サブスクリプションの有効期限の詳細。

plan.​expiration.​typestring必須

時間の単位。dayまたはmonthにすることができます。

列挙型"day""month"
plan.​expiration.​valueinteger or null必須

有効期間。

plan.​external_idstring

プラン外部ID(32文字)。

plan.​grace_periodobject

猶予期間の詳細。

plan.​grace_period.​typestring必須

時間の単位。dayにすることができます。

"day"
plan.​grace_period.​valueinteger必須

時間単位の数。

plan.​group_idstring or null

プランがリンクされているグループID。

plan.​idinteger

サブスクリプションプラン ID。

plan.​nameobject

プラン名。"localization":"plan name"のペアで構成されます。

plan.​name.​arstring

アラビア語。

plan.​name.​bgstring

ブルガリア語。

plan.​name.​cnstring

中国語(簡体字)。

plan.​name.​csstring

チェコ語。

plan.​name.​destring

ドイツ語。

plan.​name.​enstring

英語。

plan.​name.​esstring

スペイン語。

plan.​name.​frstring

フランス語。

plan.​name.​hestring

ヘブライ語。

plan.​name.​itstring

イタリア語。

plan.​name.​jastring

日本語。

plan.​name.​kostring

韓国語。

plan.​name.​plstring

ポーランド語。

plan.​name.​ptstring

ポルトガル語。

plan.​name.​rostring

ルーマニア語。

plan.​name.​rustring

ロシア語。

plan.​name.​thstring

タイ語。

plan.​name.​trstring

トルコ語。

plan.​name.​twstring

中国語(繁体字)。

plan.​name.​vistring

ベトナム語。

plan.​project_idinteger

プロジェクトID。

plan.​refund_periodinteger or null

ユーザーがサブスクリプションプランの支払いを返金できる期間(日単位)。

plan.​statusobject
plan.​status.​valuestring

サブスクリプションプランのステータス

列挙型"active""disabled"
plan.​tagsArray of strings

プランのタグ。

plan.​trialobject

試用期間の詳細。

plan.​trial.​typestring必須

時間の単位。dayにすることができます。

"day"
plan.​trial.​valueinteger必須

時間単位の数。

productobject or null
product.​idinteger or null

プランがリンクされている製品のID。

product.​descriptionobject

ローカライズされたアイテムの説明。

product.​description.​arstring

アラビア語。

product.​description.​bgstring

ブルガリア語。

product.​description.​cnstring

中国語(簡体字)。

product.​description.​csstring

チェコ語。

product.​description.​destring

ドイツ語。

product.​description.​enstring

英語。

product.​description.​esstring

スペイン語。

product.​description.​frstring

フランス語。

product.​description.​hestring

ヘブライ語。

product.​description.​itstring

イタリア語。

product.​description.​jastring

日本語。

product.​description.​kostring

韓国語。

product.​description.​plstring

ポーランド語。

product.​description.​ptstring

ポルトガル語。

product.​description.​rostring

ルーマニア語。

product.​description.​rustring

ロシア語。

product.​description.​thstring

タイ語。

product.​description.​trstring

トルコ語。

product.​description.​twstring

中国語(繁体字)。

product.​description.​vistring

ベトナム語。

product.​group_idstring

製品がリンクされているグループID。

product.​namestring

製品名。

statusstring

状態

列挙型"new""active""canceled""non_renewing""freeze"
userobject
user.​idstring

ユーザーID

user.​namestring

ユーザー名

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

サブスクリプションの更新

リクエスト

ステータスを変更(activecanceled、またはnon_renewing)したり、次の請求日を延期することによって、サブスクリプションを更新します。

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

プロジェクトID。

user_idstring必須

ユーザーID。

subscription_idinteger必須

サブスクリプションID。

ボディapplication/json必須
cancel_subscription_paymentboolean

trueに設定すると、このサブスクリプションで最後に支払った決済分が払い戻されます。canceledに設定したステータスと共にのみ実行できます

statusstring

ステータス。

列挙型"active""canceled""non_renewing"
timeshiftobject

請求の延期。

timeshift.​typestring

請求時間の単位。dayまたはmonthにすることができます。

列挙型"day""month"
timeshift.​valuestring

課金を延期する時間単位の数。値はタイプパラメータに依存し、次のようになります:
-typedayの場合 、1から366まで
-typemonthの場合、1から12までです

xsolla_networkobject
xsolla_network.​collaborator_idstring

コラボレーター ID — インフルエンサーまたはアフィリエイトネットワーク識別子。あなたのアドミンページ>パートナーネットワーク>インフルエンサーセクションで見つけることができます。

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

レスポンス

OK。

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

プロモーション

操作
操作

Subscription management

操作