Microsoft Marketplace 中的 SaaS 履行訂用帳戶 API v2

本文說明 SaaS 履行訂用帳戶 API 第 2 版。

Note

要呼叫 SaaS 履行訂閱 API，請使用正確的資源 ID 建立發佈者授權憑證。欲了解更多資訊，請參閱取得出版商授權令牌。

Note

對於 CSP 購買的訂閱，允許的操作僅限於讀取，因為受益人在此流程中無法更新或刪除訂閱。其他所有購買項目，所有操作[閱讀、更新、刪除]皆被允許。

解決已購買的訂用帳戶

Resolve 端點允許發佈者將 Microsoft Marketplace 的購買識別令牌（在已購買中稱為 token但尚未啟用）交換為持續購買的 SaaS 訂閱 ID 及其詳細資訊。

Note

啟用自動啟用的計畫則不需要 Resolve API。 Microsoft 會透過 Subscribe webhook 通知，直接將訂閱詳情傳送給出版商。

當客戶重新導向至合作夥伴的登陸頁面 URL 時，客戶識別令牌會傳遞為此 URL 呼叫中的令牌參數。合作夥伴利用此令牌提出解決請求。解析 API 回應包含 SaaS 訂用帳戶標識碼和其他詳細數據，可唯一識別購買。登陸頁面 URL 呼叫所提供的令牌有效期為 24 小時。如果您收到的代幣已過期，請向最終使用者提供以下指引：

“我們無法識別此購買。請在 Azure 入口網站或 Microsoft 365 系統管理 Center 重新開啟此 SaaS 訂閱，並再次選擇設定帳戶或管理帳戶。」

呼叫解析 API 會傳回所有支持狀態中 SaaS 訂用帳戶的訂用帳戶詳細數據和狀態。

張貼 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<api-version>`

查詢參數：

Parameter	Value
`api-version`	使用 2018-08-31。

請求標頭：

Parameter	Value
`content-type`	`application/json`
`x-ms-requestid`	從客戶端追蹤要求的唯一字串值，最好是 GUID。如果你沒有提供這個值，回應標頭會包含一個產生的值。
`x-ms-correlationid`	用戶端上作業的唯一字串值。此參數會將來自用戶端作業的所有事件與伺服器端上的事件相互關聯。如果你沒有提供這個值，回應標頭會包含一個產生的值。
`authorization`	識別發出此 API 呼叫之發行者的唯一存取令牌。當發行者擷取令牌值時，格式會 `"Bearer <access_token>"`，如根據 Microsoft Entra 應用程式取得令牌中所述，。
`x-ms-marketplace-token`	要解析的購買識別令牌參數。當客戶重新導向至 SaaS 合作夥伴的網站時，令牌會在登陸頁面 URL 呼叫中傳遞（例如：`https://contoso.com/signup?token=<token><authorization_token>`）。要編碼的令牌值是登陸頁面 URL 的一部分，因此必須先譯碼，才能在此 API 呼叫中當做參數使用。以下是 URL 中編碼字串的範例：`contoso.com/signup?token=ab%2Bcd%2Fef`，其中令牌`ab%2Bcd%2Fef`。相同的權譯碼為：`Ab+cd/ef`。

回應碼：

程序代碼：200 根據所提供的 x-ms-marketplace-token 傳回唯一的 SaaS 訂用帳戶標識碼。

回應本文範例：

{
  "id": "<guid>", // purchased SaaS subscription ID
  "subscriptionName": "Contoso Cloud Solution", // SaaS subscription name
  "offerId": "offer1", // purchased offer ID
  "planId": "silver", // purchased offer's plan ID
  "quantity": 20, // number of purchased licenses, might be empty if the plan is not per seat
  "subscription": { // full SaaS subscription details, see Get Subscription APIs response body for full description
    "id": "<guid>",
    "publisherId": "contoso",
    "offerId": "offer1",
    "name": "Contoso Cloud Solution",
    "saasSubscriptionStatus": " PendingFulfillmentStart ",
    "beneficiary": {
      "emailId": "test@test.com",
      "objectId": "<guid>", //for informational purposes, showing who is the beneficiary
      "tenantId": "<guid>", 
      "puid": "<ID of the user>" //for informational purposes, showing who is the beneficiary
    },
    "purchaser": {
      "emailId": "test@test.com",
      "objectId": "<guid>", //for informational purposes, showing who made the purchase
      "tenantId": "<guid>",
      "puid": "<ID of the user>" //for informational purposes, showing who made the purchase
    },
    "planId": "silver",
    "term": {
      "termUnit": "P1M",
      "startDate": "2022-03-07T00:00:00Z", //This field is only available after the saas subscription is active.
      "endDate": "2022-04-06T00:00:00Z" //This field is only available after the saas subscription is active.
    },
      "autoRenew": true/false,
    "isTest": true/false,
    "isFreeTrial": false,
    "allowedCustomerOperations": ["Read", "Update", "Delete"], // Indicates operations allowed on the SaaS subscription for beneficiary. For CSP-initiated purchases, this is always "Read" because the customer cannot update or delete subscription in this flow. Purchaser can perform all operations on the subscription.
      "sandboxType": "None",
      "lastModified": "0001-01-01T00:00:00", //[Deprecated] Do not use.
      "quantity": 5,
    "sessionMode": "None"
  }
}

程序代碼：400 不正確的要求。 x-ms-marketplace-token 遺失、格式不正確、無效或過期。

程序代碼：401 未經授權。授權令牌無效或已過期。該請求嘗試存取一項 SaaS 訂閱，此訂閱所屬的方案發佈時所用的 Microsoft Entra 應用程式 ID 與用來建立驗證權杖的 ID 不同。

代碼：403 禁止。授權憑證無效、未被提供，或權限不足。提供有效的授權憑證。

此錯誤通常表示 SaaS 註冊未正確執行。

程式代碼：500 內部伺服器錯誤。重試 API 呼叫。如果錯誤持續發生，請連絡 Microsoft 支援。

啟用訂用帳戶

在為終端使用者設定 SaaS 帳號後，發佈者必須呼叫 Microsoft 端的啟用訂閱 API。除非此 API 呼叫成功，否則不會向客戶收費。

Note

啟用自動啟用的計畫，出版商不需要呼叫 Activate API。 Microsoft 會在購買時自動啟動訂閱，而出版商則會Subscribe收到 webhook 通知。更多資訊請參閱「設定自動啟用」。

張貼 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?api-version=<api-version>`

查詢參數：

Parameter	Value
`api-version`	使用 2018-08-31。
`subscriptionId`	所購買 SaaS 訂用帳戶的唯一標識碼。你在使用 Resolve API 解決 Microsoft Marketplace 授權憑證後，會取得這個 ID。

請求標頭：

Parameter	Value
`content-type`	`application/json`
`x-ms-requestid`	從客戶端追蹤要求的唯一字串值，最好是 GUID。如果你沒有提供這個值，回應標頭會包含一個產生的值。
`x-ms-correlationid`	用戶端上作業的唯一字串值。此字串會將客戶端作業中的所有事件與伺服器端上的事件相互關聯。如果你沒有提供這個值，回應標頭會包含一個產生的值。
`authorization`	識別發出此 API 呼叫之發行者的唯一存取令牌。當發行者擷取令牌值時，格式會 `"Bearer <access_token>"`，如根據 Microsoft Entra 應用程式取得令牌中所述，。

回應碼：

程序代碼：200 更新訂閱的要求，並標示為「已訂閱」。獨立軟體供應商（ISV）可以在幾分鐘後查詢訂閱狀態（請繼續閱讀「取得」操作以查詢訂閱狀態）。這個操作能讓你確定訂閱是否成功更新。無法訂閱會自動傳送「取消訂閱」Webhook。

此呼叫沒有回應本文。

程序代碼：400 不正確的要求：驗證失敗。

SaaS 訂用帳戶處於已暫停狀態。

代碼：403 禁止。授權憑證無效、未被提供，或權限不足。提供有效的授權憑證。

此錯誤通常表示 SaaS 註冊未正確執行。

程序代碼：404 找不到。 SaaS 訂用帳戶處於 未訂閱 狀態。

程式代碼：500 內部伺服器錯誤。重試 API 呼叫。如果錯誤持續發生，請連絡 Microsoft 支援。

取得所有訂用帳戶的清單

此 API 會擷取發行者在 Microsoft Marketplace 中發佈之所有供應專案的所有已購買 SaaS 訂用帳戶清單。 API 會以所有狀態回傳 SaaS 訂閱，包括未訂閱訂閱，因為 Microsoft 不會刪除這些資訊。

API 會回傳分頁的結果。你必須通過 continuationToken 才能獲得後續結果。

取得 `https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<api-version>`

查詢參數：

Parameter	Value
`api-version`	使用 2018-08-31。
`continuationToken`	選擇性參數。若要擷取結果的第一頁，請保留空白。使用 `@nextLink` 參數中傳回的值來擷取下一頁。

請求標頭：

Parameter	Value
`content-type`	`application/json`
`x-ms-requestid`	從客戶端追蹤要求的唯一字串值，最好是 GUID。如果你沒有提供這個值，回應標頭會包含一個產生的值。
`x-ms-correlationid`	用戶端上作業的唯一字串值。此參數會將來自用戶端作業的所有事件與伺服器端上的事件相互關聯。如果你沒有提供這個值，回應標頭會產生並提供一個。
`authorization`	識別發出此 API 呼叫之發行者的唯一存取令牌。當發行者擷取令牌值時，格式會 `"Bearer <access_token>"`，如根據 Microsoft Entra 應用程式取得令牌中所述，。

回應碼：

程序代碼：200 根據發行者的授權令牌，傳回此發行者所提供之所有供應專案之所有現有訂閱的清單。

回應本文範例：

{
  "subscriptions": [
    {
      "id": "<guid>", // purchased SaaS subscription ID
      "name": "Contoso Cloud Solution", // SaaS subscription name
      "publisherId": "contoso", // publisher ID
      "offerId": "offer1", // purchased offer ID
      "planId": "silver", // purchased plan ID
      "quantity": 10, // purchased amount of licenses, is empty if plan is not per seat
      "beneficiary": { // email address, user ID and tenant ID for which SaaS subscription was purchased.
        "emailId": " test@contoso.com",
        "objectId": "<guid>", //for informational purposes, showing who is the beneficiary
        "tenantId": "<guid>",
        "puid": "<ID of the user>" //for informational purposes, showing who is the beneficiary
      },
      "purchaser": { // email address, user ID and tenant ID that purchased the SaaS subscription. These could be different from beneficiary information for reseller (CSP) purchase
        "emailId": " test@contoso.com",
        "objectId": "<guid>", //for informational purposes, showing who made the purchase
        "tenantId": "<guid>",
        "puid": "<ID of the user>" //for informational purposes, showing who made the purchase
      },
      "term": { // The period for which the subscription was purchased.
        "startDate": "2022-03-04T00:00:00Z", //format: YYYY-MM-DD. This is the date when the subscription was activated by the ISV and the billing started. This field is only available after the saas subscription is active.
        "endDate": "2022-04-03T00:00:00Z", // This is the last day the subscription is valid. Unless stated otherwise, the automatic renew happens the next day. This field is only available after the saas subscription is active.
        "termUnit": "P1M" // where P1M is monthly and P1Y is yearly. Also reflected in the startDate and endDate values
      },
      "autoRenew": true,
      "allowedCustomerOperations": ["Read", "Update", "Delete"], // Indicates operations allowed on the SaaS subscription for beneficiary. For CSP-initiated purchases, this is always "Read" because the customer cannot update or delete subscription in this flow. Purchaser can perform all operations on the subscription.
      "sessionMode": "None", // not relevant
      "isFreeTrial": true, // true - the customer subscription is currently in free trial, false - the customer subscription is not currently in free trial. (Optional field -– if not returned, the value is false.)
      "isTest": false, // not relevant
      "sandboxType": "None", // not relevant
      "saasSubscriptionStatus": "Subscribed" // Indicates the status of the operation. Can be one of the following: PendingFulfillmentStart, Subscribed, Suspended or Unsubscribed.
    },
    // next SaaS subscription details, might be a different offer
    {
      "id": "<guid1>",
      "name": "Contoso Cloud Solution1",
      "publisherId": "contoso",
      "offerId": "offer2",
      "planId": "gold",
      "quantity": "",
      "beneficiary": {
        "emailId": " test@contoso.com",
        "objectId": "<guid>", //for informational purposes, showing who is the beneficiary
        "tenantId": "<guid>",
        "puid": "<ID of the user>" //for informational purposes, showing who is the beneficiary
      },
      "purchaser": {
        "emailId": "purchase@csp.com ",
        "objectId": "<guid>", //for informational purposes, showing who made the purchase
        "tenantId": "<guid>",
        "puid": "<ID of the user>" //for informational purposes, showing who made the purchase
      },
      "term": {
        "startDate": "2019-05-31", /This field is only available after the saas subscription is active.
        "endDate": "2020-04-30",  //This field is only available after the saas subscription is active.
        "termUnit": "P1Y"
      },
      "autoRenew": false,
      "allowedCustomerOperations": ["Read", "Update", "Delete"], // Indicates operations allowed on the SaaS subscription for beneficiary. For CSP-initiated purchases, this is always "Read" because the customer cannot update or delete subscription in this flow. Purchaser can perform all operations on the subscription.
      "sessionMode": "None",
      "isFreeTrial": false,
      "isTest": false,
      "sandboxType": "None",
      "saasSubscriptionStatus": "Suspended"
    }
  ],
  "@nextLink": "https:// https://marketplaceapi.microsoft.com/api/saas/subscriptions/?continuationToken=%5b%7b%22token%22%3a%22%2bRID%3a%7eYeUDAIahsn22AAAAAAAAAA%3d%3d%23RT%3a1%23TRC%3a2%23ISV%3a1%23FPC%3aAgEAAAAQALEAwP8zQP9%2fFwD%2b%2f2FC%2fwc%3d%22%2c%22range%22%3a%7b%22min%22%3a%22%22%2c%22max%22%3a%2205C1C9CD673398%22%7d%7d%5d&api-version=2018-08-31" // url that contains continuation token to retrieve next page of the SaaS subscriptions list, if empty or absent, this is the last page. ISV can use this url as is to retrieve the next page or extract the value of continuation token from this url.
}

如果找不到任何購買的 SaaS 訂閱，回應文體為空。

代碼：403 禁止。授權憑證無效、未被提供，或權限不足。提供有效的授權憑證。

此錯誤通常表示 SaaS 註冊未正確執行。

程式代碼：500 內部伺服器錯誤。重試 API 呼叫。如果錯誤持續發生，請連絡 Microsoft 支援。

取得訂閱

此 API 會擷取發行者在 Microsoft Marketplace 中發佈之 SaaS 供應專案的指定已購買 SaaS 訂用帳戶。使用此呼叫依標識碼取得特定 SaaS 訂用帳戶的所有可用資訊，而不是呼叫用來取得所有訂用帳戶清單的 API。

取得 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<api-version>`

查詢參數：

Parameter	Value
`api-version`	使用 2018-08-31。
`subscriptionId`	所購買 SaaS 訂用帳戶的唯一標識碼。你在使用 Resolve API 解決 Microsoft Marketplace 授權令牌後，會取得這個 ID。

請求標頭：

Parameter	Value
`content-type`	`application/json`
`x-ms-requestid`	從客戶端追蹤要求的唯一字串值，最好是 GUID。如果你沒有提供這個值，回應標頭會包含一個產生的值。
`x-ms-correlationid`	用戶端上作業的唯一字串值。此參數會將來自用戶端作業的所有事件與伺服器端上的事件相互關聯。如果你沒有提供這個值，回應標頭會包含一個產生的值。
`authorization`	識別發出此 API 呼叫之發行者的唯一存取令牌。當發行者擷取令牌值時，格式會 `"Bearer <access_token>"`，如根據 Microsoft Entra 應用程式取得令牌中所述，。

回應碼：

代碼：200 根據您提供的 SaaS 訂閱 subscriptionId 詳情回傳。

回應本文範例：

{
  "id": "<guid>", // purchased SaaS subscription ID
  "name": "Contoso Cloud Solution", // SaaS subscription name
  "publisherId": "contoso", // publisher ID
  "offerId": "offer1", // purchased offer ID
  "planId": "silver", // purchased plan ID
  "quantity": 10, // purchased amount of licenses is empty if plan is not per seat
  "beneficiary": { // email address, user ID and tenant ID for which SaaS subscription is purchased.
    "emailId": "test@contoso.com",
    "objectId": "<guid>", //for informational purposes, showing who is the beneficiary
    "tenantId": "<guid>",
    "puid": "<ID of the user>" //for informational purposes, showing who is the beneficiary
  },
  "purchaser": { // email address ,user ID and tenant ID that purchased the SaaS subscription. These could be different from beneficiary information for reseller (CSP) scenario
    "emailId": "test@test.com",
    "objectId": "<guid>", //for informational purposes, showing who made the purchase
    "tenantId": "<guid>",
    "puid": "<ID of the user>" //for informational purposes, showing who made the purchase
  },
  "allowedCustomerOperations": ["Read", "Update", "Delete"], // Indicates operations allowed on the SaaS subscription for beneficiary. For CSP-initiated purchases, this is always "Read" because the customer cannot update or delete subscription in this flow. Purchaser can perform all operations on the subscription.
  "sessionMode": "None", // not relevant
  "isFreeTrial": false, // true - the customer subscription is currently in free trial, false - the customer subscription is not currently in free trial. Optional field – if not returned the value is false.
  "autoRenew": true,
  "isTest": false, // not relevant
  "sandboxType": "None", // not relevant
  "created": "2022-03-01T22:59:45.5468572Z",
     "lastModified": "0001-01-01T00:00:00", //[Deprecated] Do not use.
  "saasSubscriptionStatus": " Subscribed ", // Indicates the status of the operation: PendingFulfillmentStart, Subscribed, Suspended or Unsubscribed.
  "term": { // the period for which the subscription was purchased
    "startDate": "2022-03-04T00:00:00Z", //format: YYYY-MM-DD. This is the date when the subscription was activated by the ISV and the billing started. This field is only available after the saas subscription is active.
    "endDate": "2022-04-03T00:00:00Z", // This is the last day the subscription is valid. Unless stated otherwise, the automatic renew happens the next day. This field is only available after the saas subscription is active.
    "termUnit": "P1M" //where P1M is monthly and P1Y is yearly. Also reflected in the startDate and endDate values.
  }
}

代碼：403 禁止。授權憑證無效、未被提供，或權限不足。提供有效的授權憑證。

此錯誤通常表示 SaaS 註冊未正確執行。

程序代碼：404 找不到。找不到符合指定 subscriptionId 條件的 SaaS 訂閱。

程式代碼：500 內部伺服器錯誤。重試 API 呼叫。如果錯誤持續發生，請連絡 Microsoft 支援。

列出可用的方案

此 API 會擷取此供應專案的特定購買 subscriptionId 所識別之 SaaS 供應專案的所有方案。使用此呼叫來取得 SaaS 訂用帳戶的受益者可以更新訂用帳戶的所有私人和公用方案清單。傳回的方案可在與已購買的方案相同的地理位置中取得。

此呼叫會傳回該客戶除了已購買的方案外，還傳回可供該客戶使用的方案清單。你可以在出版商網站上向最終使用者展示這個清單。終端使用者可以將訂用帳戶方案變更為傳回清單中任何一個方案。將計劃變更為不在清單中的方案無法運作。

此 API 也會擷取相關聯的使用中私人供應專案識別碼（如果您使用 planId 篩選呼叫 API）。使用 planId 篩選來呼叫 API 時，會在 sourceOffers 節點的回應本文中顯示作用中的私人供應專案標識符 GUID。傳入篩選參數的 planId 應該符合客戶購買的 planId。

取得 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<api-version>&planId=<planId>`

查詢參數：

Parameter	Value
`api-version`	使用 2018-08-31。
`subscriptionId`	所購買 SaaS 訂用帳戶的唯一標識碼。你在使用 Resolve API 解決 Microsoft Marketplace 授權令牌後，會取得這個 ID。
`planId (Optional)`	您想要擷取之特定方案的方案標識碼。這是選擇性參數。如果你省略了它，API 會回傳所有計畫。

請求標頭：

Parameter	Value
`content-type`	`application/json`
`x-ms-requestid`	從客戶端追蹤要求的唯一字串值，最好是 GUID。如果你沒有提供這個值，回應標頭會包含一個產生的值。
`x-ms-correlationid`	用戶端上作業的唯一字串值。此參數會將來自用戶端作業的所有事件與伺服器端上的事件相互關聯。如果你沒有提供這個值，回應標頭會包含一個產生的值。
`authorization`	識別發出此 API 呼叫之發行者的唯一存取令牌。當發行者擷取令牌值時，格式會 `"Bearer <access_token>"`，如根據 Microsoft Entra 應用程式取得令牌中所述，。

回應碼：

程序代碼：200 傳回現有 SaaS 訂用帳戶的所有可用方案清單，包括已購買的方案。

傳遞無效的（選擇性） planId 會傳回空的計劃清單。

回應本文範例：

{
  "plans": [
    {
      "planId": "Platinum001",
      "displayName": "plan display name",
      "isPrivate": true, //returns true for private plans and customized plans created within a private offer.
      "description": "plan description",
      "minQuantity": 5,
      "maxQuantity": 100,
      "hasFreeTrials": false,
      "isPricePerSeat": true,
      "isStopSell": false,
      "market": "US",
      "planComponents": {
        "recurrentBillingTerms": [
          {
            "currency": "USD",
            "price": 1,
            "termUnit": "P1M",
            "termDescription": "term description",
            "meteredQuantityIncluded": [
              {
                "dimensionId": "Dimension001",
                "units": "Unit001"
              }
            ]
          }
        ],
        "meteringDimensions": [
          {
            "id": "MeteringDimension001",
            "currency": "USD",
            "pricePerUnit": 1,
            "unitOfMeasure": "unitOfMeasure001",
            "displayName": "unit of measure display name"
          }
        ]
      },
      "sourceOffers": [ //sourceOffers is returned when planId is passed as filter parameter (note that this is the plan that customer has purchased).
        {
          "externalId": "<guid>" //private offer id, returned when purchase is made through private offer.
        }
      ]
    }
  ]
}

程序代碼：找不到 404。 subscriptionId 找不到。

代碼：403 禁止。授權憑證無效、未被提供，或權限不足。提供有效的授權憑證。

此錯誤通常表示 SaaS 註冊未正確執行。

程式代碼：500 內部伺服器錯誤。重試 API 呼叫。如果錯誤持續發生，請連絡 Microsoft 支援。

變更訂用帳戶上的方案

使用此 API，將針對 SaaS 訂用帳戶購買的現有方案更新為新方案（公開或私人）。當出版商在 Microsoft Marketplace 購買 SaaS 訂閱時，必須在發行方更改方案時，必須呼叫這個 API。

你只能在 Active 訂閱時呼叫這個 API。你可以將任何方案更改為任何現有的計畫（無論是公營或私人），但不能更改為其他方案本身。對於私人方案，您必須在合作夥伴中心將客戶的租戶定義為方案受眾的一部分。

修補程式 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<api-version>`

查詢參數：

Parameter	Value
`api-version`	使用 2018-08-31。
`subscriptionId`	所購買 SaaS 訂用帳戶的唯一標識碼。你在使用 Resolve API 解決 Microsoft Marketplace 授權令牌後，會取得這個 ID。

請求標頭：

Parameter	Value
`content-type`	`application/json`
`x-ms-requestid`	從客戶端追蹤要求的唯一字串值，最好是 GUID。如果你沒有提供這個值，回應標頭會產生並提供一個。
`x-ms-correlationid`	用戶端上作業的唯一字串值。此參數會將來自用戶端作業的所有事件與伺服器端上的事件相互關聯。如果你沒有提供這個值，回應標頭會產生並提供一個。
`authorization`	識別發出此 API 呼叫之發行者的唯一存取令牌。當發行者擷取令牌值時，格式會 `"Bearer <access_token>"`，如根據 Microsoft Entra 應用程式取得令牌中所述，。

要求承載範例：

{
  "planId": "gold" // the ID of the new plan to be purchased
}

回應碼：

代碼：202 變更計畫的請求被接受並以非同步方式處理。合作夥伴應用程式應該輪詢 Operation-Location 網址 ，以判斷變更計畫請求的成功或失敗。每隔幾秒輪詢一次，直到收到操作的最終狀態為失敗、成功或衝突。最終行動狀態會很快恢復，但有時可能需要數分鐘。

合作夥伴應用程式也會在 Microsoft Marketplace 中動作準備好成功完成時收到 webhook 通知。只有這樣，發行者才會在發行者端進行方案變更。

回應標頭：

Parameter	Value
`Operation-Location`	取得作業狀態的 URL。例如，`https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31`

程序代碼：400 不正確的要求：驗證失敗。

找不到所請求的方案，或是該方案無法提供給使用者。
要求的方案與已訂閱的方案相同。
SaaS 訂用帳戶狀態不會訂閱。
要更新的 SaaS 訂用帳戶是由雲端解決方案提供者（CSP）購買。您必須使用 CSP 提供者來執行此動作。
SaaS 訂閱在轉移後續約前無法管理。此限制持續至續約日期。

代碼：403 禁止。授權憑證無效、未被提供，或權限不足。提供有效的授權憑證。

此錯誤通常表示 SaaS 註冊未正確執行。

程序代碼：404 找不到。找不到符合指定 subscriptionId 功能的 SaaS 訂閱。

程式代碼：500 內部伺服器錯誤。重試 API 呼叫。如果錯誤持續發生，請連絡 Microsoft 支援。

Note

你可以一次更改方案或授權數量，但不能同時更改。

你只有在取得最終使用者明確批准變更後，才能呼叫這個 API。

更改 SaaS 訂閱的授權數量

使用此 API 來更新（增加或減少）SaaS 訂閱所購買的授權數量。當 Microsoft Marketplace 建立的 SaaS 訂閱授權數量變動時，出版商必須呼叫此 API。

執照數量不得超過現行計畫允許的數量。在這種情況下，發行商應該先改變計畫，再決定授權數量。

修補程式 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<api-version>`

查詢參數：

Parameter	Value
`api-version`	使用 2018-08-31。
`subscriptionId`	已購買 SaaS 訂用帳戶的唯一標識碼。你在使用 Resolve API 解決 Microsoft Marketplace 授權令牌後，會取得這個 ID。

請求標頭：

Parameter	Value
`content-type`	`application/json`
`x-ms-requestid`	從客戶端追蹤要求的唯一字串值，最好是 GUID。如果你沒有提供這個值，回應標頭會產生並提供一個。
`x-ms-correlationid`	用戶端上作業的唯一字串值。此參數會將來自用戶端作業的所有事件與伺服器端上的事件相互關聯。如果你沒有提供這個值，回應標頭會產生並提供一個。
`authorization`	識別發出此 API 呼叫之發行者的唯一存取令牌。當發行者擷取令牌值時，格式會 `"Bearer <access_token>"`，如根據 Microsoft Entra 應用程式取得令牌中所述，。

要求承載範例：

{
  "quantity": 5 // the new amount of licenses to be purchased
}

回應碼：

代碼：202 變更數量的請求被接受並以非同步方式處理。合作夥伴應該輪詢 Operation-Location URL，以判斷變更數量要求的成功或失敗。每隔幾秒輪詢一次，直到收到操作的最終狀態為失敗、成功或衝突。最終操作狀態很快恢復，但有時可能需要數分鐘。

當動作準備好在 Microsoft Marketplace 中成功完成時，合作夥伴也會收到 Webhook 通知。只有這樣，發行者才會在發行者端進行數量變更。

回應標頭：

Parameter	Value
`Operation-Location`	連結至資源以取得作業的狀態。例如，`https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31`。

程序代碼：400 不正確的要求：驗證失敗。

新數量不在允許範圍內。
遺漏新數量或 0。
新的數量與目前的數量相同。
SaaS 訂閱狀態尚未顯示為訂閱。
要更新的 SaaS 訂用帳戶是由雲端解決方案提供者（CSP）購買。您必須使用 CSP 提供者來執行此動作。
SaaS 訂閱在轉移後續約前無法管理。此限制持續至續約日期。

代碼：403 禁止。授權憑證無效、未被提供，或權限不足。提供有效的授權憑證。

此錯誤通常是未正確執行 SaaS 註冊徵兆。

程序代碼：404 找不到。找不到符合指定 subscriptionId 功能的 SaaS 訂閱。

程式代碼：500 內部伺服器錯誤。重試 API 呼叫。如果錯誤持續發生，請連絡 Microsoft 支援。

Note

你一次只能更改一個方案或一個數量，不能同時更換。

只有在取得最終使用者明確批准變更後，才呼叫此 API。

取消訂用帳戶

使用此 API 取消訂閱指定的 SaaS 訂用帳戶。發行商不一定要用這個 API。引導客戶至 Microsoft Marketplace 取消 SaaS 訂閱。

如果發行者決定在發行者端實作取消在 Microsoft Marketplace 中購買的 SaaS 訂用帳戶，則必須呼叫此 API。完成此呼叫之後，訂用帳戶的狀態會變成 Microsoft端。

如果訂閱在購買后的72小時內取消，則不會向客戶收取費用。

如果訂用帳戶在上述寬限期之後取消，則會向客戶收取費用。客戶在取消后立即失去Microsoft端 SaaS 訂用帳戶的存取權。

刪除 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<api-version>`

查詢參數：

Parameter	Value
`api-version`	使用 2018-08-31。
`subscriptionId`	所購買 SaaS 訂用帳戶的唯一標識碼。你在使用 Resolve API 解決 Microsoft Marketplace 授權令牌後，會取得這個 ID。

請求標頭：

Parameter	Value
`content-type`	`application/json`
`x-ms-requestid`	從客戶端追蹤要求的唯一字串值，最好是 GUID。如果你沒有提供這個值，回應標頭會產生並提供一個。
`x-ms-correlationid`	用戶端上作業的唯一字串值。此參數會將來自用戶端作業的所有事件與伺服器端上的事件相互關聯。如果你沒有提供這個值，回應標頭會產生並提供一個。
`authorization`	識別發出此 API 呼叫之發行者的唯一存取令牌。當發行者擷取令牌值時，格式會 `"Bearer <access_token>"`，如根據 Microsoft Entra 應用程式取得令牌中所述，。

回應碼：

代碼：202 取消訂閱的請求被接受並以非同步方式處理。合作夥伴預期會輪詢 Operation-Location URL，以判斷此要求的成功或失敗。每隔幾秒輪詢一次，直到收到操作的最終狀態為失敗、成功或衝突。最終操作狀態很快恢復，但有時可能需要數分鐘。

當動作在 Microsoft Marketplace 中成功完成時，合作夥伴也會收到 Webhook 通知。只有在發行者取消發行者端的訂閱時，發行者才會取消。

程序代碼：200 訂用帳戶已處於未訂閱狀態。

回應標頭：

Parameter	Value
`Operation-Location`	連結至資源以取得作業的狀態。例如，`https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31`。

程序代碼：400

錯誤的請求刪除不在 allowedCustomerOperations 這個 SaaS 訂閱的清單裡。
SaaS 訂閱在轉移後續約前無法管理。此限制持續至續約日期。

代碼：403 禁止。授權憑證無效、未被提供，或權限不足。提供有效的授權憑證。

此錯誤通常表示 SaaS 註冊未正確執行。

程序代碼：404 找不到。找不到具有 subscriptionId 的 SaaS 訂用帳戶。

代碼：409

刪除無法完成，因為訂閱因待處理作業而被鎖定。

程式代碼：500 內部伺服器錯誤。重試 API 呼叫。如果錯誤持續發生，請連絡 Microsoft 支援。

免費試用

當客戶購買試用版方案時，SaaS 訂閱可成為免費試用。利用訂閱 API 啟動啟用試用期的訂閱，辨識訂閱是否正在免費試用中，辨識哪些方案設定了免費試用，將客戶從免費試用改為付費方案，並在免費試用轉為付費前取消。

API	免費試用資訊
解決已購買的訂用帳戶	使用此 API 解析購買代幣，並確認所購買訂閱是否仍在免費試用中。巢狀 `subscription` 物件包含 `isFreeTrial` 已解決購買目前處於免費試用期的時間。
啟用訂用帳戶	在客戶帳號設定完成後，使用此 API 來啟用手動啟用的 SaaS 訂閱。若購買的方案有免費試用，啟動後會啟動免費試用期，而非立即開始付費帳單。
取得所有訂用帳戶的清單	使用此 API 來識別各優惠的免費試用訂閱。每個訂閱物件都可以包含 `isFreeTrial`，這樣你就能在不同優惠中辨識活躍的免費試用訂閱。
取得訂閱	使用此 API 來辨識特定訂閱是否目前處於免費試用期。訂閱回應可以包含 `isFreeTrial` 針對指定訂閱的內容。
列出可用的方案	使用這個 API 來檢查方案是否有免費試用。每個方案可包含 `hasFreeTrials`，表示該方案是否設定了免費試用。
變更訂用帳戶上的方案	當客戶從發行商端更改方案時，包括客戶在試用期結束前從免費試用升級為付費方案，或從試用啟用方案轉換到另一個試用方案時，請使用此 API。
取消訂用帳戶	利用這個 API 從發行商端取消 SaaS 訂閱。如果訂閱目前處於免費試用狀態，取消會終止試用，且無法將訂閱轉換為付費。

當 isFreeTrial 為真時，訂閱仍有效，但客戶直到試用期結束或在試用期結束前升級為付費方案前才會被收費。

當免費試用結束或客戶升級為付費時， isFreeTrial 都會被設定為 false。

欲了解更多 Microsoft Marketplace 中 SaaS 方案的選項，請參閱 Microsoft Marketplace 的計量服務 API。
檢閱並使用用戶端，以取得不同的程式設計語言和範例。
測試指引請參見「在 SaaS 服務上實作 webhook」。

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-07-23

Microsoft Marketplace 中的 SaaS 履行訂用帳戶 API v2

解決已購買的訂用帳戶

張貼 https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<api-version>

啟用訂用帳戶

張貼 https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?api-version=<api-version>

取得所有訂用帳戶的清單

取得 https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<api-version>

取得訂閱

取得 https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<api-version>

列出可用的方案

取得 https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<api-version>&planId=<planId>

變更訂用帳戶上的方案

修補程式 https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<api-version>

更改 SaaS 訂閱的授權數量

修補程式 https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<api-version>

取消訂用帳戶

刪除 https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<api-version>

免費試用

相關內容

意見反應

其他資源

張貼 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<api-version>`

張貼 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?api-version=<api-version>`

取得 `https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<api-version>`

取得 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<api-version>`

取得 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<api-version>&planId=<planId>`

修補程式 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<api-version>`

修補程式 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<api-version>`

刪除 `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<api-version>`