確認促銷資格

發行項
03/20/2024

適用於

合作夥伴中心

適當的角色

全域管理員
系統管理代理人

注意

授權型服務的新商務體驗包含許多新功能，且適用於所有雲端解決方案提供者（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	string	Yes	目錄項目識別碼。
數量	int	Yes	授權或實例的數目。
termDuration	Datetime	Yes	詞彙持續時間的 ISO 8601 表示法。目前的支援值為 P1M（一個月）、P1Y（一年）和 P3Y（三年）。
billingCycle	string	Yes	值，表示計費周期的類型。
promotionId	string	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: 81b08ffe-4cf8-49cd-82db-5c2fb0a8e132
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: 81b08ffe-4cf8-49cd-82db-5c2fb0a8e133
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: 81b08ffe-4cf8-49cd-82db-5c2fb0a8e132
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: 81b08ffe-4cf8-49cd-82db-5c2fb0a8e133
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"
    }
}

共用方式為