# Get Redemptions
source: https://developer.mastercard.com/digital-redemptions/documentation/use-cases/redemptions/get-redemptions/index.md

## Overview {#overview}

This use case provides historical point redemption information for a Rewards
account. It retrieves all redemptions and credit redemptions performed by the
account during a given period. The response sorts redemptions by date in
descending order and supports pagination.

### Why this endpoint {#why-this-endpoint}

Use `GET /redemptions` when you need to show a cardholder their redemption
history, reconcile orders against points deducted, or find the
`redemptionId` of an earlier order before you reverse it with
[Reverse Redemption](https://developer.mastercard.com/digital-redemptions/documentation/use-cases/redemptions/reverse-redemption/index.md)
or update it with
[Update Redemption Status](https://developer.mastercard.com/digital-redemptions/documentation/use-cases/redemptions/update-redemption-status/index.md).
It is a read-only query by RANAC and date range, so it does not change any
balance.

Preconditions:

* You hold a valid RANAC for the cardholder.
* The `from_date` and `to_date` values are in `YYYY-MM-DD` format, in North American Central Time, and `from_date` is not in the future.

## Sequence diagram {#sequence-diagram}

Diagram get-redemptions

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

1. The consumer signs into the customer application.
2. The customer authenticates the consumer.
3. The customer sends a signed request to Digital Redemptions for the redemption history.
4. Mastercard Network API Gateway authenticates and authorizes the customer and routes a valid request to Digital Redemptions.
5. The Digital Redemptions Service validates the request parameters received via the `GET /redemptions` endpoint.
6. The Digital Redemptions Service retrieves the redemption history.
7. The Digital Redemptions Service sends a response with redemption history (200).
8. The Digital Redemptions Service sends a 4xx or 5xx status code for an invalid request.

You will receive an error response for an invalid request or any missing request parameter. In that case, you need to update the input and perform step 3 again.

##### Note {#note}

The response can return one or more redemptions performed between from_date
and to_date.

## Endpoint {#endpoint}


API Reference: `GET /redemptions`

## Scenario #1: Redemption With External Catalog Items {#scenario-1-redemption-with-external-catalog-items}

* Fields under Additional Details section will be included for external catalog redemptions.
* The request for redemption history requires the following mandatory request parameters:
  * **user_id** : The identifier used to identify a user uniquely.
  * **user_id_type** : Type of the user or account identification. Supported identifier is RANAC
  * **from_date** : Start date(YYYY-MM-DD) from when the redemptions are required. This is in CST time zone.
  * **to_date** : End date(YYYY-MM-DD) till when the redemptions are required. This is in CST time zone.

##### Sample response {#sample-response}

```json
  {
  "redemptions": [
    {
      "redemptionId": 2022,
      "redemptionDate": "2023-11-02T08:20:51",
      "redemptionDescription": "Redeemed thru Rest API Service.",
      "pointsRedeemed": 1,
      "redemptionStatusCode": null,
      "redemptionStatusDescription": null,
      "externalId": null,
      "redemptionItemDescription": "Redeemed thru Rest API Service.",
      "sourceItemId": null,
      "sourceItemCode": null,
      "redemptionItemId": 77042,
      "householdId": 119842155,
      "customerId": "762091704154257199330263788543",
      "accountId": "819063012963740866909399370987",
      "rewardCategoryId": 688,
      "groupId": 1434,
      "programId": 46810,
      "redemptionEmail": null,
      "cashbackAccount": null,
      "cashbackDate": null,
      "currencyCode": null,
      "creditRedemptionId": 0,
      "quantity": 1,
      "billingDate": null,
      "creditDate": null,
      "userId": "MRSWSRED",
      "vendorCost": null,
      "totalCashPaid": 0,
      "issuerCost": 0,
      "shippingAddressId": 1041924,
      "invoiceNumber": null,
      "nonMonitorySentDate": null,
      "orderId": 30261194,
      "paymentFormCode": "NA",
      "fulfillmentVendorId": 2669,
      "personalization": null,
      "sourceCode": "ES",
      "cashbackAmount": null,
      "totalCashValue": 0,
      "additionalDetails": {
        "sourceItemId": "testItemId1",
        "merchantPartnerId": "partner1",
        "merchantId": "Merchant1",
        "itemSkuCode": "2345",
        "redemptionCategory": "Gift Cards",
        "redemptionSubCategory": "Restaurant",
        "promotionId": "promo1"
      }
    }
  ]
}
```

## Scenario #2: Redemption With Non-External Catalog Items {#scenario-2-redemption-with-non-external-catalog-items}

* For non-external catalog items, the redemption history will be loaded with Additional Details section as null.
* The request for redemption history requires the following mandatory request parameters:
  * **user_id** : The identifier used to identify a user uniquely.
  * **user_id_type** : Type of the user or account identification. Supported identifier is RANAC
  * **from_date** : Start date(YYYY-MM-DD) from when the redemptions are required. This is in CST time zone.
  * **to_date** : End date(YYYY-MM-DD) till when the redemptions are required. This is in CST time zone.

##### Sample response {#sample-response-1}

```json
{
  "redemptionId": 2018,
  "redemptionDate": "2023-11-02T08:20:51",
  "redemptionDescription": "CR: credit Redeemed thru Rest API Servi",
  "pointsRedeemed": -4,
  "redemptionStatusCode": "T",
  "redemptionStatusDescription": "Redemp XML Notification",
  "externalId": "520013",
  "redemptionItemDescription": null,
  "sourceItemId": null,
  "sourceItemCode": null,
  "redemptionItemId": 77042,
  "householdId": 119842155,
  "customerId": "762091704154257199330263788543",
  "accountId": "819063012963740866909399370987",
  "rewardCategoryId": 688,
  "groupId": 1434,
  "programId": 46810,
  "redemptionEmail": null,
  "cashbackAccount": null,
  "cashbackDate": null,
  "currencyCode": "USD",
  "creditRedemptionId": 2015,
  "quantity": 16,
  "billingDate": null,
  "creditDate": null,
  "userId": "MRSWSRED",
  "vendorCost": null,
  "totalCashPaid": 0,
  "issuerCost": 0,
  "shippingAddressId": null,
  "invoiceNumber": null,
  "nonMonitorySentDate": null,
  "orderId": 30261190,
  "paymentFormCode": "NA",
  "fulfillmentVendorId": 2669,
  "personalization": null,
  "sourceCode": "PP",
  "cashbackAmount": null,
  "totalCashValue": 0,
  "additionalDetails": null
}
```

## Scenario #3: Pagination Request and Response {#scenario-3-pagination-request-and-response}

* The endpoint returns a subset of data when the request contains pagination parameters.
* Request:
  * **offset** : The number of records you asked the start of the list to be offset from. Zero-based page offset index, must NOT be negative, default value is 0.
  * **limit** : The number of records you asked the list to be limited in a page. Must be greater than 0 and less than or equal to 25, default value is 25.
* Response:
  * **count** : The number of items in this batch (the size of the item array).
  * **limit** : The number of items you asked the list to be limited in a page.
  * **offset** : The number of items you asked the start of the list to be offset from.
  * **total** : The total number of items in the collection.

##### Pagination Scenarios With Expected Behavior {#pagination-scenarios-with-expected-behavior}

|          Pagination Scenario          |                 URL                  |                                                                                                Expected Behavior                                                                                                |            Expected Pagination Response            |
|---------------------------------------|--------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------|
| The total number of redemptions is 10 | *GET /redemptions*                   | Returns all 10 redemptions. The default limit of 25 applies.                                                                                                                                                    | "count": 10, "offset": 0, "limit": 25, "total": 10 |
| The total number of redemptions is 10 | *GET /redemptions?offset=4*          | Skips the first 4 redemptions and returns redemptions 5 through 10. The default limit of 25 applies.                                                                                                            | "count": 6, "offset": 4, "limit": 25, "total": 10  |
| The total number of redemptions is 10 | *GET /redemptions?limit=2*           | Returns the first 2 redemptions.                                                                                                                                                                                | "count": 2, "offset": 0, "limit": 2, "total": 10   |
| The total number of redemptions is 10 | *GET /redemptions?offset=5\&limit=5* | Skips the first 5 redemptions and returns redemptions 6 through 10.                                                                                                                                             | "count": 5, "offset": 5, "limit": 5, "total": 10   |
| The total number of redemptions is 30 | *GET /redemptions*                   | Returns redemptions 1 through 25. The default limit of 25 applies. **Note** : To get the remaining 5 redemptions, send another request to "*GET /redemptions?offset=25*". It returns redemptions 26 through 30. | "count": 25, "offset": 0, "limit": 25, "total": 30 |