> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# サービスからサブスクリプション製品を管理する

> Recurrence サービスを使用してサブスクリプション製品を照会および管理し、ユーザーのさまざまなサブスクリプション状態を処理する方法について説明します。

サブスクリプション製品の場合、バックエンド サービスを使用して状態を検証し、ライフサイクル操作を管理してください。Recurrence API を使用することで、サポートおよびライブ運用チームがサブスクリプションを検査、延長、キャンセルするための信頼できる方法が提供されます。

この記事では、それらのシナリオで Recurrence エンドポイントを使用する方法について説明します。

## Microsoft.StoreServices .NET ライブラリとサンプルの活用

この記事で説明する原則とフローを実演するために、Microsoft.StoreServices Sample を確認してください。このサンプルは、認証を管理し Microsoft Store サービスへの呼び出しを行うために Microsoft.StoreServices ライブラリを使用しています。サンプル サービス自体には、サブスクリプション製品を管理する例のロジックがあり、セットアップに必要な構成ガイドを提供します。

* [Microsoft.StoreServices (GitHub)](https://github.com/microsoft/Microsoft-Store-Services)
* [Microsoft.StoreServices Sample (GitHub)](https://github.com/microsoft/Microsoft-Store-Services-Sample)

## サブスクリプション製品のタイプ

Store 管理およびアドオン サブスクリプションの両方の製品タイプは、Recurrence サービスと連携してユーザーのサブスクリプションを表示および管理できます。これらの各製品タイプの詳細については、[適切な製品タイプを選択する](/publishing/xstore-commerce/xstore-choosing-product-type#subscriptions)を参照してください。

## ユーザーのサブスクリプションの照会

サブスクリプションの状態のプライマリ エンドポイントとして、[purchase.mp.microsoft.com/v8.0/b2b/recurrences/query](/reference/microsoft-store-apis/xstore-v8-recurrence-query) を使用します。これはアクティブおよび履歴のサブスクリプション期間と、変更操作に必要な `subscriptionId` を返します。また、Grace 期間と Dunning 期間を区別するために必要なフィールドも含まれています。

Collections API ([b2bLicensePreview (v8)](/reference/microsoft-store-apis/xstore-v8-query-for-products) および [publisherQuery (v9)](/reference/microsoft-store-apis/xstore-v9-query-for-products)) はアクティブなサブスクリプションのエンタイトルメントを表示できますが、同じ recurrence の詳細は示しません。

## クライアント側とサーバー間で満足するエンタイトルメント チェックの遅延

バンドルに新しいアイテム (満足するエンタイトルメント) を追加する更新を公開すると、クライアントとサーバー間 API クエリの間で新しいアイテムの可視性に遅延があります。この遅延は、異なる Store システムでカタログ キャッシュが異なる間隔で更新されるために発生します。変更がカタログに公開されると、ローカル ライセンス サービスは通常最初に更新情報を取得し、publisherQuery で使用されるキャッシュは 2 \~ 3 時間後になります。したがって、クライアント側 API がアクセスを許可してから、サーバー間呼び出しが新しいアイテムの所有権を反映するまでには数時間かかることを想定してください。

Recurrence サービス自体は影響を受けません。新しく追加されたアイテムに対して満足するエンタイトルメントを照会する publisherQuery または b2bLicensePreview エンドポイントのみが影響を受けます。

### サブスクリプションの開始日、更新日、期限切れ日を理解する

サブスクリプションの `StartTime` は、アクティブなサブスクリプションが開始された日付です。サブスクリプションが自動更新に設定されている場合、開始日は変わりませんが、翌月以降にサブスクリプションが更新されると、期限切れ日が変わります。サブスクリプションがキャンセル、期限切れ、または取り消しになった場合、ユーザーがサブスクリプションを再度購入すると新しいサブスクリプション オブジェクトが作成されます。新しいアクティブなサブスクリプション期間は、ユーザーが新しいサブスクリプションをアクティブ化または購入した日の `StartTime` を持ちます。

Microsoft Store 内のサブスクリプション期間は通常、月単位の数量として構成されます。たとえば、1 か月、3 か月、または 12 か月です。ユーザーが 1 か月のサブスクリプションを購入すると、`StartTime` はサブスクリプションを開始した日の UTC 深夜 (00:00:00) になります。`ExpirationTime` は、`StartTime` に月数 (日数ではない) を追加したものから 1 秒を引いた値 (23:59:59 UTC) になります。<br />この値は、サブスクリプションが UTC 深夜のちょうど前に期限切れになるようにするためのものです。

ただし、月によって日数が異なるため、月の 29 日、30 日、31 日に開始されたサブスクリプションでは競合が発生します。<br />ユーザーの `StartTime` がこれらの日のいずれかに該当する場合、`ExpirationTime` は期限切れとなる月の最終日の 23:59:59 UTC となるように変更されます。この方法により、更新日は常に月初の UTC 深夜 (00:00:00) となり、`ExpirationTime` は常に月末の 23:59:59 UTC となります。

#### 1 か月サブスクリプションの開始日、更新日、期限切れ日の動作例

| 購入日                  | StartTime            | ExpireTime           | 自動更新日                | アクティブ日数   |
| -------------------- | -------------------- | -------------------- | -------------------- | --------- |
| 2023-02-27T12:00:00Z | 2023-02-27T00:00:00Z | 2023-03-26T23:59:59Z | 2023-03-27T00:00:00Z | 28        |
| 2023-03-27T12:00:00Z | 2023-03-27T00:00:00Z | 2023-04-26T23:59:59Z | 2023-05-27T00:00:00Z | 31        |
| 2023-03-29T12:00:00Z | 2023-03-29T00:00:00Z | 2023-04-30T23:59:59Z | 2023-05-01T00:00:00Z | 32        |
| 2023-04-29T12:00:00Z | 2023-04-29T00:00:00Z | 2023-05-31T23:59:59Z | 2023-06-01T00:00:00Z | 33        |
| 2023-04-30T12:00:00Z | 2023-04-30T00:00:00Z | 2023-05-31T23:59:59Z | 2023-06-01T00:00:00Z | 32        |
| 2024-02-27T12:00:00Z | 2024-02-27T00:00:00Z | 2024-03-26T23:59:59Z | 2024-03-27T00:00:00Z | 29 (うるう年) |

### Grace および Dunning 状態を理解する

`ExpirationTime` に自動更新の支払いが失敗した場合、サブスクリプションは Grace に入り、未解決の場合は Dunning に入ります。両方の期間は状態を `InDunning` と報告するため、現在の UTC 時刻を `ExpirationTimeWithGrace` と比較して現在の期間を判断します。

ユーザーのサブスクリプションが Grace または Dunning にある間は、[Microsoft アカウント サービスとサブスクリプション](https://account.microsoft.com/services)で請求状態を確認するようユーザーに通知する必要があります。

これらの各状態にテスト用にアカウントを適切に設定するには、[サブスクリプション製品のテスト](#testing-subscription-products)を参照してください。

#### Grace 期間

Grace 期間中は、Store が更新の支払いを再試行している間、サブスクリプションの特典を有効にしたままにします。更新が成功した場合、使用された Grace の日数は次の期間から差し引かれます。`ExpirationTimeWithGrace` の前に支払いが解決されない場合、サブスクリプションは Dunning に移行します。

#### Dunning 期間

Dunning は Grace の終了後に開始されます。この期間中はサブスクリプションの特典を無効にします。Dunning 中はユーザーは同じサブスクリプションを再購入または引き換えることはできません。Dunning を通して支払いが未解決のままの場合、サブスクリプションは非アクティブになります。

### Grace と Dunning の長さ

| サブスクリプション タイプ      | サブスクリプション期間 | Grace | Dunning (Grace 後) |
| ------------------ | ----------- | ----- | ----------------- |
| アドオン サブスクリプション     | 任意          | 3 日   | 39 日              |
| Store 管理のサブスクリプション | 任意          | 7 日   | 36 日              |

## ユーザーのサブスクリプションの変更

サービスは [purchase.mp.microsoft.com/v8.0/b2b/recurrences/](/reference/microsoft-store-apis/xstore-v8-recurrence-change){recurrenceId}[/change](/reference/microsoft-store-apis/xstore-v8-recurrence-change) を使用してサブスクリプションを変更することもできます。サポートされている操作には、日数の追加、自動更新の無効化、およびサブスクリプションのキャンセルがあります。サービスは、ユーザーのサブスクリプションを操作するために `recurrenceId` ([RecurrenceQuery API](/reference/microsoft-store-apis/xstore-v8-recurrence-query) の `id` と同じ値、および [Collections query API](/reference/microsoft-store-apis/xstore-v9-query-for-products) からの `recurrenceData` 値) が必要です。

Recurrence Change エンドポイントがサービスに役立つ例をいくつか示します。

* サービス停止を経験したユーザーのサブスクリプションに時間を追加する。
* 顧客サービス サポート チームと統合して、サブスクリプション状態やキャンセルなどの情報でユーザーを支援する。
* ユーザーが自動更新などの設定を変更したり、サブスクリプションを終了したりできるようにするゲーム内 UI。

## サブスクリプション製品のテスト

[Recurrence Change API](/reference/microsoft-store-apis/xstore-v8-recurrence-change) はテスト用にも使用できます。`Extend` は負の日数値を受け入れ、テスト サブスクリプションを目的の状態に進めることができます。

### アクティブ、非アクティブ、キャンセル状態のテスト

サブスクリプションのアクティブ、非アクティブ、キャンセル状態をテストする場合、サブスクリプションの基本価格を \$0.00 にできます。テスト アカウントにサブスクリプションを追加してアクティブ状態を確認し、Recurrence Change エンドポイントを使用して自動更新を無効にします。次に、Recurrence Change エンドポイントを使用してサブスクリプションをキャンセルするか、`ExpirationTime` が現在の UTC DateTime を過ぎるように十分な日数を差し引きます。

### Grace および Dunning 状態のテスト

Grace および Dunning 状態をテストするには、サブスクリプションにゼロ以外の価格が必要です。<br />さらに、`ExpirationTime` を過ぎた後の以降の支払いが成功しないようにテスト アカウントを構成する必要があります。現在、Microsoft Store にはテスト用の支払い手段がないため、アカウントを設定する最も簡単な方法は、プリペイド通貨コードを使用することです。

1. \$0.99 などの低価格でテスト環境にサブスクリプションを設定します。
2. 最初のサブスクリプション購入 (税込) を賄うが更新はできない金額として、[XBOX プリペイド ギフト カードを購入](https://www.microsoft.com/en-us/p/xbox-gift-card-digital-code/cfq7ttc0k63h/0002?activetab=pivot:overviewtab)します (\$1.00 または \$2.00)。
3. ギフト カードをテスト アカウントで引き換えます。
4. テスト アカウントでサブスクリプションを購入します。
5. サブスクリプションの自動更新が有効になっているが、サブスクリプションを更新するのに十分な資金がないことを確認します。
6. Recurrence Change を使用してサブスクリプションの `ExpirationTime` を次の 24 時間以内に移動します (以下のメモを参照)。
7. `ExpirationTime` を自然に経過させ、状態が `InDunning` に表示されるのを待ちます (`ExpirationTime` の後に最大 24 時間かかることがあります)。

正確な Grace -> Dunning -> Inactive の動作を得るには、テストを設定した後にアカウントを自然に進行させてください。

<Note>
  Grace および Dunning 期間の「InDunning」状態にアカウントを適切に入れるには、アカウントは自然に `ExpirationTime` および `ExpirationTimeWithGrace` の日付を過ぎる必要があります。日数を差し引くときは、次の 24 時間以内の `ExpirationTime` をターゲットとし、その後時間を自然に経過させてください。`ExpirationTime` を既に過去の時点に移動すると、`InDunning` が表示されず、テスト状態が無効になる場合があります。この問題を解決する唯一の方法は、サブスクリプションをキャンセルして新しいテスト サブスクリプションを作成することです。
</Note>

## 関連項目

[コマースの概要](/publishing/xstore-commerce/xstore-commerce-overview)

[Microsoft Store Service API](/reference/microsoft-store-apis/index)

[purchase.mp.microsoft.com/v8.0/b2b/recurrences/query](/reference/microsoft-store-apis/xstore-v8-recurrence-query)

[purchase.mp.microsoft.com/v8.0/b2b/recurrences/](/reference/microsoft-store-apis/xstore-v8-recurrence-change){recurrenceId}[/change](/reference/microsoft-store-apis/xstore-v8-recurrence-change)

[Microsoft.StoreServices ライブラリ (GitHub)](https://github.com/microsoft/Microsoft-Store-Services)

[Microsoft.StoreServices Sample (GitHub)](https://github.com/microsoft/Microsoft-Store-Services-Sample)


## Related topics

- [サービスから XBOX Game Pass サブスクリプションのアクセスを検出する](/ja-jp/publishing/xstore-commerce/xstore-detecting-game-pass.md)
- [サービスから消費型製品を管理する](/ja-jp/publishing/xstore-commerce/xstore-managing-consumables.md)
- [プレイヤーにアドオン コンテンツへのアクセスを付与する](/ja-jp/publishing/xstore-commerce/xstore-granting-access.md)
- [Microsoft Store サービス API](/ja-jp/reference/microsoft-store-apis/xstore-nav.md)
- [RTA サービスのベスト プラクティス](/ja-jp/services/xbox-services/fundamentals/rta/concepts/live-rta-best-practices.md)