分享方式:


確認促銷資格

適用於

  • 合作夥伴中心

適當的角色

  • 系統管理代理人

注意

授權型服務的新商務體驗包含許多新功能,並可供所有 雲端解決方案提供者 (CSP) 使用。 如需詳細資訊,請參閱 新的商務體驗概觀

元件者可以驗證客戶交易是否符合指定促銷的資格。 如果客戶交易符合指定促銷的資格,這個方法會 傳回 True 。 合作夥伴可以在提交交易之前先確認資格,以確保將套用促銷。

必要條件

  • 認證,如合作夥伴中心驗證所述。 此案例支援使用獨立應用程式和 App+使用者認證進行驗證。
  • 資格包括購買的產品 SKU 可用性、正在評估的促銷標識碼、交易的數量、期限和計費週期。
  • 此 API 的節流速率上限為每個合作夥伴租使用者每分鐘 625 個要求(RPM)。 超過限制的呼叫會導致 HTTP 回應為 429。 如需節流的相關信息,請參閱 節流指引

REST 要求

要求語法

方法 要求 URI
POST {baseURL}/v1/customers/{customerId}/promotionEligibilities HTTP/1.1

URI 參數

使用下列查詢參數可傳回可用的促銷。

名稱 類型​​ 必要 描述
customerId string Y 此值是 GUID 格式的 customer-tenant-id,此識別碼可讓您用來指定客戶。

要求標頭

如需詳細資訊,請參閱合作夥伴中心 REST 標頭

要求本文

Body 包含 PromotionEligibilitiesRequestItems 的集合。 下表描述 PromotionEligibilitiesRequestItem 的屬性

屬性 型別 必要 描述
catalogItemId 字串 Yes 目錄項目識別碼。
數量 int Yes 授權或實例的數目。
termDuration Datetime Yes 詞彙持續時間的 ISO 8601 表示法。 目前的支援值為 P1M(一個月)、P1Y(一年)和 P3Y(三年)。
billingCycle 字串 Yes 值,表示計費周期的類型。
promotionId 字串 No 促銷項目標識碼。

要求範例

POST https://api.partnercenter.microsoft.com/v1/customers/46632f71-f052-4384-8f84-4cdb6c12c2a1/promotionEligibilities HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: 18752a69-1aa1-4ef7-8f9d-eb3681b2d70a
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
X-Locale: en-US

 // Request example with promotion ID input
{
    "items": [
        {
            "catalogItemId": "CFQ7TTC0LH2Z:0002:CFQ7TTC0HRVK",
            "quantity": 2400,
            "termDuration": "P1Y",
            "billingCycle": "Monthly",
            "promotionId": "39NFJQT1PM6C:0005:39NFJQT1Q5L7"
        }
    ]
}

POST https://api.partnercenter.microsoft.com/v1/customers/46632f71-f052-4384-8f84-4cdb6c12c2a1/promotionEligibilities HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: 18752a69-1aa1-4ef7-8f9d-eb3681b2d70b
MS-CorrelationId: bbbb1111-cc22-3333-44dd-555555eeeeee
X-Locale: en-US

 // Request example with no promotion ID input
{
    "items": [
        {
            "id": "0",
            "catalogItemId": "CFQ7TTC0HBSJ:0001:CFQ7TTC0JQH3",
            "quantity": 300,
            "termDuration": "P1M",
            "billingCycle": "monthly"
        }
    ]
}

REST 回應

如果提供 promotionId 且要求成功,這個方法會傳回資格結果的集合。 如果未提供 promotionId 且要求成功,此方法會傳回指定供應專案的所有促銷,以及每個促銷的對應客戶資格。

回應成功和錯誤碼

每個回應都有一個 HTTP 狀態代碼,指出成功或失敗,以及更多偵錯資訊。 使用網路追蹤工具來讀取此程式代碼、錯誤類型等等參數。 如需完整清單,請參閱錯誤碼

資格錯誤類型和描述

如果資格檢查會根據促銷標識符來判斷要評估的產品 SKU,則資格會傳回 false。 系統會評估各種條件和條件約束,並傳回錯誤類型,以描述不符合資格的條件。

資格錯誤類型 資格錯誤描述
InvalidCatalogItemId 提供的 CatalogItemId 無效。
InvalidPromotion 提供的升級無效。
PrerequisiteProductOwnership 客戶不符合符合此促銷資格的必要產品擁有權需求。
RedemptionLimit 已符合此促銷的兌換限制。
SeatCount 所提供的數量不符合促銷的最低或最大座位需求。
OfferPurchasedPreviously 此供應專案先前已為此客戶購買。
術語 提供的字詞不適用於促銷。
NoPromotionsAvailable 目前沒有促銷。

回應範例

HTTP/1.1 200 OK
Content-Length: 138
Content-Type: application/json
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
MS-RequestId: 18752a69-1aa1-4ef7-8f9d-eb3681b2d70a
Date: Fri, 26 Feb 2021 20:42:26 GMT

// Response example with promotion ID provided in the request
{
    "totalCount": 1,
    "items": [
        {
            "id": 0,
            "catalogItemId": "CFQ7TTC0LH2Z:0002:CFQ7TTC0HRVK",
            "quantity": 2400,
            "billingCycle": "monthly",
            "termDuration": "P1Y",
            "eligibilities": [
                {
                    "promotionId": "39NFJQT1PM6C:0005:39NFJQT1Q5L7",
                    "isEligible": false,
                    "errors": [
                        {
                            "minimumRequiredSeats": 1,
                            "maximumRequiredSeats": 2400,
                            "availableSeats": 500,
                            "type": "SeatCount",
                            "description": "The provided quantity does not satisfy the minimum or maximum seat requirements for the promotion."
                        }
                    ]
                }
            ],
            "attributes": {
                "objectType": "PromotionEligibilities"
            }
        }
    ],
    "attributes": {
        "objectType": "Collection"
    }
}
HTTP/1.1 200 OK
Content-Length: 138
Content-Type: application/json
MS-CorrelationId: bbbb1111-cc22-3333-44dd-555555eeeeee
MS-RequestId: 18752a69-1aa1-4ef7-8f9d-eb3681b2d70b
Date: Fri, 26 Feb 2021 20:42:26 GMT

// Response example with no promotion ID provided in the request
{
    "totalCount": 1,
    "items": [
        {
            "id": 0,
            "catalogItemId": "CFQ7TTC0HBSJ:0001:CFQ7TTC0JQH3",
            "quantity": 300,
            "billingCycle": "monthly",
            "termDuration": "P1M",
            "eligibilities": [
                {
                    "promotionId": "39NFJQT1XK5L:000J:39NFJQT1Q5D8",
                    "isEligible": true
                },
                {
                    "promotionId": "39NFJQT1XG89:0002:39NFJQT1Q5L2",
                    "isEligible": true
                }
            ],
            "attributes": {
                "objectType": "PromotionEligibilities"
            }
        }
    ],
    "attributes": {
        "objectType": "Collection"
    }
}