API Overview

The Smart Gift API provides a robust and scalable interface for integrating voucher sales and redemptions into your online shop, EPOS system, or mobile/web applications.

Core Capabilities

  • Voucher Sales: Create voucher orders for both monetary and experience-based vouchers.
  • Voucher Redemptions: Facilitate the redemption of vouchers, supporting both single and multiple experience redemptions.
  • Voucher Reservation: Use the hold endpoint to temporarily reserve a voucher for redemption, ensuring the value remains available during multi-step processes.
  • Real-time Availability: Retrieve lists of available vouchers, including details like descriptions, images, and status (active, hidden, disabled, etc.).
  • Flexible Payment Integration: Fetch available payment methods to process sales through your preferred provider.

API Architecture

Authentication

All requests must be authenticated using an API Key provided in the Smart-Auth header.

  • Development URL: https://api.devsmartgift.co.uk
  • Production URL: https://api.smart-gift.co.uk

All requests must be made over HTTPS and include the following headers:

  • Smart-Auth: Your secret API key.
  • Content-Type: application/json
  • Accept: application/json

Key Endpoints

Method Endpoint Description
GET /vouchers List all available vouchers (monetary and experience).
POST /pos-sale Create a new voucher order/sale.
GET /payment-methods Retrieve available payment methods for orders.
POST /redeem Redeem a voucher (monetary value or experience sum).
POST /redeem/hold Reserve a voucher for 5 minutes and receive a hold_token.

Error Handling

The API uses standard HTTP status codes. Most client-side errors return a 422 Unprocessable Entity status with a detailed JSON body explaining the validation failure.

  • 422 Unprocessable Entity: Validation errors (e.g., invalid voucher number, expired voucher, or invalid site ID).
  • 429 Too Many Requests: Rate limit exceeded (limit is 60 requests per minute).
  • 5xx Server Errors: Internal server errors. Use a generic fallback message for these.

Rate Limiting

The API is limited to 60 requests per minute. You can monitor your usage via the following response headers:

  • X-RateLimit-Limit: The total allowed requests per window.
  • X-RateLimit-Remaining: The number of requests remaining in the current window.
  • X-RateLimit-Reset: The Unix timestamp when the limit resets.