Guides

Get Offer Details By ID

Suggest Edits

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:
      • language — Language code (e.g., EN)
      • 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, KI)
      • country_code — Country code for regional filtering

  2. Process the Response

    • Purpose: To display detailed information about the offer in the application.
    • Response Body: A successful (200 OK) response will contain a JSON object with the offer's full metadata, including title, description, imagery, merchant details, and pricing.
    • 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. Localized Content: Pass the language query parameter to retrieve translated offer content when available.
  3. Geolocation Parameters Are Optional: For online-only offers, location-based parameters are ignored.
  4. 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.
  • Respect User Language Settings: Set language based on the user’s app preferences to display localized content.
  • 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.

Updated 3 days ago