purchase.mp.microsoft.com/v8.0/b2b/recurrences/{recurrenceId}/change
注意
開発サンドボックスを使用している場合、現在、この API はサブスクリプション製品が RETAIL サンドボックスに公開されている場合にのみ機能します。 サブスクリプションが RETAIL に公開されていない場合は、HTTP 400 エラー応答が返され、"要求されたカタログ製品データが見つかりませんでした" というメッセージが表示されます。 これは既知の問題で、今後のリリースで解決される作業項目が含まれています。 それまでは、この API を使用できるようにするには、プライベート フライト グループにサブスクリプションを発行するか、RETAIL で非表示としてサブスクリプションを発行する必要があります。
このエンドポイントは、Microsoft Store でユーザーのサブスクリプション製品の請求状態を変更するために使用されます。 サブスクリプションのキャンセル、延長、払戻を行ったり、自動更新を無効にしたりできます。
Microsoft.StoreServices ライブラリ (GitHub) では、StoreServicesClient.RecurrenceChangeAysnc API によりこのメソッドの機能を提供しています。
前提条件
この API を使用するには、以下が必要になります。
- 対象ユーザーの URI 値
https://onestore.microsoft.comを持つ Microsoft Entra ID アクセス トークン - 付与する無料製品のユーザーの ID を表すユーザー購入 ID キー
詳細については、「サーバー間認証にユーザー Store ID を要求する」を参照してください。
さらに、サービスに表示できるようにする製品には、パートナー センターでの追加の構成が必要です。
製品を適切に構成する方法については、「ユーザー Store ID / Microsoft Entra ID 認証を使用して製品を表示および管理するために必要な追加の構成」を参照してください。
注意
製品の構成がまだ行われておらず、パートナー センター経由で発行された場合、購入サービスの呼び出しは成功しますが、応答に結果は入りません。
要求
要求の構文
| メソッド | 要求 URI |
|---|---|
POST |
purchase.mp.microsoft.com/v8.0/b2b/recurrences/{recurrenceId}/change |
要求ヘッダー
| ヘッダー | 型 | 説明 |
|---|---|---|
Authorization |
string |
必須。
Bearer
<
トークン> という形式の Microsoft Entra ID サービス アクセス トークン。 |
Host |
string |
値 purchase.mp.microsoft.com を設定する必要があります。 |
Content-Length |
number |
要求本文の長さ。 |
Content-Type |
string |
要求と応答の種類を指定します。 現在唯一サポートされている値は application/json です。 |
要求パラメーター
| ヘッダー | 型 | 説明 | 必須かどうか |
|---|---|---|---|
recurrenceId |
string |
ユーザーのサブスクリプションに固有で、purchase.mp.microsoft.com/v8.0/b2b/recurrences/query へのクエリの結果から取得されます。 | はい |
リクエストの本文
| パラメーター | 型 | 説明 | 必須 |
|---|---|---|---|
b2bKey |
string |
要求しているユーザーの ID を表すユーザー購入 ID。 ユーザー ストア ID キーを参照してください。 | はい |
changeType |
string |
行う変更の種類を識別します。 使用可能な変更の種類の値については、次の表を参照してください。 | はい |
extensionTimeInDays |
string |
changeType パラメーターの値が Extend の場合、このパラメーターはサブスクリプションを延長する日数を指定します。 テスト シナリオの場合、この数値を負の値にして、サブスクリプションから日数を削除できます。 | changeType の値が Extend の場合は、はい。それ以外の値の場合は、いいえ。 |
sbx |
string |
結果のスコープを設定するサンドボックスを指定する UserStoreIds で認証するための省略可能な値。 この値のない既定値は RETAIL サンドボックスです。 サンドボックスは X トークン内で指定されているため、X トークン認証ではこの値は必要ありません。 | いいえ |
種類を変更する操作
| 種類を変更する | 説明 |
|---|---|
Cancel |
サブスクリプションをキャンセルします。 |
Extend |
サブスクリプションを延長します。 この値を指定する場合は、要求本文に extensionTimeInDays パラメーターも含める必要があります。 |
Refund |
サブスクリプションを顧客に払い戻します。 |
ToggleAutoRenew |
サブスクリプションの自動更新を無効にします。 現在サブスクリプションの自動更新が無効になっている場合は、この値にすると、何も行われません。 |
要求の例
次の例では、このメソッドを使用してサブスクリプション期間を 5 日だけ延長する方法を示します。 b2bKey の値を、サブスクリプションを変更したいユーザーの ID を表すユーザー 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"
}
応答
このメソッドは、変更されたサブスクリプション アドオンに関する情報 (変更されたフィールドなど) が含まれる JSON 応答本文を返します。 次の例は、このメソッドに関する応答の本文を示しています。
注意
開発サンドボックスを使用している場合、現在、この API はサブスクリプション製品が RETAIL サンドボックスに公開されている場合にのみ機能します。 サブスクリプションが RETAIL に公開されていない場合は、HTTP 400 エラー応答が返され、"要求されたカタログ製品データが見つかりませんでした" というメッセージが表示されます。 これは既知の問題で、今後のリリースで解決される作業項目が含まれています。 それまでは、この API を使用できるようにするには、プライベート フライト グループにサブスクリプションを発行するか、RETAIL で非表示としてサブスクリプションを発行する必要があります。
応答の本文
| パラメーター | 型 | 説明 | 必須 |
|---|---|---|---|
continuationToken |
string |
製品のセットが複数ある場合、ページ制限に達すると、このトークンが返されます。 残りの製品を取得する後続の呼び出しで、この継続トークンを指定できます。 | いいえ |
items |
list<RecurrenceItem> |
指定したユーザーの製品の配列。 詳細については、後の表を参照してください。 | はい |
RecurrenceItem オブジェクトには以下のパラメーターが含まれています。
| パラメーター | 型 | 説明 | 必須 |
|---|---|---|---|
autoRenew |
bool |
次の請求サイクルの終了時にサブスクリプションを自動更新するようにユーザーが登録されているかどうかを示します。 | はい |
beneficiary |
string |
ユーザー購入 ID 内の受益者の発行者 ID。 | はい |
expirationTime |
DateTime |
サブスクリプションの有効期限が切れる、または期限切れになる日時 (UTC) | はい |
expirationTimeWithGrace |
DateTime |
ExpirationTime で自動更新が失敗した場合に、ユーザーの猶予期間が終了する日時 (UTC)。 Grace の間、ユーザーは引き続きアクセスでき、有効なサブスクライバーと見なされますが、自動更新の支払いを修正する必要があることを通知されます。 | はい |
id |
string |
ユーザーが所有する他の項目からこのコレクション項目を識別する ID。 この ID は製品ごとに一意です。 | はい |
isTrial |
bool |
製品がサブスクリプションなどの試用期間内であるかどうかを示します。 | はい |
lastModified |
DateTime |
この項目が最後に更新された日付 (UTC)。 | はい |
market |
string |
製品が購入された国/地域は、2 文字の ISO 3166 国/地域コードに従っています。 例: US。 | はい |
productId |
string |
Microsoft Store カタログ内の製品の場合、Store ID とも呼ばれます。 製品の Store ID の例は、9NBLGGH42CFD です。 | はい |
recurrenceState |
string |
再発の現在の状態です。 「再発の状態」を参照してください。 | はい |
skuId |
string |
Microsoft Store カタログに製品の提供が複数ある場合は、特定の SKU 識別子。 SKU の Store ID の例は、0010 です。 | はい |
startTime |
DateTime |
サブスクリプションが有効になった、または有効になる予定の日付 (UTC)。 | はい |
cancellationDate |
DateTime |
サブスクリプションがキャンセルされた日付 (UTC)。 | いいえ |
再発の状態
| 値 | 説明 |
|---|---|
None |
これは永続的なサブスクリプションを示します。 |
Active |
サブスクリプションは有効であり、ユーザーにはサブスクリプション特典を受け取る資格があります。 |
Inactive |
サブスクリプションは有効期限を過ぎており、ユーザーはこのサブスクリプションの自動更新オプションをオフにしました。 |
Canceled |
サブスクリプションは有効期限の前に意図的に終了され、払戻は行われた場合と行われていない場合があります。 |
InDunning |
サブスクリプションは督促状態にあります (つまり、サブスクリプションの有効期限が近づいているので、Microsoft はサブスクリプションを自動的に更新するための資金を取得しようとしています)。 現在の日付が expirationTimeWithGrace 値より前の場合、ユーザーにはまだサブスクリプション特典を受け取る資格があります。 現在の日付が expirationTimeWithGrace 値より後の場合、ユーザーにはサブスクリプション特典を受け取る資格がありません。 |
Failed |
督促期間が終了し、数回試行しましたがサブスクリプションを更新できませんでした。 |
- 非アクティブ/キャンセル済み/失敗は、最終状態です。 サブスクリプションがこれらのいずれかの状態になった場合、ユーザーがサブスクリプションを再度アクティブ化するには、再購入する必要があります。 ユーザーは、これらの状態にあるサービスを使用する資格はありません。
- サブスクリプションがキャンセルされると、expirationTime はキャンセルの日時で更新されます。
- サブスクリプションの ID は、有効期間全体にわたって同じまま保持されます。 これは、自動更新オプションがオンでもオフでも、変更されません。 最終状態に達した後にユーザーがサブスクリプションを再購入すると、新しいサブスクリプション ID が作成されます。
- 個々のサブスクリプションに対して何かの操作を実行するには、サブスクリプションの ID を使用する必要があります。
- ユーザーがサブスクリプションをキャンセルまたは中止した後にサブスクリプションを再購入した場合、そのユーザーの結果に対してクエリを実行すると、2 つの項目が取得されます。1 つは最終状態の古いサブスクリプション ID を持つ項目、もう 1 つはアクティブ状態の新しいサブスクリプション ID を持つ項目です。
- recurrenceState の更新は数分 (または場合によっては数時間) 遅れる可能性があるため、常に recurrenceState と expirationTime の両方を確認することをお勧めします。
応答の例
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 431
ms-correlationid: 95b2aee4-1118-437b-8910-a2f7d84d0766
ms-cv: Kl684e1htkqb19Ch.0
Date: Thu, 03 Mar 2022 23:19:12 GMT
{
"autoRenew": true,
"beneficiary": "pub:NoUserIdProvided",
"expirationTime": "2022-03-03T23:59:59.00+00:00",
"expirationTimeWithGrace": "2022-03-17T23:59:59.00+00:00",
"id": "mdr:0:3172048a2d1849ba9a24fd305854d4a8:cedca1d3-9580-4229-9cb5-f00c4547078c",
"isTrial": false,
"lastModified": "2022-03-03T23:19:12.26+00:00",
"market": "US",
"productId": "CFQ7TTC0HC8Z",
"skuId": "0003",
"startTime": "2022-03-03T00:00:00.00+00:00",
"recurrenceState": "Active"
}
関連トピック
purchase.mp.microsoft.com/v8.0/b2b/recurrences/query