販売促進の適格性を確認する

2025-06-09

適用対象

パートナーセンター

適切なロール

管理エージェント

注

ライセンスベースのサービスの新しいコマースエクスペリエンスには、多くの新機能が含まれており、すべてのクラウドソリューションプロバイダー (CSP) で利用できます。詳細については、新しいコマースエクスペリエンスの概要を参照してください。

パーターは、顧客トランザクションが特定のプロモーションの対象であるかどうかを確認できます。このメソッドは、顧客トランザクションが特定のプロモーションの対象である場合True を返します。パートナーは、プロモーションが適用されることを確認するために、トランザクションを送信する前に適格性を確認できます。

前提条件

パートナーセンターの認証に関するページで説明している資格情報。このシナリオでは、スタンドアロンアプリとアプリ + ユーザーの両方の資格情報を使った認証がサポートされています。
適格性には、購入した製品 SKU の可用性、評価対象のプロモーション ID、数量、期間、トランザクションの支払いサイクルが含まれます。
この API の調整率は、パートナーテナントあたり 1 分あたり最大 625 要求 (RPM) です。制限を超える呼び出しでは、http 応答は 429 になります。調整の詳細については、 rottling ガイダンスを参照してください。

REST 要求

要求の構文

認証方法	要求 URI
投稿	{baseURL}/v1/customers/{customerId}/promotionEligibilities HTTP/1.1

URI パラメーター

使用可能なプロモーションを返すには、次のクエリパラメーターを使用します。

名前	タイプ	必須	説明
customerId	string	年	この値は、顧客を指定できるようにする識別子である、GUID 形式の customer-tenant-id です。

要求ヘッダー

詳細については、「パートナーセンター REST ヘッダー」を参照してください。

要求本文

本文には、PromotionEligibilitiesRequestItems のコレクションが含まれています。次の表では、 PromotionEligibilitiesRequestItem のプロパティについて説明します。

プロパティ	タイプ	必須	説明
カタログアイテムID	ひも	はい	カタログアイテム識別子。
量	整数 (int)	はい	ライセンスまたはインスタンスの数。
termDuration (期間)	日付と時間	はい	期間の ISO 8601 表現。現在サポートされている値は、P1M (1 か月)、P1Y (1 年)、P3Y (3 年) です。
billingCycle	ひも	はい	支払いサイクルの種類を示す値。
promotionId	ひも	いいえ	昇格項目識別子。

要求の例

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 状態コードが付属しています。ネットワークトレースツールを使用して、このコード、エラーの種類、その他のパラメーターを読み取ります。完全な一覧については、エラーコードに関するページを参照してください。

適格性エラーの種類と説明

適格性チェックで、プロモーション ID に対して評価される製品 SKU が一致しないと判断された場合、適格性は false を返します。さまざまな条件と制約が評価され、エラーの種類が返され、適格性が満たされていない条件が記述されます。

適格性エラーの種類	適格性エラーの説明
無効なカタログアイテムID	指定された CatalogItemId が無効です。
無効なプロモーション	指定された昇格が無効です。
前提条件製品所有権	お客様は、このプロモーションの対象となる前提条件となる製品の所有権要件を満たしていません。
償還限度	このプロモーションの利用制限が満たされました。
座席数	指定された数量は、プロモーションの最小または最大座席要件を満たしていません。
以前に購入されたオファー	このオファーは、この顧客に対して以前に購入されています。
以前購入されたオファー	このオファーは購入できません。これは、顧客が不適格としてリストされている SKU の 1 つを持っているためです。
任期	指定された用語は、プロモーションには適用されません。
プロモーションが利用できません	現時点では、プロモーションは利用できません。

応答の例

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"
    }
}

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, 20 June 2025 20:42:26 GMT

// Response example for OffersPurchasedPreviously error. This error is relevant to the June 9, 2025 three-year enterprise SKU promotions.
{
    "totalCount": 1,
    "items": [
        {
            "id": 0,
            "catalogItemId": "39NFJQT1PM6C:0005:39NFJQT1Q5L7",
            "quantity": 300,
            "billingCycle": "Annual",
            "termDuration": "P3M",
            "eligibilities": [
                {
                    "promotionId": "39NFJQT1PM6C:0005:39NFJQT1Q5L7",
                    "isEligible": false,
                    "errors": [
                            {                      
                            "type": "OffersPurchasedPreviously",
                            "description": " has been purchased previously for this customer."
			                              "exlcudedProductsTerms":[
                                  {
                                      "bigId": "CFQ7TTC0MBMD/0002",
                                      "termDuration": "P1Y"
                        	         },
                   		             {
                        	             "bigId": "CFQ7TTC0MBMD/0002",
			                                   "termDuration": "P3Y"
                        	         },
                   		             {
                        	              "bigId": "CFQ7TTC0MBMD/0004",
				                                   "termDuration": "P1Y"
                                  }
                               ]
                            }
 		                 ]
                }

            "attributes": {
                "objectType": "PromotionEligibilities"
            }
        }
    ],
    "attributes": {
        "objectType": "Collection"
    }
}