> ## 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 範例。此範例使用 Microsoft.StoreServices 程式庫來管理驗證，並呼叫 Microsoft Store 服務。範例服務本身包含管理訂閱產品的範例邏輯，並提供設定指南協助您完成設定。

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

## 訂閱產品類型

商店管理的訂閱和附加元件訂閱這兩種產品類型，都可搭配 Recurrence 服務來檢視和管理使用者的訂閱。如需各產品類型的詳細資訊，請參閱[選擇正確的產品類型](/zh-TW/publishing/xstore-commerce/xstore-choosing-product-type#subscriptions)

## 查詢使用者的訂閱

請使用 [purchase.mp.microsoft.com/v8.0/b2b/recurrences/query](/zh-TW/reference/microsoft-store-apis/xstore-v8-recurrence-query) 作為查詢訂閱狀態的主要端點。它會傳回目前有效和歷史的訂閱期間，以及進行變更作業所需的 `subscriptionId`。它也包含區分寬限期 (Grace) 和催繳期 (Dunning) 所需的欄位。

Collections API ([b2bLicensePreview (v8)](/zh-TW/reference/microsoft-store-apis/xstore-v8-query-for-products) 和 [publisherQuery (v9)](/zh-TW/reference/microsoft-store-apis/xstore-v9-query-for-products)) 可以顯示有效的訂閱權利，但無法提供相同的週期性詳細資料。

## 用戶端與伺服器對伺服器之間滿足權利檢查的延遲

當您發佈將新項目 (滿足權利) 加入套件組合的更新時，新項目在用戶端與伺服器對伺服器 API 查詢中的可見性會有延遲。這種延遲的原因是不同的商店系統會以不同的間隔更新其目錄快取。當變更發佈到目錄時，本機授權服務通常會先取得更新的資訊，而 publisherQuery 所使用的快取則會在兩到三小時之後更新。因此，請預期在用戶端 API 授與存取權之後，您的伺服器對伺服器呼叫可能有數小時尚未反映新項目的擁有權。

Recurrence 服務本身不受影響，只有查詢新加入項目之滿足權利的 publisherQuery 或 b2bLicensePreview 端點會受影響。

### 了解訂閱的開始、續訂和到期日期

訂閱的 `StartTime` 日期是有效訂閱開始的日期。如果訂閱設定為自動續訂，開始日期會維持不變，但到期日期會隨著後續月份的續訂而變更。如果訂閱遭到取消、到期或撤銷，使用者再次購買訂閱時，就會建立新的訂閱物件。新的有效訂閱期間的 `StartTime` 是使用者啟用或購買新訂閱的日期。

Microsoft Store 內的訂閱期間通常以月數設定，例如 1 個月、3 個月或 12 個月。當使用者購買一個月的訂閱時，`StartTime` 是使用者開始訂閱當天的 UTC 午夜 (00:00:00)。`ExpirationTime` 是 `StartTime` 加上月數 (而非天數) 再減去一秒 (UTC 23:59:59)。<br />此值的用意是讓訂閱在 UTC 午夜之前到期。

不過，有些月份的天數不同，因此會與從某月 29 日、30 日或 31 日開始的訂閱產生衝突。<br />如果使用者的 `StartTime` 落在這些日期之一，`ExpirationTime` 會修改為到期月份最後一天的 UTC 23:59:59。如此一來，之後的續訂日期一律是每月第一天的 UTC 午夜 (00:00:00)，而 `ExpirationTime` 一律是每月最後一天的 UTC 23:59:59。

#### 一個月訂閱的開始、續訂和到期日期行為範例

| 購買日期 | 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` 時自動續訂付款失敗，訂閱會進入寬限期，若仍未解決則會進入催繳期。這兩個期間回報的狀態都是 `InDunning`，因此請比較目前的 UTC 時間與 `ExpirationTimeWithGrace` 來判斷目前處於哪個期間。

當使用者的訂閱處於寬限期或催繳期時，您應該通知使用者到 [Microsoft 帳戶服務與訂閱](https://account.microsoft.com/services)檢查其帳單狀態。

若要正確地將帳戶設定為上述各狀態以進行測試，請參閱[測試訂閱產品](#testing-subscription-products)。

#### 寬限期

在寬限期間，請在商店重試續訂付款時保持訂閱權益啟用。如果續訂成功，已使用的寬限天數會從下一個期間扣除。如果付款未在 `ExpirationTimeWithGrace` 之前解決，訂閱就會進入催繳期。

#### 催繳期

催繳期在寬限期結束後開始。請在此期間停用訂閱權益。使用者無法在催繳期間重新購買或兌換相同的訂閱。如果在整個催繳期間付款仍未解決，訂閱就會變成非使用中。

### 寬限期和催繳期的長度

| 訂閱類型 | 訂閱長度 | 寬限期 | 催繳期 (寬限期之後) |
| - | - | - | - |
| 附加元件訂閱 | 任何 | 3 天 | 39 天 |
| 商店管理的訂閱 | 任何 | 7 天 | 36 天 |

## 變更使用者的訂閱

您的服務也可以使用 [purchase.mp.microsoft.com/v8.0/b2b/recurrences/](/zh-TW/reference/microsoft-store-apis/xstore-v8-recurrence-change){recurrenceId}[/change](/zh-TW/reference/microsoft-store-apis/xstore-v8-recurrence-change) 來修改訂閱。支援的作業包括新增天數、停用自動續訂，以及取消訂閱。您的服務需要 `recurrenceId` (與 [RecurrenceQuery API](/zh-TW/reference/microsoft-store-apis/xstore-v8-recurrence-query) 中的 `id` 以及 [Collections 查詢 API](/zh-TW/reference/microsoft-store-apis/xstore-v9-query-for-products) 中的 `recurrenceData` 值相同) 才能對使用者的訂閱進行操作。

以下是 Recurrence Change 端點對您的服務可能有用的一些範例：

* 為經歷服務停機的使用者訂閱增加時間。
* 與您的客戶服務支援團隊整合，協助使用者了解其訂閱狀態、取消等資訊。
* 遊戲內 UI，可讓使用者變更自動續訂等設定或結束其訂閱。

## 測試訂閱產品

[Recurrence Change API](/zh-TW/reference/microsoft-store-apis/xstore-v8-recurrence-change) 也可用於測試。`Extend` 接受負數的天數值，讓您將測試訂閱往前推進到目標狀態。

### 測試有效、非使用中和已取消狀態

當您測試訂閱的有效、非使用中和已取消狀態時，可以為訂閱使用 \$0.00 的基本價格。將訂閱新增至測試帳戶以驗證有效狀態，並使用 Recurrence Change 端點停用自動續訂。然後使用 Recurrence Change 端點取消訂閱，或減去足夠的天數，讓 `ExpirationTime` 早於目前的 UTC DateTime。

### 測試寬限期和催繳期狀態

若要測試寬限期和催繳期狀態，訂閱必須有非零的價格。<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 小時)。

若要取得準確的寬限期 -> 催繳期 -> 非使用中行為，請在設定測試後讓帳戶自然推進。

<Note>
  若要讓帳戶正確進入寬限期和催繳期的 'InDunning' 狀態，帳戶必須自然經過 `ExpirationTime` 和 `ExpirationTimeWithGrace` 日期。減去天數時，請將 `ExpirationTime` 設定在未來 24 小時內，然後讓時間自然經過。如果您將 `ExpirationTime` 移至已經過去的時間點，可能不會出現 `InDunning`，且測試狀態可能變成無效。解決此問題的唯一方法是取消訂閱並建立新的測試訂閱。
</Note>

## 另請參閱

[Commerce 概觀](/zh-TW/publishing/xstore-commerce/xstore-commerce-overview)

[Microsoft Store 服務 API](/zh-TW/reference/microsoft-store-apis/index)

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

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




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

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


## Related topics

- [從您的服務管理消耗性產品](/zh-TW/publishing/xstore-commerce/xstore-managing-consumables.md)
- [從您的服務管理退款與退單](/zh-TW/publishing/xstore-commerce/xstore-managing-refunds.md)
- [Microsoft Store v8 訂閱週期變更 API](/zh-TW/reference/microsoft-store-apis/xstore-v8-recurrence-change.md)
- [從您的服務查詢使用者權利](/zh-TW/publishing/xstore-commerce/xstore-query-entitlements.md)
- [collections.mp.microsoft.com/v8.0/collections/consume](/zh-TW/reference/microsoft-store-apis/xstore-v8-consume.md)