ユーザーのサブスクリプションに関する請求の状態を変更するChange the billing state of a subscription for a user

特定のユーザーのサブスクリプション アドオンの請求状態を変更するには、Microsoft Store 購入 API の以下のメソッドを使います。Use this method in the Microsoft Store purchase API to change the billing state of a subscription add-on for a given user. サブスクリプションのキャンセル、延長、払い戻し、または自動更新の無効化を行えます。You can cancel, extend, refund, or disable automatic renewal for a subscription.

注意

このメソッドは、ユニバーサル Windows プラットフォーム (UWP) アプリ用のサブスクリプション アドオンを作成できるように Microsoft がプロビジョニングした開発者アカウントでのみ使うことができます。This method can only be used by developer accounts that have been provisioned by Microsoft to be able to create subscription add-ons for Universal Windows Platform (UWP) apps. 現在のところ、サブスクリプション アドオンはほとんどの開発者アカウントで使うことができません。Subscription add-ons are currently not available to most developer accounts.

前提条件Prerequisites

このメソッドを使用するための要件:To use this method, you will need:

  • 対象ユーザー URI の値が https://onestore.microsoft.com の Azure AD アクセス トークン。An Azure AD access token that has the audience URI value https://onestore.microsoft.com.
  • 変更対象のサブスクリプションの権利を持つユーザーの ID を表す Microsoft Store ID キー。A Microsoft Store ID key that represents the identity of the user who has an entitlement to the subscription you want to change.

詳しくは、「サービスによる製品の権利の管理」をご覧ください。For more information, see Manage product entitlements from a service.

要求Request

要求の構文Request syntax

メソッドMethod 要求 URIRequest URI
POSTPOST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/{recurrenceId}/change

要求ヘッダーRequest header

HeaderHeader 種類Type 説明Description
AuthorizationAuthorization stringstring 必須。Required. Bearer <トークン> という形式の Azure AD アクセス トークン。The Azure AD access token in the form Bearer <token>.
HostHost stringstring purchase.mp.microsoft.com に設定する必要があります。Must be set to the value purchase.mp.microsoft.com.
Content-LengthContent-Length numbernumber 要求の本文の長さ。The length of the request body.
Content-TypeContent-Type stringstring 要求と応答の種類を指定します。Specifies the request and response type. 現時点では、サポートされている唯一の値は application/json です。Currently, the only supported value is application/json.

要求パラメーターRequest parameters

名前Name 種類Type 説明Description 必須Required
recurrenceIdrecurrenceId stringstring 変更するサブスクリプションの ID。The ID of the subscription you want to change. この ID を取得する呼び出し、ユーザーのサブスクリプションを取得するメソッドを変更するサブスクリプションのアドオンを表す応答本文のエントリを識別およびの値を使用して、 idエントリのフィールド。To get this ID, call the get subscriptions for a user method, identify the response body entry that represents the subscription add-on you want to change, and use the value of the id field for the entry. Yes

要求本文Request body

フィールドField 種類Type 説明Description 必須Required
b2bKeyb2bKey stringstring 変更対象のサブスクリプションを所有するユーザーの ID を表す Microsoft Store ID キーThe Microsoft Store ID key that represents the identity of the user whose subscription you want to change. Yes
changeTypechangeType stringstring 加える変更の種類を識別する次のいずれかの文字列です。One of the following strings that identifies the type of change you want to make:
  • キャンセル:サブスクリプションをキャンセルします。Cancel: Cancels the subscription.
  • 拡張:サブスクリプションを拡張します。Extend: Extends the subscription. この値を指定する場合、extensionTimeInDays パラメーターも含める必要があります。If you specify this value, you must also include the extensionTimeInDays parameter.
  • 返金:サブスクリプションを顧客に返金します。Refund: Refunds the subscription to the customer.
  • ToggleAutoRenew:サブスクリプションの自動更新を無効にします。ToggleAutoRenew: Disables automatic renewal for the subscription. サブスクリプションの自動更新が現在無効になっている場合、この値は何も行いません。If automatic renewal is currently disabled for the subscription, this value does nothing.
Yes
extensionTimeInDaysextensionTimeInDays stringstring changeType パラメーターの値が Extend の場合、このパラメーターはサブスクリプションを延長する日数を指定します。If the changeType parameter has the value Extend, this parameter specifies the number of days to extend the subscription. changeType の値が Extend の場合は必須、それ以外の場合は必須ではありません。Yes, if changeType has the value Extend; otherwise, no.

要求の例Request example

次の例は、このメソッドを使ってサブスクリプション期間を 5 日延長する方法を示しています。The following example demonstrates how to use this method to extend the subscription period by 5 days. b2bKey の値は、変更対象のサブスクリプションを持つユーザーの ID を表す Microsoft Store ID キーに置き換えてください。Replace the b2bKey value with the Microsoft Store ID key that represents the identity of the user whose subscription you want to change.

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 応答本文を返します。This method returns a JSON response body that contains information about the subscription add-on that was modified, including any fields that were modified. このメソッドの応答本文を次の例に示します。The following example demonstrates a response body for this method.

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

応答本文Response body

応答本文には、次のデータが含まれています。The response body contains the following data.

Value 種類Type 説明Description
autoRenewautoRenew ブール値Boolean 現在のサブスクリプション期間の終了時にサブスクリプションが自動的に更新されるように構成されているかどうかを示します。Indicates whether the subscription is configured to automatically renew at the end of the current subscription period.
beneficiarybeneficiary stringstring このサブスクリプションに関連付けられている権利の受益者 ID。The ID of the beneficiary of the entitlement that is associated with this subscription.
expirationTimeexpirationTime stringstring サブスクリプションの有効期限が切れる日時 (ISO 8601形式)。The date and time the subscription will expire, in ISO 8601 format. このフィールドは、サブスクリプションが特定の状態のときのみ利用可能です。This field is only available when the subscription is in certain states. 有効期限は通常、現在の状態の有効期限がいつ切れるかを示します。The expiration time usually indicates when the current state expires. たとえば、アクティブなサブスクリプションの場合、有効期限日は次の自動更新がいつ行われるかを示します。For example, for an active subscription, the expiration date indicates when the next automatic renewal will occur.
expirationTimeWithGraceexpirationTimeWithGrace stringstring 日付と、サブスクリプションから、猶予期間を含む ISO 8601 形式で有効期限が切れる時刻。The date and time the subscription will expire including the grace period, in ISO 8601 format. この値は、ときに、ユーザーがアクセスできなくなります、サブスクリプション、サブスクリプションが自動的に更新が失敗した後を示します。This value indicates when the user will lose access to the subscription after the subscription has failed to automatically renew.
idid stringstring サブスクリプションの ID。The ID of the subscription. ユーザーのサブスクリプションの請求状態を変更するメソッドを呼び出すときに変更するサブスクリプションを指定するには、この値を使います。Use this value to indicate which subscription you want to modify when you call the change the billing state of a subscription for a user method.
isTrialisTrial ブール値Boolean サブスクリプションが試用版であるかどうかを示します。Indicates whether the subscription is a trial.
lastModifiedlastModified stringstring サブスクリプションが前回変更された日時 (ISO 8601形式)。The date and time the subscription was last modified, in ISO 8601 format.
marketmarket stringstring ユーザーがサブスクリプションを取得した国コード (2 文字の ISO 3166-1 alpha-2 形式)。The country code (in two-letter ISO 3166-1 alpha-2 format) in which the user acquired the subscription.
productIdproductId stringstring Microsoft Store カタログ内のサブスクリプション アドオンを表す製品Store IDThe Store ID for the product that represents the subscription add-on in the Microsoft Store catalog. 製品のストア ID の例は、9NBLGGH42CFD です。An example Store ID for a product is 9NBLGGH42CFD.
skuIdskuId stringstring Microsoft Store カタログ内のサブスクリプション アドオンを表す SKUStore IDThe Store ID for the SKU that represents the subscription add-on the Microsoft Store catalog. SKU の Store ID の例は、0010 です。An example Store ID for a SKU is 0010.
startTimestartTime stringstring サブスクリプションの開始日時 (ISO 8601 形式)。The start date and time for the subscription, in ISO 8601 format.
recurrenceStaterecurrenceState stringstring 次のいずれかの値です。One of the following values:
  • None:  永続サブスクリプションを示す。None:  This indicates a perpetual subscription.
  • Active:  サブスクリプションがアクティブであり、ユーザーがサービスを使う権利を持っている。Active:  The subscription is active and the user is entitled to use the services.
  • Inactive:  サブスクリプションの有効期限が過去の日付であり、ユーザーがサブスクリプションの自動更新オプションをオフにした。Inactive:  The subscription is past the expiration date, and the user turned off the automatic renew option for the subscription.
  • Canceled:  サブスクリプションが、有効期限前に意図的に終了された (払い戻しあり、またはなし)。Canceled:  The subscription has been purposefully terminated before the expiration date, with or without a refund.
  • InDunning:  サブスクリプションが催促中である (つまり、サブスクリプションの有効期限が近づいているため、Microsoft がサブスクリプションを自動更新する資金を得ようとしている)。InDunning:  The subscription is in dunning (that is, the subscription is nearing expiration, and Microsoft is trying to acquire funds to automatically renew the subscription).
  • Failed:  催促期間が終了し、何回か試行された後サブスクリプションの更新に失敗した。Failed:  The dunning period is over and the subscription failed to renew after several attempts.

注: Note:

  • Inactive/Canceled/Failed は終了状態です。Inactive/Canceled/Failed are terminal states. サブスクリプションがこれらのいずれかの状態になると、ユーザーはサブスクリプションを再購入してもう一度アクティブ化する必要があります。When a subscription enters one of these states, the user must repurchase the subscription to activate it again. ユーザーは、これらの状態でサービスを使うことはできません。The user is not entitled to use the services in these states.
  • サブスクリプションが Canceled になると、キャンセルの日時によって expirationTime が更新されます。When a subscription is Canceled, the expirationTime will be updated with the date and time of the cancellation.
  • サブスクリプションの ID は、有効期限が終了するまで同じままです。The ID of the subscription will remain the same during its entire lifetime. 自動更新オプションがオンでもオフでも変更されません。It will not change if the auto-renew option is turned on or off. 終了状態に達した後ユーザーがサブスクリプションを再購入した場合、新しいサブスクリプション ID が作成されます。If a user repurchases a subscription after reaching a terminal state, a new subscription ID will be created.
  • サブスクリプションの ID は、個々のサブスクリプションで任意の操作を実行するために使ってください。The ID of a subscription should be used to execute any operation on an individual subscription.
  • ユーザーがサブスクリプションをキャンセルまたは中止した後に再購入した場合、ユーザーの結果を照会すると、終了状態の古いサブスクリプション ID を含むエントリとアクティブ状態の新しいサブスクリプション ID を含むエントリの 2 つが返されます。When a user repurchases a subscription after cancelling or discontinuing it, if you query the results for the user you will get two entries: one with the old subscription ID in a terminal state, and one with the new subscription ID in an active state.
  • 必ず、recurrenceState と expirationTime の両方を確認することをお勧めします。recurrenceState の更新は数分 (場合によって数時間) 遅れることがあるためです。It's always a good practice to check both recurrenceState and expirationTime, since updates to recurrenceState can potentially be delayed by a few minutes (or occasionally hours).
cancellationDatecancellationDate stringstring ユーザーのサブスクリプションがキャンセルされた日時 (ISO 8601 形式)。The date and time the user's subscription was cancelled, in ISO 8601 format.