Check Voucher Balance

Check the current balance and status of a voucher by its code. This is a read-only operation useful for displaying voucher information to customers.

Endpoint

POST /v1/vouchers/balance

Authentication

Requires an API key with the promotions:read scope.

Request Body

Field	Type	Required	Description
code	string	Yes	Voucher code to check

Example Request

curl -X POST "https://app.equipdash.com/api/v1/vouchers/balance" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "GFT-ABCD-1234"
  }'

Success Response (200 OK)

{
  "data": {
    "code": "GFT-ABCD-1234",
    "original_value": 100.00,
    "remaining_value": 45.00,
    "currency": "USD",
    "status": "active",
    "is_redeemable": true,
    "is_expired": false,
    "is_paid": true,
    "valid_from": "2026-01-01T00:00:00+00:00",
    "valid_until": "2026-12-31T23:59:59+00:00",
    "times_used": 2,
    "total_redeemed": 55.00
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-02-01T10:00:00+00:00"
  }
}

Response Fields

Field	Type	Description
code	string	Voucher code
original_value	number	Original voucher value
remaining_value	number	Current remaining balance
currency	string	Currency code (e.g., USD, EUR, GBP)
status	string	Voucher status: active, redeemed, expired
is_redeemable	boolean	Whether the voucher can currently be used
is_expired	boolean	Whether the voucher has passed its expiry date
is_paid	boolean	Whether payment has been received for the voucher
valid_from	string	ISO 8601 datetime when voucher becomes valid (null if immediate)
valid_until	string	ISO 8601 datetime when voucher expires (null if no expiry)
times_used	integer	Number of times the voucher has been partially redeemed
total_redeemed	number	Total amount redeemed from the voucher

Status Values

Status	Description
active	Voucher has remaining balance and is within validity period
redeemed	Voucher has been fully used (zero balance)
expired	Voucher has passed its expiry date

Redeemability

A voucher is redeemable (is_redeemable: true) when all of the following are true:

• Status is active
• Remaining value is greater than zero
• is_paid is true (payment has been recorded)
• Current date is within valid_from and valid_until range

Error Responses

Invalid Voucher Code (422)

{
  "error": {
    "code": "validation_error",
    "message": "The given data was invalid.",
    "details": [
      {
        "field": "code",
        "message": "Invalid voucher code."
      }
    ]
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

Missing Code (422)

{
  "error": {
    "code": "validation_error",
    "message": "The given data was invalid.",
    "details": [
      {
        "field": "code",
        "message": "The code field is required."
      }
    ]
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

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
422	validation_error	Invalid or missing voucher code

Use Cases

Display Balance to Customer

Show customers their remaining voucher balance before checkout:

async function checkVoucherBalance(code) {
  const response = await fetch('https://app.equipdash.com/api/v1/vouchers/balance', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ code })
  });

  const data = await response.json();

  if (response.ok) {
    console.log(`Balance: $${data.data.remaining_value}`);
    console.log(`Redeemable: ${data.data.is_redeemable}`);
  } else {
    console.error('Invalid voucher code');
  }
}

Check Before Applying to Booking

Verify a voucher before applying it:

async function canApplyVoucher(code, bookingTotal) {
  const response = await fetch('https://app.equipdash.com/api/v1/vouchers/balance', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ code })
  });

  const { data } = await response.json();

  if (!data.is_redeemable) {
    return { canApply: false, reason: 'Voucher is not redeemable' };
  }

  const applicableAmount = Math.min(data.remaining_value, bookingTotal);
  return { canApply: true, applicableAmount };
}

Notes

• This endpoint is read-only and does not modify the voucher
• Use Validate Voucher to check if a voucher can be used for a specific booking amount
• The times_used count increments each time a partial redemption occurs
• Vouchers can be partially redeemed multiple times until the balance reaches zero

Related Resources

• Validate Voucher - Validate a voucher for a specific amount
• Vouchers - List and manage vouchers
• Promotions Overview - Overview of promotions system