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. If omitted, general availability rules apply.
Process the Response
- Purpose: To determine whether the offer is valid and available for use or display.
- Response Body: A successful (200 OK) response will include availability status details.
- 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.
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.

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.