Guides

Get Redemption History

Suggest Edits

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

  1. 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).

  2. Process the Response

    • Purpose: To display the user’s redemption history within the application.
    • Response Body: A successful (200 OK) response returns a JSON array of redemption records, typically including offer metadata, timestamps, and location or context of redemption.
    • Error Handling:
      • 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

  1. Pagination Support: Use the limit and offset parameters to load redemption history in chunks, especially for users with extensive activity.
  2. User-Specific Data: This endpoint returns data scoped to the authenticated user. Ensure the correct session context is applied.
  3. 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.

Updated 3 days ago