Get Offer Counts

The Get Offer Counts endpoint allows clients to retrieve the number of available offers based on specified filters. This is useful for analytics, dashboards, or dynamically displaying the number of offers by category, type, or redemption method. The response returns the count of matching offers per filter.

Prerequisites

Before making an API call to get offer counts, 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

Construct the API Request
- Purpose: Retrieve a count of offers based on filter parameters.
- Endpoint Reference: Get offer counts
- Usage: Make a GET request to the following endpoint:
  - GET /api/v1/offers/counts
- Query Parameters (all optional):
  - categories: Array of category names (e.g., dining, ACTIVITIES)
  - categories_ids: Array of category IDs. Takes precedence over categories: when sent, categories is ignored.
  - offer_types: Array of offer types (bogo, free_with_purchase, percentage_savings, dollars_off, price_point, cash_back, merchandise, digital_gift_card, physical_gift_card, spend_and_get, affiliate)
  - offer_redemption_types: Array of redemption types (in_store, print, online, purchase, spend_and_get)
  - location_latitude, location_longitude, radius: Geo filter. Must be sent together. radius is in miles.
  - location_id: Limit the count to a single merchant location
Process the Response
- Purpose: To retrieve and display offer count summaries in the application.
- Response Body: A successful (200 OK) response contains the count of offers that match the provided filters:
```
{ "total_offers": 128 }
```
- Error Handling:
  - 400 Bad Request: Returned if the query parameters are malformed or invalid
  - 500 Internal Server Error: Returned if the backend fails to process the request
  - Error responses include an error_code and error_message

Key Considerations

Flexible Filtering: You may provide any combination of the filters above. If none are provided, the endpoint returns the total count of all offers.
Array Format: Pass array parameters using bracket notation (e.g., categories[0]=dining&categories[1]=shopping).
Use with Get Offers: This endpoint is typically used in conjunction with Get Offers to provide count summaries alongside actual offer listings.

Best Practices

Cache Counts Where Applicable: If the filters do not change often, cache the result to avoid unnecessary API calls.
Validate Filter Values: Ensure your frontend or analytics tools send valid and expected filter names to prevent 400 Bad Request errors.
Use for UI Elements: Offer counts can be used to dynamically update tab labels, display badges, or provide quick summaries of offer availability.
Monitor Response Time: Since this is often called during UI initialization, monitor its performance to avoid slow page loads.