REST API

Getting Started

Generate an API key from your dashboard at Settings → API Keys. Include it as a Bearer token in every request:

Authorization: Bearer gft_your_api_key_here

Base URL: https://www.gifternise.com/api/v1

Endpoints

Health Check

GET /api/v1/ping

Response:
{
  "success": true,
  "data": {
    "message": "Gifternise API v1",
    "timestamp": "2026-03-15T12:00:00+00:00"
  }
}

List Vouchers

Retrieve all active, public vouchers for your business.

GET /api/v1/vouchers

Response:
{
  "success": true,
  "data": [
    {
      "id": "abc-123",
      "title": "Afternoon Tea for Two",
      "value": 45.00,
      "price": 25.00,
      "currency": "GBP",
      "valid_days": 365,
      "status": "active",
      "stock_limit": 100,
      "allow_custom_amount": false
    }
  ]
}

Validate a Voucher Code

Look up a purchased voucher by its redemption code to check status and remaining balance.

GET /api/v1/voucher/CAFE-ABC12345

Response:
{
  "success": true,
  "data": {
    "code": "CAFE-ABC12345",
    "voucher_title": "Afternoon Tea for Two",
    "face_value": 45.00,
    "amount_paid": 25.00,
    "remaining": 45.00,
    "currency": "GBP",
    "status": "active",
    "is_valid": true,
    "expires_at": "2027-03-15",
    "buyer_name": "John Smith",
    "recipient_name": "Jane Smith"
  }
}

Redeem a Voucher

Redeem a voucher in full or partially. If amount is omitted, the full remaining balance is redeemed.

POST /api/v1/voucher/CAFE-ABC12345/redeem
Content-Type: application/json

{
  "amount": 12.50,
  "notes": "Table 4"
}

Response:
{
  "success": true,
  "data": {
    "code": "CAFE-ABC12345",
    "amount_deducted": 12.50,
    "remaining": 32.50,
    "fully_redeemed": false,
    "currency": "GBP"
  }
}

Validate a Coupon Code

Check a coupon code or trackable claim code.

GET /api/v1/coupon/SUMMER20

Response:
{
  "success": true,
  "data": {
    "coupon_title": "Summer Special",
    "coupon_code": "SUMMER20",
    "discount_type": "percent",
    "discount_value": 20,
    "is_valid": true
  }
}

Redeem a Coupon

Mark a coupon as used via your EPOS or scanner.

POST /api/v1/coupon/SUMMER20/redeem

Response:
{
  "success": true,
  "data": {
    "coupon_title": "Summer Special",
    "discount_type": "percent",
    "discount_value": 20,
    "redeemed_at": "2026-03-15T14:30:00+00:00"
  }
}

Webhooks

Receive real-time HTTP POST notifications when events occur. Configure webhook endpoints from Settings → Webhooks in your dashboard.

Every webhook includes an X-Gifternise-Signature header with an HMAC-SHA256 signature so you can verify authenticity. Failed deliveries are automatically retried with exponential backoff.

Security & Rate Limiting

• 🔒 Bearer Token Authentication — API keys are hashed with SHA256 and never stored in plain text
• ⏱ Rate Limited — 60 requests per minute per API key with Retry-After headers
• 🔑 HMAC-Signed Webhooks — verify every webhook payload with your signing secret
• 🔐 HTTPS Only — all API traffic is encrypted; webhook endpoints must be HTTPS
• 📊 Usage Tracking — last-used timestamps and delivery logs for full visibility

EPOS Integrations

We provide ready-made integration guides for popular EPOS systems:

• Epos Now — validate and redeem vouchers directly from your till
• Lightspeed POS — scan and process voucher codes at checkout

The API is standard REST/JSON, so it works with any system that can make HTTP requests — custom websites, mobile apps, kiosks, or third-party automation tools like Zapier.