Get Offer Availability

The Get Offer Availability endpoint allows clients to check whether a specific offer is available For the user, optionally scoped to a specific merchant location. This is useful for validating offer usability before redemption or display, especially when location-based rules may affect availability.

Prerequisites

Before making an API call to get offer availability, 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: Check if a specific offer is currently available for the user.
- Endpoint Reference: Get offer availability
- Usage: Make a GET request to the following endpoint, replacing {offer_id} with the offer’s unique identifier:
  - GET /api/v1/offers/{offer_id}/availability
- Path Parameters:
  - offer_id (int, required): The ID of the offer to check.
- Query Parameters:
  - location_id (int, optional): The ID of a specific merchant location to check availability against. Required for non-online offers.
  - catalog_filter_ids (array of UUIDs, optional): Catalog filter (edition) IDs. When sent, the offer is only available if it belongs to at least one of them.
- Checking Multiple Offers: To check several offers in one call, send a POST to /api/v1/offers/availability with an array of { "offer_id", "location_id", "catalog_filter_ids" } items. See Check offers availability. The response is an array with one result per item.
Process the Response
- Purpose: To determine whether the offer is valid and available for use or display.
- Response Body: A successful (200 OK) response contains:
  - offer_id: The offer that was checked
  - is_available: Whether the user can redeem the offer now
  - location_id: The location checked, if any
  - remaining: How many more times the user can redeem the offer
  - offer_redemption_limit: The offer's redemption cap
  - number_of_redemptions_used: The user's total redemptions of the offer
  - redeemed_at_date: When the user last redeemed the offer
  - redemptions_used_at: Timestamps of all the user's redemptions of the offer
  - refresh_date: When the redemption limit resets
  - redemption_control_details: The redemption control period code (e.g., Y, CQ, U)
```
{
  "offer_id": 12345,
  "is_available": true,
  "location_id": 6789,
  "remaining": 1,
  "offer_redemption_limit": 2,
  "number_of_redemptions_used": 1,
  "redeemed_at_date": "2026-09-14T18:22:05Z",
  "redemptions_used_at": ["2026-09-14T18:22:05Z"],
  "refresh_date": "2027-01-01T00:00:00Z",
  "redemption_control_details": "Y"
}
```
- Error Handling:
  - 400 Bad Request: Returned if the provided offer_id is invalid
  - 500 Internal Server Error: Indicates a backend error occurred while processing the request
  - Errors will include an error_code and a descriptive error_message

Key Considerations

Location-Specific Validation: If location_id is provided, the response will reflect availability for that specific location. Otherwise, it defaults to general availability.
Location Required for Non-Online Offers: location_id is required if the offer is tied to a physical location.
Use for Gating Actions: This endpoint is commonly used before allowing a user to proceed with redemption, booking, or checkout to avoid downstream errors.
Offer ID Must Be Valid: Passing a non-existent or inactive offer ID will result in a 400 error.
Redemption Method: An offer at a physical location can be redeemed as PRINT or INSTORE. See Redeem Offer.

Best Practices

Always Validate Before Redemption: Use this endpoint to check offer availability before allowing redemption to ensure a smooth user experience.
Pair with Offer Details: Use in conjunction with Get Offer by ID to validate both availability and metadata.
Fallback UI for Inactive Offers: If an offer is unavailable, provide a user-friendly message or alternative recommendations.
Log Failures for Support: Capture offer_id, location_id, and any error responses to help diagnose issues with offer availability checks.