Comprobar idoneidad de la promoción

Se aplica a

  • Centro de socios

Roles adecuados

  • Agente de administración

Nota:

Las nuevas experiencias comerciales para los servicios basados en licencias incluyen muchas funcionalidades nuevas y están disponibles para todos los Proveedores de soluciones en la nube (CSP). Para más información, consulte información general sobre las nuevas experiencias comerciales.

Los participantes pueden comprobar si una transacción de cliente es apta para una promoción determinada. Este método devuelve True si la transacción del cliente es apta para una promoción determinada. Los partners pueden comprobar la idoneidad antes de enviar una transacción para asegurarse de que se aplicará la promoción.

Requisitos previos

  • Credenciales como se describen en Autenticación de Partner Center. Este escenario admite la autenticación con credenciales de aplicación independiente y app+usuario.
  • La elegibilidad incluye la disponibilidad del SKU del producto adquirido, el ID de la promoción que se está evaluando, la cantidad, la duración del plazo y el ciclo de facturación de la transacción.
  • La velocidad de limitación de esta API es un máximo de 625 solicitudes por minuto (RPM) por inquilino del asociado. Las llamadas que superan el límite darán lugar a la respuesta http de 429. Consulte las instrucciones sobre limitación de velocidad para obtener información sobre la limitación.

Solicitud REST

Sintaxis de la solicitud

Método URI de solicitud
POST {baseURL}/v1/customers/{customerId}/promotionEligibilities HTTP/1.1

Parámetro de URI

Use los siguientes parámetros de consulta para devolver promociones disponibles.

Nombre Tipo Obligatorio Descripción
customerId cadena Y El valor es un elemento customer-tenant-id con formato de GUID, que es un identificador que te permite especificar un cliente.

Encabezados de solicitud

Para obtener más información, consulta Encabezados REST del Centro de partners.

Cuerpo de la solicitud

Body incluye una colección de PromotionEligibilitiesRequestItems. En esta tabla se describen las propiedades de un PromotionEligibilitiesRequestItem.

Propiedad Tipo Obligatorio Descripción
id int No Identificador de elemento de línea dentro de la solicitud.
catalogItemId cuerda / cadena Sí Identificador del elemento de catálogo.
cantidad int Sí Número de licencias o instancias.
termDuration Fecha y hora Sí Representación ISO 8601 de la duración del término. Los valores admitidos actuales son P1M (un mes), P1Y (un año) y P3Y (tres años).
billingCycle cuerda / cadena Sí Valor que indica el tipo de ciclo de facturación.
promotionId cuerda / cadena No Identificador del elemento de promoción.
subscriptionId cuerda / cadena No Identificador de la suscripción. Se requiere al evaluar la idoneidad de las actualizaciones, las conversiones de prueba a pago o las renovaciones.
evaluationType cuerda / cadena No Tipo de evaluación que se va a realizar. Valores: immediate (para actualizaciones y conversiones de prueba a pago) o scheduled (para renovaciones a medio plazo y final). Si se omite, el valor predeterminado es la evaluación de una compra nueva.

Ejemplo de solicitud

POST https://api.partnercenter.microsoft.com/v1/customers/aaaabbbb-0000-cccc-1111-dddd2222eeee/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/aaaabbbb-0000-cccc-1111-dddd2222eeee/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"
        }
    ]
}

Comprobación de la idoneidad de las actualizaciones y las conversiones

Puede usar la misma API para comprobar la idoneidad de la promoción al actualizar una suscripción o convertir una prueba en una suscripción de pago. En estos escenarios, incluya el subscriptionId de la suscripción existente y establezca evaluationType en immediate.

Nota:

Esta API no admite actualmente comprobaciones de idoneidad para escenarios de puestos de complemento (cambio de cantidad).

POST https://api.partnercenter.microsoft.com/v1/customers/aaaabbbb-0000-cccc-1111-dddd2222eeee/promotionEligibilities HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: 18752a69-1aa1-4ef7-8f9d-eb3681b2d70c
MS-CorrelationId: cccc2222-dd33-4444-55ee-666666ffffff
X-Locale: en-US

// Request example for upgrade with evaluationType = immediate
{
    "items": [
        {
            "id": 0,
            "catalogItemId": "CFQ7TTBZZR6H:000P:CFQ7TTC0K0R6",
            "quantity": 90,
            "termDuration": "P1Y",
            "billingCycle": "monthly",
            "promotionId": "39NFJQT10PV6:000B:084R5MQ9QF2R",
            "subscriptionId": "aaaa1111-bb22-3333-cc44-dddddd555555",
            "evaluationType": "immediate"
        }
    ]
}

Comprobación de la idoneidad de las renovaciones

Puede verificar si una promoción es aplicable a las renovaciones de mitad de período y de fin de período configurando evaluationType en scheduled. Esto le permite comprobar si se aplica una promoción en el momento de la renovación. Puede evaluar varias promociones para la misma suscripción incluyendo varios elementos en la solicitud.

Importante

Cómo funcionan las promociones con renovaciones programadas:

  • Si la renovación programada de la suscripción incluye un identificador de promoción válido, la promoción se aplica cuando se produce la renovación.
  • Los socios deben actualizar el calendario de renovación para incluir la promoción antes de la fecha de renovación para que se aplique.
  • Si una promoción finaliza o se retira Microsoft antes de la fecha de renovación, no se aplicará incluso si se agregó anteriormente a la programación.
POST https://api.partnercenter.microsoft.com/v1/customers/aaaabbbb-0000-cccc-1111-dddd2222eeee/promotionEligibilities HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: 18752a69-1aa1-4ef7-8f9d-eb3681b2d70d
MS-CorrelationId: dddd3333-ee44-5555-66ff-777777aaaaaa
X-Locale: en-US

// Request example for renewals with evaluationType = scheduled (multiple items)
{
    "items": [
        {
            "id": 0,
            "catalogItemId": "CFQ7TTBZZR6H:000P:CFQ7TTC0K0R6",
            "quantity": 1110,
            "termDuration": "P1Y",
            "billingCycle": "annual",
            "promotionId": "39NFJQT10PV7:000C:084R5MQ9QF2R",
            "subscriptionId": "bbbb2222-cc33-4444-dd55-eeeeee666666",
            "evaluationType": "scheduled"
        },
        {
            "id": 1,
            "catalogItemId": "CFQ7TTBZZR6H:000P:CFQ7TTC0K0R6",
            "quantity": 1110,
            "termDuration": "P1Y",
            "billingCycle": "annual",
            "promotionId": "39NFJQT10PV6:000D:084R5MQ9QF2R",
            "subscriptionId": "bbbb2222-cc33-4444-dd55-eeeeee666666",
            "evaluationType": "scheduled"
        }
    ]
}

Si se proporciona un promotionId y la solicitud se procesa correctamente, este método devuelve una colección de resultados de elegibilidad. Si no se proporciona promotionId y la solicitud se realiza correctamente, este método devuelve todas las promociones disponibles para la oferta especificada y la idoneidad del cliente correspondiente para cada promoción.

Códigos de respuesta correcta y de error

Cada respuesta incluye un código de estado HTTP que indica éxito o error y más información de depuración. Use una herramienta de seguimiento de red para leer este código, tipo de error y más parámetros. Para ver la lista completa, consulte Códigos de error.

Tipos y descripciones de errores de idoneidad

La idoneidad devolverá false si las comprobaciones de idoneidad determinan la SKU del producto que se va a evaluar con respecto al identificador de promoción no se alinean. Se evalúan varias condiciones y restricciones y devuelven tipos de error para describir las condiciones que no se cumplen para la idoneidad.

Tipo de error de idoneidad Descripción del error de idoneidad
Id de Artículo de Catálogo Inválido CatalogItemId proporcionado no es válido.
InvalidPromotion La promoción proporcionada no es válida.
PrerequisiteProductOwnership El cliente no cumple los requisitos previos de propiedad del producto para poder optar a esta promoción.
Límite de Redención Se ha alcanzado el límite de canje para esta promoción.
Capacidad de Asientos La cantidad proporcionada no cumple los requisitos mínimos o máximos de asiento para la promoción.
OfferPurchasedPreviously Esta oferta ya se ha adquirido previamente para este cliente.
OffersPurchasedPreviously Esta oferta no se puede comprar porque el cliente tiene una de las SKU enumeradas como no válidas.
Término El término proporcionado no es aplicable a la promoción.
No hay promociones disponibles No hay promociones disponibles en este momento.

Ejemplo de respuesta

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"
    }
}
  • Last updated on