# Use Cases
source: https://developer.mastercard.com/easy-savings-specials/documentation/use-cases/index.md

|       API request call       |             Use case             |                                                                                                                                                        Description                                                                                                                                                        |
|------------------------------|----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `GET/countries`              | Fetch country and language codes | Retrieves a list of three-letter ISO country codes in the [ISO 3166-1 alpha-3](https://www.iso.org/iso-3166-country-codes.html) format, along with the supported languages in each country using the [IETF BCP 47](https://gist.github.com/typpo/b2b828a35e683b9bf8db91b5404f1bd1) format, to help fetch relevant offers. |
| `GET/offers`                 | Fetch details about the offers   | Retrieves a list of available offers and their details, including the description, redemption URL, voucher code, merchant name, merchant website, categories, and more.                                                                                                                                                   |
| `POST/redemptions`           | Unlock new redemption            | Provides a voucher code or URL for the requested offer, allowing SMEs to redeem it on the merchant page.                                                                                                                                                                                                                  |
| `GET/redemptions/{order_id}` | Retrieve order history           | Retrieves the existing voucher code and the status of previously unlocked redemptions.                                                                                                                                                                                                                                    |

Each endpoint includes the following details:
> * Overview
> * Pre-requisites (if any)
> * User journey
> * Workflow
> * Use case examples
> * Endpoint YAML

## End-to-end merchant offers redemption process {#end-to-end-merchant-offers-redemption-process}

### Pre-requisites {#pre-requisites}

##### Fetch valid country and language codes {#fetch-valid-country-and-language-codes}

The issuer retrieves valid country and language codes and provides them as input to the `GET/offers` API request to initiate the offers redemption process.
Diagram fetch-country-language

##### Workflow {#workflow}

1. The issuer sends a `GET/countries` request to retrieve valid country and language codes.
2. The Easy Savings Specials Merchant Offers API returns a list of country codes along with their respective supported languages.

Note: This step is typically a one-time pre-configuration. Clients store the response and reuse the codes for subsequent requests, unless they need updates.

### Merchant offers redemption process {#merchant-offers-redemption-process}

This core process helps the issuer distribute merchant offers to SME business cardholders and supports them in accessing and unlocking those offers.
Diagram merchant-offer-redeem

#### Workflow {#workflow-1}

1. The issuer sends a `GET/offers` request to retrieve the list of currently available offers.
2. The Easy Savings Specials Merchant Offers API returns a list of available offers with details, such as description, merchant, categories, and redemption options.
3. The issuer stores the retrieved offer data locally for display and further processing. Note: The issuer updates the list of available offers daily to ensure accuracy and relevance.
4. The SME business cardholder sends a request to view the available offers.
5. The issuer displays offers retrieved from the issuer's existing storage or database.
6. The SME business cardholder sends a request to unlock one or more selected redemption offers.
7. The issuer sends a `POST/redemptions` request to unlock the redemption details for one or more selected offers.
8. The Easy Savings Specials Merchant Offers API returns the redemption details to issuers for one or more selected offers, including redemption codes, expiration dates, and other relevant information.
9. The issuer displays the redemption details along with additional offer information, such as the redemption URL and other relevant details. Note: The required parameters from the list of offers can be mapped and displayed along with the redemption details.
10. The SME business cardholder sends a request to view the redemption or order history.
11. The issuer sends a `GET/redemptions/{order_id}` request to retrieve the redemption history.
12. The Easy Savings Specials Merchant Offers API returns the previously unlocked redemption details, including offer information and redemption status.
13. The issuer displays the previously unlocked redemption details, including relevant offer information and status.

## Next steps {#next-steps}

Now that you have an understanding of the different use cases the service uses, proceed to the [API Reference](https://developer.mastercard.com/easy-savings-specials/documentation/api-reference/index.md) section to interact with all of our endpoints on the API explorer.