# Use Cases
source: https://developer.mastercard.com/eligibility-api/documentation/usecases/index.md

The Eligibility API provides the ability for vendors/merchants to search for products and benefits
using various metrics. Use cases for the endpoints are outlined below, but further information about each endpoint
can be found by looking through [API Reference](https://developer.mastercard.com/eligibility-api/documentation/api-reference/index.md).
Please find additional information about errors for the endpoints in the [Code and Formats Reference](https://developer.mastercard.com/eligibility-api/documentation/code-and-formats/index.md) section.

### Endpoint map {#endpoint-map}

|       Use case area        |         Typical endpoint          |                                   Primary input                                    |                            Outcome                            |
|----------------------------|-----------------------------------|------------------------------------------------------------------------------------|---------------------------------------------------------------|
| Benefits lookup            | `benefits/searches`               | `cardNumber`, `cardIdentifier`, optional `effectiveDate` and `serviceProviderCode` | Returns active benefits for the selected card or identifier   |
| Product lookup             | `products/searches`               | `cardNumber`, `cardIdentifier`, optional `effectiveDate`                           | Returns products associated with the card                     |
| Bundle lookup              | `/cards/{card_number_id}/bundles` | `cardIdentifier`, optional `effectiveDate` and `serviceProviderCode`               | Returns bundles associated with the card identifier           |
| Access token generation    | `widgets/access-tokens`           | vendor context and authentication                                                  | Returns a valid token for widget access                       |
| Card identifier generation | `/card-identifiers`               | `cardNumber`                                                                       | Returns a unique identifier based on the supplied card number |

Use the [API Reference](https://developer.mastercard.com/eligibility-api/documentation/api-reference/index.md) to review the authoritative request and response schema for each operation before implementing production logic.

## Benefits Use Cases {#benefits-use-cases}

Below you will find a sequence diagram outlining how the *benefits/searches* can be used.

Diagram usecase1

Use `benefits/searches` whenever you need the eligible benefits for a cardholder, rather than `products/searches` (which returns product metadata, not benefit entitlements) or `/card-identifiers` (which only tokenizes a card number). Pick this endpoint any time you need to decide whether to show a benefit or offer to the cardholder.

API Reference: `POST /benefits/searches`

### Use Case 1: Retrieve benefits that are active as of today {#use-case-1-retrieve-benefits-that-are-active-as-of-today}

1. Vendor sends a request with a Luhn-verified card number or a card identifier as an input parameter
2. Eligibility API returns the benefits that are active/effective as of the current date

### Use Case 2: Retrieve benefits that are active as of a specific date {#use-case-2-retrieve-benefits-that-are-active-as-of-a-specific-date}

1. Vendor sends a request with a Luhn-verified card number or a card identifier and a past date as input parameters
2. Eligibility API returns the benefits that are active/effective as of the given date

### Use Case 3: Retrieve benefits that are specific to a vendor {#use-case-3-retrieve-benefits-that-are-specific-to-a-vendor}

1. Vendor sends a request with a Luhn-verified card number or a card identifier and a service provider code as input parameters
2. Eligibility API returns the benefits that are active/effective as of the current date and are serviced by the provider code

### Use Case 4: Retrieve benefits that are associated with a specific product {#use-case-4-retrieve-benefits-that-are-associated-with-a-specific-product}

1. Vendor sends a request with a Luhn-verified card number or a card identifier and a product code as input parameters
2. Eligibility API returns the benefits that are active/effective as of the current date and have product(s) with the given code

### Use Case 5: Both Card Number and Card Identifier are sent in the requests. {#use-case-5-both-card-number-and-card-identifier-are-sent-in-the-requests}

1. Vendor sends a request containing both a Luhn-verified card number and a card identifier, we prioritize the card number and disregard the identifier during processing.

## Products Use Cases {#products-use-cases}

Below you will find a sequence diagram outlining how the *products/searches* can be used.

Diagram usecase2

Use `products/searches` when you need the Mastercard product(s) tied to a card, for example to drive product-level reporting or to determine which product code to pass into a benefits or bundle lookup. Use `benefits/searches` instead when the goal is to determine benefit eligibility itself.

API Reference: `POST /products/searches`

### Use Case 1: Retrieve products that are associated with a specific cardNumber {#use-case-1-retrieve-products-that-are-associated-with-a-specific-cardnumber}

1. Vendor sends a request with a Luhn-verified card number or a card identifier as an input parameter
2. Eligibility API returns the products that are active/effective as of the current date and associated with the current card number

### Use Case 2: Retrieve products that are associated with a specific cardNumber and active as of a specific date {#use-case-2-retrieve-products-that-are-associated-with-a-specific-cardnumber-and-active-as-of-a-specific-date}

1. Vendor sends a request with a Luhn-verified card number or a card identifier and a past date as input parameters
2. Eligibility API returns the products that are active/effective as of the past date and associated with the current card number

### Use Case 3: Both Card Number and Card Identifier are sent in the requests. {#use-case-3-both-card-number-and-card-identifier-are-sent-in-the-requests}

1. Vendor sends a request containing both a Luhn-verified card number and a card identifier, we prioritize the card number and disregard the identifier during processing.

## Bundles Use Cases {#bundles-use-cases}

Below you will find a sequence diagram outlining how the \* /cards/{card_number_id}/bundles\* can be used.

Diagram usecase5

Use `/cards/{card_number_id}/bundles` when a vendor already holds a card identifier and needs the bundled set of benefits/products grouped together for that card, rather than making separate `benefits/searches` and `products/searches` calls. This endpoint requires a card identifier (generated via `/card-identifiers`), not a raw card number.

API Reference: `GET /cards/{card_number_id}/bundles`

### Use Case 1: Retrieve bundles that are active as of today {#use-case-1-retrieve-bundles-that-are-active-as-of-today}

1. Vendor sends a request with a card identifier as a query parameter
2. Eligibility API returns the bundles that are active/effective as of the current date and associated with the card identifier

### Use Case 2: Retrieve bundles that are active as of a specific date {#use-case-2-retrieve-bundles-that-are-active-as-of-a-specific-date}

1. Vendor sends a request with a card identifier and an effective date as query parameters
2. Eligibility API returns the bundles that are active/effective as of the given date and associated with the card identifier

### Use Case 3: Retrieve bundles that are specific to a service provider {#use-case-3-retrieve-bundles-that-are-specific-to-a-service-provider}

1. Vendor sends a request with a card identifier and a service provider code as query parameters
2. Eligibility API returns the bundles that are active/effective as of the current date, associated with the card identifier, and serviced by the specified provider code

### Use Case 4: Retrieve bundles with multiple filter criteria {#use-case-4-retrieve-bundles-with-multiple-filter-criteria}

1. Vendor sends a request with a card identifier, an effective date, and a service provider code as query parameters
2. Eligibility API returns the bundles that match all the specified criteria (card identifier, date and service provider)

## Access Token Use Cases {#access-token-use-cases}

Below you will find a sequence diagram outlining how the *widgets/access-tokens* can be used.

Diagram usecase3

Use `widgets/access-tokens` when a non-PCI-compliant vendor needs to embed the Mastercard widget and does not want to handle raw card numbers directly. Choose this endpoint over `/card-identifiers` when the goal is rendering the widget itself, not generating a standalone identifier for backend use.

API Reference: `GET /widgets/access-tokens`

### Use Case 1: Retrieve new token for the vendor website {#use-case-1-retrieve-new-token-for-the-vendor-website}

1. The vendor sends a request, and the API returns a newly generated access token.
2. If the token is successfully verified and remains valid, the widget will be displayed on the vendor's page.
3. The authentication token will remain active for a specified period after issuance. However, to ensure uninterrupted access and security, the vendor must periodically refresh or extend the token's validity by re-authenticating.

## Card Identifier Use Cases {#card-identifier-use-cases}

Below you will find a sequence diagram outlining how the */card-identifiers* can be used.

Diagram usecase4

Use `/card-identifiers` when you need to convert a raw card number into a reusable, non-sensitive identifier before storing it or passing it to `benefits/searches`, `products/searches`, or the bundles endpoint. This is the only endpoint that accepts and returns payload-encrypted (JWE) data; see [API Basics - Payload Encryption](https://developer.mastercard.com/eligibility-api/documentation/api-basics/index.md).

API Reference: `POST /card-identifiers`

### Use Case 1: Retrieve card identifier for a provided card number {#use-case-1-retrieve-card-identifier-for-a-provided-card-number}

1. The vendor sends a request with a Luhn-verified card number as an input parameter
2. Eligibility API returns a unique identifier based on the provided card number.

## Widget API Use Cases {#widget-api-use-cases}

The widget specification (`widget-spec.yaml`) exposes the same card-identifier and benefits-search capability for use inside the embedded Mastercard widget flow described in [Widget Integration](https://developer.mastercard.com/eligibility-api/documentation/tutorials-and-guides/widget-tutorial/widget-integration/index.md). Use these operations instead of the Eligibility API operations above only when your integration is driven through the widget's own initialization/session flow rather than a direct backend-to-backend call.

### Use Case 1: Generate a card identifier from within the widget flow {#use-case-1-generate-a-card-identifier-from-within-the-widget-flow}

1. The widget captures the cardholder's card number and sends it to `benefits/card-identifiers`.
2. The widget API returns a card identifier scoped to the widget session, which is then used to look up benefits.


API Reference: `POST /benefits/card-identifiers`

### Use Case 2: Retrieve benefits from within the widget flow {#use-case-2-retrieve-benefits-from-within-the-widget-flow}

1. Using the card identifier generated above, the widget sends a request to `benefits/searches`.
2. The widget API returns the eligible benefits to render inside the embedded widget UI.


API Reference: `POST /benefits/searches`

## Next Steps {#next-steps}

* Review the full request/response contract for each operation above in the [API Reference](https://developer.mastercard.com/eligibility-api/documentation/api-reference/index.md).
* Validate these flows against Sandbox using the [Testing](https://developer.mastercard.com/eligibility-api/documentation/testing/index.md) guide.
* If you are embedding the widget rather than calling the Eligibility API directly, continue with [Widget Integration](https://developer.mastercard.com/eligibility-api/documentation/tutorials-and-guides/widget-tutorial/widget-integration/index.md).