# 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 "burn" information about an Rewards account. It retrieves information about ALL the redemptions and credit redemptions performed by the account, in the given time period. Redemptions are sorted in descending order of redemption date and supports pagination. ## Sequence diagram {#sequence-diagram} Diagram get-redemptions ##### Following are the execution steps: {#following-are-the-execution-steps} 1. The consumer signs into the customer application. 2. The customer authenticates the consumer. 3. The customer sends a signed request to the Digital Redemptions for redemption history. 4. Mastercard Network API Gateway authenticates/authorizes the customer and routes the request to the Digital Redemptions in the case of a valid customer. 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 response with a status code of 4xx/5xx in case of 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 single or multiple redemption history depending on the 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 uniquely identify an user. * **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 uniquely identify an user. * **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: Request and Response for Pagination {#scenario-3-request-and-response-for-pagination} * The endpoint returns a subset of data when request contains page 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 scenario's with expected behavior : {#pagination-scenarios-with-expected-behavior-} | Pagination Scenario | URL | Expected Behavior | Expected Pagination Response | |----------------------------------------|--------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------| | The total number of redemptions are 10 | *GET /redemptions* | Returns all the 10 redemptions. The default limit of 25 will be considered. | "count": 10, "offset": 0, "limit": 25, "total": 10 | | The total number of redemptions are 10 | *GET /redemptions?offset=4* | It will skip first 4 redemptions and then return redemptions from 5th to 10th. The default limit of 25 will be considered. | "count": 6, "offset": 4, "limit": 25, "total": 10 | | The total number of redemptions are 10 | *GET /redemptions?limit=2* | Returns the first 2 redemptions. | "count": 2, "offset": 0, "limit": 2, "total": 10 | | The total number of redemptions are 10 | *GET /redemptions?offset=5\&limit=5* | It will skip first 5 redemptions and return redemptions from 6th to 10th. | "count": 5, "offset": 5, "limit": 5, "total": 10 | | The total number of redemptions are 30 | *GET /redemptions* | Return redemptions from first to 25th. The default limit of 25 will be considered. ++**Note**:++ To get the remaining 5 redemptions, we have to make another request "*GET /redemptions?offset=25*". Then, it will return redemptions from 26th to 30th. | "count": 25, "offset": 0, "limit": 25, "total": 30 |