Vouchers & Gift Cards

Access vouchers and gift cards.

List Vouchers

GET /v1/vouchers

Authentication

Requires an API key with the promotions:read scope.

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
per_page	integer	15	Items per page (max 100)
status	string	-	Filter by status: active, redeemed, expired
issued_from	string	-	Only cards issued on or after this day, YYYY-MM-DD in the shop's time zone
issued_to	string	-	Only cards issued on or before this day, YYYY-MM-DD in the shop's time zone

Response (200 OK)

{
  "data": [
    {
      "id": 1,
      "code": "GC-ABC123XYZ",
      "original_value": 100.00,
      "remaining_value": 75.00,
      "currency": "USD",
      "valid_from": "2025-12-25T00:00:00+00:00",
      "valid_until": "2026-12-25T23:59:59+00:00",
      "status": "active",
      "source": "widget",
      "purchaser": {
        "name": "John Doe",
        "email": "john@example.com"
      },
      "recipient": {
        "name": "Jane Doe",
        "email": "jane@example.com",
        "personal_message": "Happy Birthday! Enjoy a day at the beach."
      },
      "is_expired": false,
      "is_redeemable": true,
      "payment_status": "paid",
      "sold_through": "booking_page",
      "amount_paid": 100.00,
      "issued_on": "2025-12-19",
      "created_at": "2025-12-20T00:00:00+00:00",
      "updated_at": "2026-01-15T10:30:00+00:00"
    },
    {
      "id": 2,
      "code": "GC-DEF456ABC",
      "original_value": 50.00,
      "remaining_value": 0.00,
      "currency": "USD",
      "valid_from": "2025-06-01T00:00:00+00:00",
      "valid_until": "2026-06-01T23:59:59+00:00",
      "status": "redeemed",
      "source": "admin",
      "purchaser": {
        "name": "Mike Smith",
        "email": "mike@example.com"
      },
      "recipient": null,
      "is_expired": false,
      "is_redeemable": false,
      "payment_status": "paid",
      "sold_through": "counter",
      "amount_paid": 50.00,
      "issued_on": "2025-06-01",
      "created_at": "2025-06-01T00:00:00+00:00",
      "updated_at": "2025-08-15T14:00:00+00:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 15,
    "total": 25,
    "total_pages": 2,
    "request_id": "req_abc123",
    "timestamp": "2026-01-15T12:00:00+00:00"
  }
}

Response Fields

Field	Type	Description
id	integer	Unique identifier
code	string	Voucher code
original_value	float	Original voucher value
remaining_value	float	Remaining balance
currency	string	ISO 4217 currency code
valid_from	string|null	Start date (ISO 8601)
valid_until	string|null	Expiry date (ISO 8601)
status	string	active, redeemed, or expired
source	string	admin (made in the app), widget (bought online), api, refund (issued for a cancelled booking) or import (brought across from another system)
purchaser	object	Purchaser details
recipient	object|null	Recipient details (if gift)
is_expired	boolean	Whether voucher has expired
is_redeemable	boolean	Whether voucher can be used
payment_status	string	paid, partial, unpaid, or imported (paid in another system; can be redeemed)
sold_through	string	How the card was issued: booking_page (bought online), counter (sold at the POS), api, staff (added on the Vouchers page), refund_credit (credit for a refunded booking) or imported
amount_paid	float	Money taken for the card. 0 for a refund credit, an imported card, or a staff card with no payment recorded
issued_on	string	The day the card was issued, YYYY-MM-DD in the shop's time zone
created_at	string	ISO 8601 datetime
updated_at	string	ISO 8601 datetime

Status Values

Status	Description
active	Voucher has remaining balance and is valid
redeemed	Voucher has been fully used
expired	Voucher validity period has ended

Errors

Status	Code	Description
401	authentication_required	No API key provided
401	invalid_api_key	Invalid API key
403	insufficient_scope	API key lacks promotions:read scope

Example Request

curl -X GET "https://app.equipdash.com/api/v1/vouchers?status=active" \
  -H "Authorization: Bearer eqd_live_abc123xyz789..."