Geschiktheid voor promoties controleren

Artikel
03/07/2025

Van toepassing op

Partnercentrum

Juiste rollen

Beheermedewerker

Notitie

De nieuwe commerce-ervaringen voor services op basis van licenties omvatten veel nieuwe mogelijkheden en zijn beschikbaar voor alle CSP's (Cloud Solution Provider). Voor meer informatie, zie overzicht van nieuwe commerce-ervaringen.

Parters kunnen controleren of een klanttransactie in aanmerking komt voor een bepaalde promotie. Deze methode retourneert True als de klanttransactie in aanmerking komt voor een bepaalde promotie. Partners kunnen de geschiktheid controleren voordat ze een transactie indienen om ervoor te zorgen dat de promotie wordt toegepast.

Vereisten

Referenties zoals beschreven in Partnercentrum-authenticatie. Dit scenario ondersteunt verificatie met zowel zelfstandige app- als app+gebruikersreferenties.
Geschiktheid omvat de beschikbaarheid van de aangeschafte product-sku, de promotie-ID die wordt geëvalueerd, de hoeveelheid, de looptijd en de factureringsperiode van de transactie.
De limietsnelheid voor deze API is maximaal 625 aanvragen per minuut (RPM) per partner-tenant. Aanroepen die de limiet overschrijden, resulteren in het HTTP-antwoord van 429. Zie beperkingsrichtlijnen voor meer informatie over beperkingen.

REST-aanvraag

Aanvraagsyntaxis

Wijze	URI aanvragen
POST	{baseURL}/v1/customers/{customerId}/promotionEligibilities HTTP/1.1

URI-parameter

Gebruik de volgende queryparameters om beschikbare promoties te retourneren.

Name	Type	Vereist	Beschrijving
customerId	tekenreeks	Y	De waarde is een door de GUID opgemaakte klant-tenant-id. Dit is een id waarmee u een klant kunt opgeven.

HTTP-aanvraagheaders

Zie REST-headers in het Partnercentrum voor meer informatie.

Inhoud van het verzoek

Het hoofdgedeelte bevat een verzameling PromotionEligibilitiesRequestItems. In deze tabel worden de eigenschappen voor een PromotionEligibilitiesRequestItem beschreven.

Eigenschap	Type	Vereist	Beschrijving
catalogusItemId	tekenreeks	Ja	De identificatie van het catalogus-item.
hoeveelheid	int	Ja	Het aantal licenties of instanties.
termijnduur	Datum en tijd	Ja	Een ISO 8601-weergave van de duur van de term. De huidige ondersteunde waarden zijn P1M (één maand), P1Y (één jaar) en P3Y (drie jaar).
billingCycle	tekenreeks	Ja	De waarde die het type factureringscyclus aangeeft.
promotionId	tekenreeks	Nee	De id van het promotie-item.

Aanvraagvoorbeeld

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-antwoord

Als er een promotionId wordt opgegeven en de aanvraag is geslaagd, retourneert deze methode een verzameling geschiktheidsresultaten. Als promotionId niet is opgegeven en de aanvraag is geslaagd, retourneert deze methode alle promoties die beschikbaar zijn voor de opgegeven aanbieding en de bijbehorende klant die in aanmerking komt voor elke promotie.

Geslaagde antwoorden en foutcodes

Elk antwoord wordt geleverd met een HTTP-statuscode die aangeeft of het succesvol was of is mislukt en meer informatie biedt voor foutopsporing. Gebruik een hulpprogramma voor netwerktracering om deze code, het fouttype en meer parameters te lezen. Zie Foutcodes voor de volledige lijst.

Typen en beschrijvingen van geschiktheidsfouten

De geschiktheid zal onwaar retourneren als de controles bepalen dat de product-SKU niet overeenkomt met de promotie-ID. Er worden verschillende voorwaarden en beperkingen geëvalueerd en fouttypen geretourneerd om de voorwaarden te beschrijven waaraan niet is voldaan voor de geschiktheid.

Type geschiktheidsfout	Beschrijving van geschiktheidsfout
OngeldigCatalogusItemId	De opgegeven CatalogItemId is ongeldig.
OngeldigePromotie	De opgegeven promotie is ongeldig.
Eigendom van Vereist Product	De klant voldoet niet aan de vereisten voor producteigendom om in aanmerking te komen voor deze promotie.
Inwissellimiet	Aan de inwisselingslimiet voor deze promotie is voldaan.
SeatCount	De opgegeven hoeveelheid voldoet niet aan de minimum- of maximumvereisten voor de promotie.
AanbiedingEerderGekocht	Deze aanbieding is eerder gekocht voor deze klant.
Term	De opgegeven term is niet van toepassing op de promotie.
Geen promoties beschikbaar	Er zijn momenteel geen promoties beschikbaar.

Responsvoorbeeld

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

Delen via