Get Redemption History

Get Offer Redemption History

The Get Offer Redemption History endpoint allows clients to retrieve a list of past offer redemptions made by the user. This is useful for displaying a user's redemption activity, managing offer usage limits, or powering reward and engagement features.

Prerequisites

Before making an API call to get offer redemption history, ensure that the necessary user-level session token has been obtained. This token is required to authenticate API requests and can be acquired by following the User Client Level Authentication.

Steps to Implement

Construct the API Request
- Purpose: Retrieve a list of offers the user has redeemed.
- Endpoint Reference: Get offer redemption history
- Usage: Make a GET request to the following endpoint:
  - GET /api/v1/offers/redemption-history
- Query Parameters (optional):
  - limit (int ≥ 0): The maximum number of redemption records to return.
  - offset (int ≥ 0): The number of records to skip before starting to return results (for pagination).
  - sort_by (string): Sort field: date, merchant_name, amount, or redemption_type
  - sort_order (string): ascending or descending (default: descending)
  - redeemed_from (string): Start date filter, inclusive, in yyyy-mm-dd format
  - redeemed_to (string): End date filter, inclusive, in yyyy-mm-dd format
  - redemption_type[] (array of strings): Filter by redemption type: INSTORE, PRINT, MOBILE, PURCHASE, CLICKTHRU
  - offer_id (int): Only return redemptions of this offer
  - location_id (int): Only return redemptions at this location
Process the Response
- Purpose: To display the user’s redemption history within the application.
- Response Body: A successful (200 OK) response returns a JSON object. When the user has no redemptions, or no rows match the filters, redemptions is empty and the totals are zero.
  - redemptions: The list of redemptions. Each includes offer_id, offer_name, merchant_name, categories, amount, date, timestamp, location_id, redemption_type, and savings_type.
  - total: Total number of records available
  - total_record: Total number of redeemed offers
  - total_saving: Total savings from all redemptions (e.g., "125.50")
  - this_month_saving: Total savings for the current month
  - limit, offset: The pagination values applied
```
{
  "redemptions": [
    {
      "offer_id": 12345,
      "offer_name": "Buy One Entree, Get One Free",
      "merchant_name": "Pizza Palace",
      "categories": ["Dining"],
      "amount": "15.00",
      "date": "2026-09-14",
      "timestamp": "2026-09-14T18:22:05Z",
      "location_id": 6789,
      "redemption_type": "in_store",
      "savings_type": "monetary"
    }
  ],
  "total": 1,
  "total_record": 1,
  "total_saving": "15.00",
  "this_month_saving": "0.00",
  "limit": 20,
  "offset": 0
}
```
- Error Handling:
  - 400 Bad Request: Returned if a query parameter is invalid (e.g., a malformed date)
  - 500 Internal Server Error: Returned if the backend fails to retrieve the redemption history
  - The error response will include an error_code and a user-friendly error_message

Key Considerations

Pagination Support: Use the limit and offset parameters to load redemption history in chunks, especially for users with extensive activity.
User-Specific Data: This endpoint returns data scoped to the authenticated user. Ensure the correct session context is applied.
Privacy and Security: Do not expose sensitive metadata in the client UI unless explicitly required and permitted.

Best Practices

Display Friendly Timestamps: Convert timestamps in the response to human-readable formats (e.g., "Redeemed 2 days ago").
Paginate for Performance: Use small limit values (e.g., 20 or 50) to keep load times fast and reduce API strain.
Fallback Messaging: If no redemptions are found, display a helpful message (e.g., "You haven’t redeemed any offers yet").
Error Logging: Capture and log failed requests to help with debugging and support.