Redeem Offer

Redeem Offer

The Redeem Offer endpoint allows clients to redeem a specific offer on behalf of the authenticated user. This is used to trigger a redemption event, which may issue a voucher, log the redemption in history, or initiate reward workflows. The request includes contextual metadata such as platform, redemption time, location, and voucher type.

Prerequisites

Before making an API call to redeem offer, 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: Submit a redemption request for a specific offer.
   • Endpoint Reference: Redeem offer
   • Usage: Make a POST request to the following endpoint, replacing {offer_id} with the offer’s unique identifier:
     • POST /api/v1/offers/{offer_id}/redeem
   • Path Parameters:
     • offer_id (int, required): The ID of the offer being redeemed.
   • Body Parameters:
     • platform (string, required): The platform used for redemption (e.g., WEB, MOBILE_APP)
     • redeemed_at (ISO date-time, required): The timestamp of when the redemption occurs
     • time_zone (string, required): IANA time zone (e.g., America/Chicago)
     • voucher_type (string, required): Type of voucher being used (PRINT, DIGITAL, etc.)
     • latitude (double, optional): Latitude of the user at redemption
     • longitude (double, optional): Longitude of the user at redemption
     • location_id (int, optional): Merchant location ID tied to the redemption

2. Process the Response

   • Purpose: To confirm the offer redemption and update the user interface.
   • Response Body: A successful (200 OK) response will confirm the redemption and return any relevant metadata (e.g., voucher, redemption ID).
   • Error Handling:
     • 400 Bad Request: Returned if the offer_id is invalid or required fields are missing
     • 500 Internal Server Error: Indicates an error occurred during processing
     • Error responses include an error_code and a descriptive error_message

Key Considerations

1. Time Zone and Timestamps: The combination of redeemed_at and time_zone ensures accurate local time tracking. Always provide both.
2. Voucher Type: voucher_type must match the type of redemption.