Get Offer Details By ID

Retrieve Offer Details by ID

The Retrieve Offer Details by ID endpoint provides a way to fetch detailed information about a specific offer using its unique offer_id. This is typically used when a user selects an offer from a list or is deep-linked into the app. The response includes attributes such as the title, description, image, location, price, and other relevant metadata.

Prerequisites

Before making an API call to get 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: Allows a client to retrieve full details for a specific offer by ID.
   • Endpoint Reference: Get offer by ID
   • Usage: Make a GET request to the endpoint below, replacing {offer_id} with the offer's unique ID.
     • GET /api/v1/offers/{offer_id}
   • Query Parameters:
     • location_id — Specific merchant location ID to retrieve location-specific data
     • latitude, longitude, radius — Used together for location-based filtering
     • search_radius_unit — Unit for the search radius (MI or KM)
     • country_code — Country code for regional filtering (e.g., US)
     • catalog_filter_ids — Catalog filter (edition) IDs, so that additional_offers are limited to the same edition or program

2. Process the Response

   • Purpose: To display detailed information about the offer in the application.
   • Response Body: A successful (200 OK) response contains an offer_detail object with the offer's full metadata, including title, description, image, merchant, location, redemption_methods, is_available, is_in_store_offer, and additional_offers (other offers from the same merchant).
   • Error Handling: Your application should be prepared to handle the following:
     • 404 Not Found if the offer_id is invalid or no offer exists
     • 500 Internal Server Error if the backend fails to process the request
     • Error responses will include an error_code and a user-friendly error_message

Key Considerations

1. Location-Specific Results: If location_id is provided, the response will return data for that merchant location. If not, and if latitude, longitude, and radius are included, the API will attempt to return the most relevant nearby location.
2. Geolocation Parameters Are Optional: For online-only offers, location-based parameters are ignored.
3. Fallback Behavior: If no matching location is found and no location_id is provided, the API uses default location selection logic.

Best Practices

• Always Include Location When Applicable: To ensure accurate merchant-specific data, pass location_id or geolocation parameters.
• Log and Handle 404s Gracefully: Display a fallback message or screen when an offer is not found.
• Avoid Duplicate Requests: If an offer was already returned in a list view, consider using cached data to avoid unnecessary API calls.
• Validate Query Parameters: Ensure all coordinates and IDs are in the correct format before making the API request.