ユーザーのサブスクリプションに関する請求の状態を変更する

  • [アーティクル]

特定のユーザーのサブスクリプション アドオンの請求状態を変更するには、Microsoft Store 購入 API の以下のメソッドを使います。 サブスクリプションのキャンセル、延長、払い戻し、または自動更新の無効化を行えます。

注意

このメソッドは、ユニバーサル Windows プラットフォーム (UWP) アプリ用のサブスクリプション アドオンを作成できるように Microsoft がプロビジョニングした開発者アカウントでのみ使うことができます。 現在のところ、サブスクリプション アドオンはほとんどの開発者アカウントで使うことができません。

Microsoft.StoreServices ライブラリは、StoreServicesClient.RecurrenceChangeAysnc API を介して、このメソッドの機能を提供します。

前提条件

このメソッドを使用するための要件:

  • 対象ユーザー URI の値が https://onestore.microsoft.com の Azure AD アクセス トークン。
  • 変更対象のサブスクリプションの権利を持つユーザーの ID を表す Microsoft Store ID キー。

詳しくは、「サービスによる製品の権利の管理」をご覧ください。

要求

要求の構文

認証方法 要求 URI
POST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/{recurrenceId}/change

要求ヘッダー

Header 種類 説明
承認 string 必須。 Bearer<トークン> という形式の Azure AD アクセス トークン。
Host string 値 purchase.mp.microsoft.com に設定する必要があります。
Content-Length number 要求本文の長さです。
Content-Type string 要求と応答の種類を指定します。 現時点では、サポートされている唯一の値は application/json です。

要求パラメーター

名前 種類 説明 必須
recurrenceId string 変更するサブスクリプションの ID。 この ID を取得するには、ユーザーのサブスクリプションの取得メソッドを呼び出して、変更するサブスクリプション アドオンを表す応答本文エントリを識別し、エントリの id フィールドの値を使います。 はい

要求本文

フィールド Type 説明 必須
b2bKey string 変更対象のサブスクリプションを所有するユーザーの ID を表す Microsoft Store ID キー。 はい
changeType string 加える変更の種類を識別する次のいずれかの文字列です。
  • Cancel: サブスクリプションをキャンセルします。
  • Extend: サブスクリプションを延長します。 この値を指定する場合、extensionTimeInDays パラメーターも含める必要があります。
  • Refund: サブスクリプションを顧客に払い戻します。
  • ToggleAutoRenew: サブスクリプションの自動更新を無効にします。 サブスクリプションの自動更新が現在無効になっている場合、この値は何も行いません。
 はい
extensionTimeInDays string changeType パラメーターの値が Extend の場合、このパラメーターはサブスクリプションを延長する日数を指定します。 changeType の値が Extend の場合は必須、それ以外の場合は必須ではありません。

要求の例

次の例は、このメソッドを使ってサブスクリプション期間を 5 日延長する方法を示しています。 b2bKey の値は、変更対象のサブスクリプションを持つユーザーの ID を表す Microsoft Store ID キーに置き換えてください。

POST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/mdr:0:bc0cb6960acd4515a0e1d638192d77b7:77d5ebee-0310-4d23-b204-83e8613baaac/change HTTP/1.1
Authorization: Bearer <your access token>
Content-Type: application/json
Host: https://purchase.mp.microsoft.com

{
  "b2bKey":  "eyJ0eXAiOiJ...",
  "changeType": "Extend",
  "extensionTimeInDays": "5"
}

Response

このメソッドは、変更されたすべてのフィールドを含む、変更されたサブスクリプション アドオンに関する情報を含む JSON 応答本文を返します。 このメソッドの応答本文を次の例に示します。

{
  "items": [
    {
      "autoRenew":true,
      "beneficiary":"pub:gFVuEBiZHPXonkYvtdOi+tLE2h4g2Ss0ZId0RQOwzDg=",
      "expirationTime":"2017-06-16T03:07:49.2552941+00:00",
      "id":"mdr:0:bc0cb6960acd4515a0e1d638192d77b7:77d5ebee-0310-4d23-b204-83e8613baaac",
      "lastModified":"2017-01-10T21:08:13.1459644+00:00",
      "market":"US",
      "productId":"9NBLGGH52Q8X",
      "skuId":"0024",
      "startTime":"2017-01-10T21:07:49.2552941+00:00",
      "recurrenceState":"Active"
    }
  ]
}

応答本文

応答本文には、次のデータが含まれています。

値 種類 説明
autoRenew ブール値 現在のサブスクリプション期間の終了時にサブスクリプションが自動的に更新されるように構成されているかどうかを示します。
beneficiary string このサブスクリプションに関連付けられている権利の受益者 ID。
expirationTime string サブスクリプションの有効期限が切れる日時 (ISO 8601形式)。 このフィールドは、サブスクリプションが特定の状態のときのみ利用可能です。 有効期限は通常、現在の状態の有効期限がいつ切れるかを示します。 たとえば、アクティブなサブスクリプションの場合、有効期限日は次の自動更新がいつ行われるかを示します。
expirationTimeWithGrace string サブスクリプションの有効期限が切れる日時です (ISO 8601 形式、猶予期間を含みます)。 この値は、サブスクリプションが自動的に更新されなくなった後に、ユーザーがサブスクリプションへのアクセス権を失う日時を示します。
id string サブスクリプションの ID です。 ユーザーのサブスクリプションの請求状態を変更するメソッドを呼び出すときに変更するサブスクリプションを指定するには、この値を使います。
isTrial Boolean サブスクリプションが試用版であるかどうかを示します。
lastModified string サブスクリプションが前回変更された日時 (ISO 8601形式)。
market string ユーザーがサブスクリプションを取得した国コード (2 文字の ISO 3166-1 alpha-2 形式)。
productId string Microsoft Store カタログ内のサブスクリプション アドオンを表す製品の Store ID。 製品のストア ID の例は、9NBLGGH42CFD です。
skuId string Microsoft Store カタログ内のサブスクリプション アドオンを表す SKU の Store ID。 SKU の Store ID の例は、0010 です。
startTime string サブスクリプションの開始日時 (ISO 8601 形式)。
recurrenceState string 次のいずれかの値です。
  • None: 永続サブスクリプションを示す。
  • Active: サブスクリプションがアクティブであり、ユーザーがサービスを使う権利を持っている。
  • Inactive: サブスクリプションの有効期限が過去の日付であり、ユーザーがサブスクリプションの自動更新オプションをオフにした。
  • Canceled: サブスクリプションが、有効期限日の前に意図的に終了された (払い戻しの有無にかかわらず)。
  • InDunning: サブスクリプションが "督促中" である (つまり、サブスクリプションの有効期限が近付いており、Microsoft が、サブスクリプションを自動的に更新するための資金を獲得しようとしている)。
  • Failed: 催促期間が終了し、サブスクリプションの更新が、数回の試行の後に失敗した。

注:

  • Inactive/Canceled/Failed は終了状態です。 サブスクリプションがこれらのいずれかの状態になると、ユーザーはサブスクリプションを再購入してもう一度アクティブ化する必要があります。 ユーザーは、これらの状態でサービスを使うことはできません。
  • サブスクリプションが Canceled になると、キャンセルの日時によって expirationTime が更新されます。
  • サブスクリプションの ID は、有効期限が終了するまで同じままです。 自動更新オプションがオンでもオフでも変更されません。 終了状態に達した後ユーザーがサブスクリプションを再購入した場合、新しいサブスクリプション ID が作成されます。
  • サブスクリプションの ID は、個々のサブスクリプションで任意の操作を実行するために使ってください。
  • ユーザーがサブスクリプションをキャンセルまたは中止した後に再購入した場合、ユーザーの結果を照会すると、終了状態の古いサブスクリプション ID を含むエントリとアクティブ状態の新しいサブスクリプション ID を含むエントリの 2 つが返されます。
  • 必ず、recurrenceState と expirationTime の両方を確認することをお勧めします。recurrenceState の更新は数分 (場合によって数時間) 遅れることがあるためです。
cancellationDate string ユーザーのサブスクリプションがキャンセルされた日時 (ISO 8601 形式)。