# Presentment and platform offers
source: https://developer.mastercard.com/presentment/documentation/use-cases/presentment-and-platform-offers/index.md

## Overview {#overview}

A cardholder can interact with an offers program on a website or mobile application to view and activate offers, indicate offer preferences, and review rewards and savings.
Note: The following APIs return user-specific content.

## Authentication {#authentication}

### Retrieve access token {#retrieve-access-token}

When a cardholder logs in to their Offers account, a user session token or access token is created. This token authenticates and tracks the cardholder's interactions with their Offers program. The token must be called prior to any other API calls for the specified cardholder. The default expiration time of the access token is 60 minutes, but it can be configured based on a customer request. The access token is then used in the subsequent API requests.

#### Sequence diagram {#sequence-diagram}

Diagram access-tokens

#### Execution steps {#execution-steps}

1. The cardholder logs in to their Offers account.
2. The Publisher sends a request to Offers for Publishers: `POST /loyalty/offers/presentment/access-tokens`.
   * Offers for Publishers receives and processes the request through `POST /access-tokens`.
   * Offers for Publishers validates the request and generates an access token.
3. Offers for Publishers returns the access token to the Publisher.
4. The cardholder is successfully authenticated.

#### API structure {#api-structure}

The example sequence shows the use of the Access Token API POST request to get the access token for the user.


API Reference: `GET /access-tokens`

<br />

## Offer discovery and engagement {#offer-discovery-and-engagement}

### Retrieve user offers {#retrieve-user-offers}

A cardholder can view a list of offers assigned based on their spend history, each accompanied by relevant content, such as marketing materials, terms and conditions, logos, images, and translations. Offers are assigned a propensity score to indicate the likelihood of redemption, allowing cardholders to sort and prioritize the most relevant offers. When browsing, offers are displayed in descending order of propensity score, showing those with the highest potential for redemption at the top.

#### Sequence diagram {#sequence-diagram-1}

Diagram useroffers

#### Execution steps {#execution-steps-1}

1. The cardholder initiates offer retrieval.
2. The Publisher sends a request to Offers for Publishers: `GET /loyalty/offers/presentment/offers`.
   * Offers for Publishers receives and processes the request through `GET /offers`.
   * Offers for Publishers validates the request and retrieves eligible offers for the cardholder.
3. Offers for Publishers returns the list of offers, including their propensity scores, to the Publisher.
4. The Publisher displays the offers to the cardholder in descending order of propensity score, displaying the highest scoring offer first.

#### API structure {#api-structure-1}

The example sequence shows the use of the following APIs:

1. (Required) Send the Access Token API POST request to get the access token for the user and use it in the Offers API GET request.


   API Reference: `GET /access-tokens`

   <br />

2. Initiate the Offers API GET request to retrieve the offers that are matched to the cardholder. All offers returned receive a propensity score.


   API Reference: `GET /offers`

   <br />

### Retrieve offer details {#retrieve-offer-details}

A cardholder can retrieve details for the requested offer with information such as category, associated merchant, and merchant location.

#### Sequence diagram {#sequence-diagram-2}

Diagram useroffer

#### Execution steps {#execution-steps-2}

1. The cardholder initiates the offer detail request.
2. The Publisher sends a request to Offers for Publishers: `GET /loyalty/offers/presentment/offers/{offer_id}`.
   * Offers for Publishers receives and processes the request through `GET / offers/{offer_id}`.
   * Offers for Publishers validates the request and retrieves details for the specified offer.
3. Offers for Publishers returns the offer details to the Publisher.
4. The Publisher displays the offer details to the cardholder.

#### API structure {#api-structure-2}

The example sequence shows the use of the following APIs:

1. (Required) Send the Access Token API POST request to get the access token for the user and use it in the Offer API GET request.


   API Reference: `GET /access-tokens`

   <br />

2. Initiate the Offer API GET request to retrieve detailed information about an offer.


   API Reference: `GET /offers/{offer_id}`

   <br />

### Geo-filtering of dining offers {#geo-filtering-of-dining-offers}

Cardholders can receive dining offer programs that are geographically relevant specifically within a 10-mile radius of their location. The offer filtering logic applies cardholder location data and merchant location data to ensure relevance and personalization.

#### Sequence diagram {#sequence-diagram-3}

Diagram retrieve-geolocation-offers

#### Execution steps {#execution-steps-3}

1. The cardholder enters a city name as their search criteria to find offers.
2. The Publisher sends a request to Offers for Publishers: `GET /loyalty/offers/presentment/geo-locations`.
   * Offers for Publishers receives and processes the request through `GET / geo-locations`.
3. Offers for Publishers returns geographical coordinates for the specified location.
4. The Publisher uses the returned coordinates to request offers: `GET /loyalty/offers/presentment/offers`.
   * Offers for Publishers receives and processes the request through `GET /offers`.
5. Offers for Publishers returns offers filtered based on the provided geo-location.
6. The Publisher displays the location-based offers to the cardholder.

#### API structure {#api-structure-3}

(Required) Retrieves a list of geographically relevant merchant offers based on the cardholder's location, preferences, and eligibility.

API Reference: `GET /geo-locations`

### Activate an offer {#activate-an-offer}

A cardholder can activate a given offer and make it available for redemption.
Note: Not all programs require an offer to be activated. This is determined during program implementation and Mastercard will consult with the Publisher if offers require an activation for use.

#### Sequence diagram {#sequence-diagram-4}

Diagram useractivations

#### Execution steps {#execution-steps-4}

1. The cardholder initiates offer retrieval.
2. The Publisher sends a request to Offers for Publishers: `GET /loyalty/offers/presentment/offers`.
   * Offers for Publishers receives and processes the request through `GET /offers`.
3. Offers for Publishers returns a list of available offers.
4. The Publisher displays the available offers to the Cardholder.
5. The cardholder selects an offer to activate.
6. The Publisher sends an activation request to Offers for Publishers: `POST /loyalty/offers/presentment/activations`.
   * Offers for Publishers receives and processes the request through `POST /activations`.
7. Offers for Publishers returns a confirmation of the offer activation.
8. The Publisher displays the activation confirmation to the cardholder.

#### API structure {#api-structure-4}

The example sequence shows the use of the following APIs:

1. (Required) Send the Access Token API POST request to get the access token for the user and use it in the Offers API GET request and the Activations API POST request.


   API Reference: `GET /access-tokens`

   <br />

2. Initiate the Offers API GET request to retrieve the offers that are matched to the cardholder and use the offer ID of one of the user matched offers in the Activations API POST request.


   API Reference: `GET /offers`

   <br />

3. Initiate the Activations API POST request to activate an offer and enable that offer for use.


   API Reference: `GET /activations`

   <br />

### Create like or dislike activity {#create-like-or-dislike-activity}

A cardholder can create an activity for a specific source type and source name.

#### Sequence diagram {#sequence-diagram-5}

Diagram activities

#### Execution steps {#execution-steps-5}

1. The cardholder initiates activity creation.
2. The Publisher sends the request to Offers for Publishers: `POST /loyalty/offers/presentment/activities`.
   * Offers for Publishers receives and processes the request through `POST /activities`.
3. Offers for Publishers records the activity and returns a confirmation of the activity creation to the Publisher.
4. The Publisher displays a confirmation that the like or dislike activity has been successfully created.

#### API structure {#api-structure-5}

The example sequence shows the use of the following APIs:

1. (Required) Access Token API POST request to get the access token for the user and use it in the Activities API POST request.


   API Reference: `GET /access-tokens`

   <br />

2. Initiate the Activities API POST request to create an activity for the specified sources, source types and activity type.


   API Reference: `GET /activities`

   <br />

### Retrieve activities by source type {#retrieve-activities-by-source-type}

A cardholder can retrieve all the activities submitted for the source type with the most recent at the top.

#### Sequence diagram {#sequence-diagram-6}

Diagram activities-source-type

#### Execution steps {#execution-steps-6}

1. The cardholder requests to view activities for a specific source type.
2. The Publisher sends a request to Offers for Publishers: `GET /loyalty/offers/presentment/activities/{source_type}`.
   * Offers for Publishers receives and processes the request through `GET /activities/{source_type}`.
3. Offers for Publishers returns the activities to the Publisher, ordered with the most recent first.
4. The Publisher displays the activities to the cardholder. Activities are ordered by recency, with the most recent at the top.

#### API structure {#api-structure-6}

The example sequence shows the use of the following APIs:

1. (Required) Access Token API POST request to get the access token for the user and use it in the Activities GET request.


   API Reference: `GET /access-tokens`

   <br />

2. Initiate the Activities API GET request to retrieve all the activities by source type. It works only for `offers` as source type only.


   API Reference: `GET /activities/{source_type}`

   <br />

### Retrieve activities by source type and source name {#retrieve-activities-by-source-type-and-source-name}

A cardholder can retrieve activities submitted for the source type and the requested source.

#### Sequence diagram {#sequence-diagram-7}

Diagram activities-source-type-and-name

#### Execution steps {#execution-steps-7}

1. The cardholder requests to view activities for a specific source type and source name.
2. The Publisher sends a request to Offers for Publishers: `GET /loyalty/offers/presentment/activities/{source_type}/sources/{source}`.
   * Offers for Publishers receives and processes the request through `GET /activities/{source_type}/sources/{source}`.
3. Offers for Publishers returns activities for the specified source type and source name.
4. The Publisher displays the activities filtered by source type and source name to the cardholder.

#### API structure {#api-structure-7}

The example sequence shows the use of the following APIs:

1. (Required) Access Token API POST request to get the access token for the user and use it in the Activities GET request.


   API Reference: `GET /access-tokens`

   <br />

2. Initiate the Activities API GET request to retrieve all the activities by source type and source. It works only for `offers` as source type only.


   API Reference: `GET /activities/{source_type}/sources/{source}`

   <br />

## Rewards {#rewards}

### Retrieve user rewards {#retrieve-user-rewards}

A cardholder can retrieve an itemized view of rewards they have earned based on their specified search criteria. A reward is defined as a value or benefit earned by eligible cardholders as a result of redeeming an offer. Rewards may include cashback, discounts, points, or other forms of compensation to the consumer determined by the terms of the offer.

#### Sequence diagram {#sequence-diagram-8}

Diagram useradjustments

#### Execution steps {#execution-steps-8}

1. The cardholder requests to view earned rewards.
2. The Publisher sends a request to Offers for Publishers: `GET /loyalty/offers/presentment/adjustments`.
   * Offers for Publishers receives and processes the request through `GET /adjustments`.
3. Offers for Publishers returns rewards data for the cardholder.
4. The Publisher displays the rewards to the cardholder.

#### API structure {#api-structure-8}

The example sequence shows the use of the following APIs:

1. (Required) Send the Access Token API POST request to get the access token for the user and use it in the Adjustments API GET request.


   API Reference: `GET /access-tokens`

   <br />

2. Initiate the Adjustments API GET request to retrieve the rewards for the user.


   API Reference: `GET /adjustments`

   <br />

### Retrieve user savings {#retrieve-user-savings}

A cardholder can access the total savings they have earned from the offers program, along with the total cashback or points accumulated from redeemed offers. Savings are displayed as a comprehensive total covering the duration of the cardholder's participation in the program.

#### Sequence diagram {#sequence-diagram-9}

Diagram usersavings

#### Execution steps {#execution-steps-9}

1. The cardholder requests to view their total savings.
2. The Publisher sends a request to Offers for Publishers: `GET /loyalty/offers/presentment/savings`.
   * Offers for Publishers receives and processes the request through `GET /savings`.
3. Offers for Publishers returns the savings data to the Publisher.
4. The Publisher displays the total savings to the cardholder.

#### API structure {#api-structure-9}

The example sequence shows the use of the following APIs:

1. (Required) Send the Access Token API POST request to get the access token for the user and use it in the User Savings API GET request.


   API Reference: `GET /access-tokens`

   <br />

2. Initiate the User Savings API GET request to retrieve the accumulated and potential savings for a user.


   API Reference: `GET /savings`

   <br />

### Access redemption data {#access-redemption-data}

The Redeemed Transactions API enables an aggregator, which is the party responsible for sourcing each offer, to securely access their own offer redemption data within the authorized retention time frame to support reconciliation efforts.

#### Sequence diagram {#sequence-diagram-10}

Diagram access-redemption-data

#### Execution steps {#execution-steps-10}

1. The aggregator sends a request to retrieve redemption data for offers they own. The request requires these input parameters:

   | Parameter  |                                                                                                                                                                               Description                                                                                                                                                                               | Required |
   |------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|
   | source     | The entity responsible for providing the offer to the Offers Platform. This entity can either be Mastercard as a direct source or an authorized third-party provider.                                                                                                                                                                                                   | Yes      |
   | start_date | The beginning of the offer redemption date range. This parameter, together with end_date, defines the time window for which redeemed transactions are returned. Redemption data is only available for the last 30 days. If the submitted date range exceeds 30 days, the response defaults to the last 30 days of redemption data without returning a warning or error. | No       |
   | end_date   | The end of the offer redemption date range. This parameter, together with start_date, defines the time window for which redeemed transactions are returned. Redemption data is only available for the last 30 days. If the submitted date range exceeds 30 days, the response defaults to the last 30 days of redemption data without returning a warning or error.     | No       |
   | date type  | Indicates whether the date reflects when the transaction occurred or when the Offers Platform recognized the transaction as a redemption. If not specified, the date defaults to the redemption date.                                                                                                                                                                   | No       |
   | merchant   | The name of the retailer to which the offer applies.                                                                                                                                                                                                                                                                                                                    | No       |
   | offer_id   | A system-wide identifier for the offer campaign.                                                                                                                                                                                                                                                                                                                        | No       |

2. Offers for Publishers retrieves the request through `GET /platforms/redeemed-transactions`.
3. If the request is valid, Offers for Publishers sends a successful response with the list of redeemed transactions and their associated metadata within the specified date range. If the submitted date range exceeds 30 days, the response defaults to the last 30 days of redemption data without returning a warning or error.
4. If the request is invalid, Offers for Publishers sends a failed response.
5. In the event of an error response for an invalid request or missing request parameter, update the input and repeat step 1.

#### API structure {#api-structure-10}


API Reference: `GET /platforms/redeemed-transactions`

## Platform offers {#platform-offers}

### Retrieve platform offers {#retrieve-platform-offers}

The Publisher can specify criteria and filter a list of all offers regardless of cardholder. The Publisher can retrieve extended information for the requested offers, such as marketing content, terms and conditions, logos, images, and translations.

#### Sequence diagram {#sequence-diagram-11}

Diagram filteroffers

#### Execution steps {#execution-steps-11}

1. The Publisher sends a request to Offers for Publishers: `GET /loyalty/offers/presentment/platforms/offers`.
   * Offers for Publishers receives and processes the request through `GET platforms/offers`.
2. Offers for Publishers returns a list of platform offers based on the specified criteria.

#### API structure {#api-structure-11}

The example sequence shows the use of the Platform Offers API GET request to get the list of offers for the Publisher based on a filter criteria provided.


API Reference: `GET /platforms/offers`

<br />

### Retrieve platform rewards {#retrieve-platform-rewards}

The Publisher can specify search criteria to retrieve all rewards for a Publisher, including redeemed offers and their associated redemption details for cardholders within a specified time period.

#### Sequence diagram {#sequence-diagram-12}

Diagram retrieve-platform-adjustments

#### Execution steps {#execution-steps-12}

1. The Publisher sends a request to Offers for Publishers: `GET /loyalty/offers/platforms/adjustments`.
   * Offers for Publishers receives and processes the request through `GET /platforms/adjustments`.
2. Offers for Publishers returns rewards data based on the specified criteria.

#### API structure {#api-structure-12}

The example sequence demonstrates the use of the Platforms Adjustments API GET request to retrieve all rewards, including redeemed offers and their associated redemption details, for a Publisher based on the provided filter criteria.

API Reference: `GET /platforms/adjustments`

## Error handling {#error-handling}

Refer to the [Code and Formats](https://developer.mastercard.com/presentment/documentation/code-and-formats/index.md) page for details on possible error responses and resolution steps.