> ## 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.

# Microsoft Store v8 訂閱週期變更 API

> Microsoft Store v8 週期變更端點，可讓遊戲服務依週期 ID 取消、延長或退款使用者的訂閱週期。

<Note>
  此 API 只有在訂閱已發佈至 RETAIL 時才能運作。如果使用開發沙箱，請先將訂閱發佈至私人測試群組，或在 RETAIL 中以隱藏方式發佈，再呼叫此 API。如果訂閱未發佈至 RETAIL，回應會是 HTTP 400 錯誤，訊息會指出「Requested catalog product data wasn't found.」
</Note>

此端點用於變更使用者在 Microsoft Store 中訂閱產品的計費狀態。
您可以取消、延長、退款訂閱，或停用訂閱的自動續訂。

[Microsoft.StoreServices 程式庫 (GitHub)](https://github.com/microsoft/Microsoft-Store-Services) 透過 StoreServicesClient.RecurrenceChangeAsync API 提供此方法的功能。

## 必要條件

請檢閱[服務對服務 API 的必要條件](https://learn.microsoft.com/reference/service-to-service-nav#prerequisites-for-service-to-service-apis)。

此 API 僅支援 Microsoft Entra ID 驗證類型。

如果產品設定未在 Partner Center 中發佈，呼叫可能會成功，但不會傳回任何結果。

## 要求

### 要求語法

| 方法 | 要求 URI |
| - | - |
| `POST` | `purchase.mp.microsoft.com/v8.0/b2b/recurrences/{recurrenceId}/change` |

### 要求標頭

| 標頭 | 類型 | 描述 |
| - | - | - |
| `Authorization` | `string` | 必要。Microsoft Entra ID 服務存取權杖，格式為 `Bearer` \<*token*>。 |
| `Host` | `string` | 必須設定為值 `purchase.mp.microsoft.com`。 |
| `Content-Length` | `number` | 要求本文的長度。 |
| `Content-Type` | `string` | 指定要求和回應類型。目前唯一支援的值是 `application/json`。 |

### 要求參數

| 標頭 | 類型 | 描述 | 必要 |
| - | - | - | - |
| `recurrenceId` | `string` | 對使用者的訂閱而言是唯一的，且與 [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` 為相同的值。 | 是 |

### 要求本文

| 參數 | 類型 | 描述 | 必要 |
| - | - | - | - |
| `b2bKey` | `string` | 代表您所要求之使用者身分識別的 User Purchase ID。請參閱 [User Store ID 金鑰](https://learn.microsoft.com/reference/xstore-requesting-a-userstoreid#step-4-create-a-user-store-id-key)。 | 是 |
| `changeType` | `string` | 識別您要進行的變更類型。如需可能的值，請參閱[變更類型作業](#change-type-operations)表格。 | 是 |
| `extensionTimeInDays` | `string` | 如果 changeType 參數的值為 Extend，此參數會指定要延長訂閱的天數。在測試案例中，此數字可以是負數，以從訂閱中移除天數。 | 如果 changeType 的值為 *Extend*，則為是；否則為否。 |
| `sbx` | `string` | 使用 UserStoreIds 驗證時的選用值，指定結果應限定的 Sandbox。若無此值，預設為 RETAIL 沙箱。X-Token 驗證不需要此值，因為 Sandbox 已在 X-Token 內指定。 | 否 |

### 變更類型作業

| 變更類型 | 描述 |
| - | - |
| `Cancel` | 取消訂閱。 |
| `Extend` | 延長訂閱。如果您指定此值，也必須在要求本文中包含 `extensionTimeInDays` 參數。 |
| `Refund` | 將訂閱退款給客戶。 |
| `ToggleAutoRenew` | 停用訂閱的自動續訂。如果訂閱的自動續訂目前已停用，此值不會有任何作用。 |

### 要求範例

下列範例示範如何使用此方法將訂閱期間延長五天。請將 b2bKey 值取代為代表您要變更其訂閱之使用者身分識別的 User Store ID 金鑰。

```html theme={null}
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 回應本文，描述已更新的訂閱附加元件，包括已修改的欄位。

<Note>
  此方法具有與本文開頭所述相同的 RETAIL 發佈需求。
</Note>

### 回應本文

| 參數 | 類型 | 描述 | 必要 |
| - | - | - | - |
| `continuationToken` | `string` | 如果有多組產品，當達到頁面限制時，就會傳回此權杖。您可以在後續呼叫中指定此接續權杖，以擷取其餘產品。 | 否 |
| `items` | `list<RecurrenceItem>` | 指定使用者的產品陣列。如需詳細資訊，請參閱下表。 | 是 |

`RecurrenceItem` 物件包含下列參數。

| 參數 | 類型 | 描述 | 必要 |
| - | - | - | - |
| `autoRenew` | `bool` | 表示使用者是否已註冊在下一個計費週期結束時自動續訂其訂閱。 | 是 |
| `beneficiary` | `string` | User Purchase ID 中受益人的 Publisher ID。 | 是 |
| `expirationTime` | `DateTime` | 訂閱到期的 UTC 日期和時間。 | 是 |
| `expirationTimeWithGrace` | `DateTime` | 如果在 ExpirationTime 自動續訂失敗，使用者寬限期結束的 UTC 日期和時間。在寬限期間，使用者仍應具有存取權並被視為有效的訂閱者，但應通知他們需要修正自動續訂付款。 | 是 |
| `id` | `string` | 用來區分此集合項目與使用者擁有之其他項目的 ID。此 ID 對每個產品都是唯一的。 | 是 |
| `isTrial` | `bool` | 表示產品是否處於試用期間，例如訂閱。 | 是 |
| `lastModified` | `DateTime` | 此項目上次修改的 UTC 日期。 | 是 |
| `market` | `string` | 購買產品的國家/地區，採用兩個字元的 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` | 催收期間已結束，且訂閱在多次嘗試後仍無法續訂。 |

* *Inactive/Canceled/Failed* 是終止狀態。當訂閱進入其中一種狀態時，使用者必須重新購買訂閱才能再次啟用。使用者在這些狀態下無權使用服務。
* 當訂閱為 Canceled 時，`expirationTime` 會更新為取消的日期和時間。
* 訂閱的 ID 在其整個存留期間都保持不變。開啟或關閉自動續訂選項時，ID 不會變更。如果使用者在到達終止狀態後重新購買訂閱，將會建立新的訂閱 ID。
* 應使用訂閱的 ID 來對個別訂閱執行任何作業。
* 當使用者在取消或停止訂閱後重新購買時，如果您查詢該使用者的結果，將會得到兩個項目：一個是處於終止狀態的舊訂閱 ID，另一個是處於作用中狀態的新訂閱 ID。
* 最好一律同時檢查 recurrenceState 和 `expirationTime`，因為 `recurrenceState` 的更新可能會延遲幾分鐘 (偶爾會延遲數小時)。

### 回應範例

```json theme={null}
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](/zh-TW/reference/microsoft-store-apis/xstore-v8-recurrence-query)

[從您的服務管理產品](https://learn.microsoft.com/reference/service-to-service-nav)

[從您的服務管理退款和退單](https://learn.microsoft.com/reference/xstore-managing-refunds-and-chargebacks)

[使用 Microsoft Store API 驗證您的服務](https://learn.microsoft.com/reference/xstore-authenticating-your-service)

[使用 publisherQuery (Collections v9) 查詢使用者的產品和權利](/zh-TW/reference/microsoft-store-apis/xstore-v9-query-for-products)


## Related topics

- [帳戶方案升級](/zh-TW/services/playfab/pricing/account-upgrades.md)
- [Microsoft Store v8 subscription recurrence change API](/reference/microsoft-store-apis/xstore-v8-recurrence-change.md)
- [Microsoft Store v8 Collections b2bLicensePreview API](/reference/microsoft-store-apis/xstore-v8-query-for-products.md)
- [Microsoft Store service APIs](/reference/microsoft-store-apis/xstore-nav.md)
- [API b2bLicensePreview de Collections v8 de Microsoft Store](/es/reference/microsoft-store-apis/xstore-v8-query-for-products.md)