# 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.

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

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

Diagram usecase1

### 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 Identifer are sent in the requests. {#use-case-5-both-card-number-and-card-identifer-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 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 Identifer are sent in the requests. {#use-case-3-both-card-number-and-card-identifer-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.

## 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 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 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. Eligbility API returns a unique identifier based on the provided card number.