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 issues a voucher, logs the redemption in history, or initiates 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 (WEB or MOBILE)
     • redeemed_at (ISO 8601 date-time, required): The timestamp of when the redemption occurs, in UTC
     • voucher_type (string, required): Type of voucher to generate (INSTORE, PRINT, or CLICKTHRU). See Voucher Types.
     • latitude (double, optional): Latitude of the user at redemption
     • longitude (double, optional): Longitude of the user at redemption. If one coordinate is sent, both must be sent.
     • location_id (int, optional): Merchant location ID tied to the redemption
     • voucher_options (object, optional): Rendering options for the voucher image. Any field left out uses the default for the voucher type.
       • format (string): png (default) or html
       • template (string): instore or print
       • width (int): Layout width in CSS pixels. Defaults to 400 for instore and 770 for print.
       • url_expiration_seconds (int): How long the voucher image URL stays valid. Defaults to 3600 (1 hour), maximum 86400 (24 hours).
       • with_extras (boolean): Render the template's extra sections (the Entertainment header on in-store; the page header, usage footer and membership banner on print). Defaults to false for instore and true for print.

   Example Request

   JSON

   POST /api/v1/offers/12345/redeem
   {
     "platform": "WEB",
     "redeemed_at": "2026-10-08T17:30:00Z",
     "voucher_type": "INSTORE",
     "latitude": 41.8781,
     "longitude": -87.6298,
     "location_id": 6789
   }

2. Process the Response

   • Purpose: To confirm the offer redemption and display the voucher to the user.
   • Response Body: A successful (200 OK) response contains the following fields:

• Error Handling: Errors are returned as Problem Details (RFC 9457) objects with type, title, status, and detail fields.
  • 400 Bad Request: Malformed offer_id, only one of latitude/longitude sent, or a voucher_type the offer does not support (type ends in #redemption-method-not-supported)
  • 401 Unauthorized: Missing, malformed, or expired access token. Refresh the session and retry.
  • 403 Forbidden: The account is not entitled to Entertainment offers. Retrying will not help.
  • 404 Not Found: No published offer exists for the given offer_id
  • 409 Conflict: The offer is not available for redemption (type ends in #offer-unavailable). It is expired, out of stock, or the account has no remaining redemptions for it.
  • 500 Internal Server Error: An error occurred during processing
  • 503 Service Unavailable: Voucher generation failed because an upstream dependency is unavailable. Retry after a short delay.

Voucher Types

The voucher_type sent in the request decides which voucher is returned in the response. Every voucher includes an asset object:

• asset.asset_uri: A pre-signed URL to the rendered voucher image. It expires after voucher_options.url_expiration_seconds (1 hour by default), so display or download it right away rather than storing the URL.
• asset.asset_type: VoucherInstore, VoucherPrint, or VoucherClickThru.

In-store Voucher (INSTORE)

Shown on the member's phone and presented to the cashier at a physical location. The voucher is valid for 10 minutes; once the user closes it, it can't be redeemed again.

What to use from the response:

• voucher.in_store.asset.asset_uri: Display this image full-screen to the member.
• voucher.in_store.code: The promotional code, if the offer has one. It is already drawn on the voucher image; use this field if you also want to show it as text.
• entertainment_logo_url and entertainment_spinning_logo_url: Display around the voucher when present (see Entertainment Branding).

{
  "voucher": {
    "in_store": {
      "asset": {
        "asset_uri": "https://<voucher-bucket>.s3.amazonaws.com/vouchers/...png?X-Amz-Expires=3600&...",
        "asset_type": "VoucherInstore"
      },
      "code": null
    }
  },
  "voucher_id": "3f1c2a9e-7b4d-4e2a-9c1f-8d6e5b4a3c21",
  "redemption_id": 98765,
  "is_entertainment_offer": true,
  "entertainment_logo_url": "https://d1a4n83cq9sj78.cloudfront.net/assets/frontend-assets/entertainment_logo.png",
  "entertainment_spinning_logo_url": "https://d1a4n83cq9sj78.cloudfront.net/assets/frontend-assets/entertainment_spinning_logo.gif"
}

Print Voucher (PRINT)

A full-page voucher the member prints or saves and brings to the merchant. The voucher is valid for 14 days from the date it was printed.

What to use from the response:

• voucher.print.asset.asset_uri: Display this image with a print or download option. By default it includes the page header, usage footer, and membership banner.
• voucher.print.code: The promotional code, if the offer has one. It is already drawn on the voucher image.
• entertainment_logo_url and entertainment_spinning_logo_url: Display around the voucher when present (see Entertainment Branding).

{
  "voucher": {
    "print": {
      "asset": {
        "asset_uri": "https://<voucher-bucket>.s3.amazonaws.com/vouchers/...png?X-Amz-Expires=3600&...",
        "asset_type": "VoucherPrint"
      },
      "code": "SAVE20"
    }
  },
  "voucher_id": "8a2b6c4d-1e3f-4a5b-9c7d-0e1f2a3b4c5d",
  "redemption_id": 98766,
  "is_entertainment_offer": true,
  "entertainment_logo_url": "https://d1a4n83cq9sj78.cloudfront.net/assets/frontend-assets/entertainment_logo.png",
  "entertainment_spinning_logo_url": "https://d1a4n83cq9sj78.cloudfront.net/assets/frontend-assets/entertainment_spinning_logo.gif"
}

Click-thru Voucher (CLICKTHRU)

Used for online offers. The member is sent to the merchant's website, where the code is applied.

What to use from the response:

• voucher.click_thru.uri: The merchant URL. Open it when the member taps the redeem button. Any tracking parameters for the member's code are already appended, so use the URL as is.
• voucher.click_thru.code: The promotional code to enter at checkout, if the offer has one. Display it so the member can copy it.
• voucher.click_thru.instructions: Redemption instructions to display to the member. Defaults to Click the link to redeem when the offer has no usage text.
• voucher.click_thru.asset.asset_uri: A rendered voucher image you can display alongside the link.
• entertainment_logo_url and entertainment_spinning_logo_url: Display around the voucher when present (see Entertainment Branding).

{
  "voucher": {
    "click_thru": {
      "asset": {
        "asset_uri": "https://<voucher-bucket>.s3.amazonaws.com/vouchers/...png?X-Amz-Expires=3600&...",
        "asset_type": "VoucherClickThru"
      },
      "uri": "https://www.merchant.com/deals?code=ONLINE15",
      "instructions": "Enter the code at checkout to save 15%.",
      "code": "ONLINE15"
    }
  },
  "voucher_id": "c4d5e6f7-a8b9-4c0d-8e1f-2a3b4c5d6e7f",
  "redemption_id": 98767,
  "is_entertainment_offer": true,
  "entertainment_logo_url": "https://d1a4n83cq9sj78.cloudfront.net/assets/frontend-assets/entertainment_logo.png",
  "entertainment_spinning_logo_url": "https://d1a4n83cq9sj78.cloudfront.net/assets/frontend-assets/entertainment_spinning_logo.gif"
}

Purchase and Spend and Get Offers

These offers render no voucher. The response omits voucher and the Entertainment logo URLs, and returns instructions and code at the top level instead.

{
  "instructions": "Use the code at checkout.",
  "code": "PROMO123",
  "voucher_id": null,
  "redemption_id": 98768,
  "is_entertainment_offer": true
}

Entertainment Branding

When the redeemed offer is Entertainment's own inventory (is_entertainment_offer is true) and the response contains a voucher, the response includes two image URLs. Display them on the redemption and voucher screens so you don't need to host the images yourself.

Field	Image
entertainment_logo_url
entertainment_spinning_logo_url

For partner (white-label) offers, is_entertainment_offer is false and both fields are omitted. Show your program's own logo instead. The voucher image for a partner offer is already rendered without Entertainment branding.

Key Considerations

1. Timestamps: Send redeemed_at in UTC.
2. Voucher Type: voucher_type must be a redemption method the offer supports. Otherwise the request fails with 400 and a #redemption-method-not-supported problem type.
3. Voucher Image URLs Expire: asset_uri is a pre-signed URL. Request a longer lifetime with voucher_options.url_expiration_seconds (up to 24 hours) if needed.
4. Branding Fields Are Optional: Always check for entertainment_logo_url and entertainment_spinning_logo_url before using them, since they are omitted for partner offers and for offers with no voucher.