Check gift card balance

Look up a gift card by code and check its validity, balance, expiry and maximum-usage rules. Accessible with both publishable (tybrite_pk_*) and secret (tybrite_sk_*) API keys.

The valid flag is true only when the gift card is active, has a positive balance, and has not expired.

Responses are cached at the edge for ~30s and support ETag revalidation via If-None-Match.

GET /v1/gift-cards/check

Check gift card balance

cURL

curl --request GET \
  --url https://api.tybritelabs.com/v1/gift-cards/check \
  --header 'Authorization: Bearer <token>'

200

{
  "valid": true,
  "balance": 10000,
  "status": "active",
  "expiry_date": "2026-03-31",
  "maximum_usage_percentage": null,
  "gift_card": {
    "id": "f1c4a2b3-8d77-4e0a-9b6c-2e3f5a8d1c44",
    "code": "V5G6-4N7H-9P2R-8W1S",
    "balance": 10000,
    "initial_balance": 10000,
    "currency": "KES",
    "status": "active",
    "expiry_date": "2026-03-31",
    "customer_id": "aeaae40a-71e2-4fb8-862e-c37a34a2f651",
    "issued_date": "2025-12-17",
    "last_used_date": null,
    "maximum_usage_percentage": null,
    "redemption_count": 0,
    "created_at": "2025-12-17T07:43:31.304672+00:00",
    "updated_at": "2026-02-24T08:48:13.548922+00:00"
  }
}

Authorizations

Authorization · string · header · required

API Key Authentication

Use your API key in the Authorization header:

Authorization: Bearer tybrite_sk_live_YOUR_KEY

Key Types:

Secret Keys (Server-Side Only):

• Format: tybrite_sk_live_* (production) or tybrite_sk_test_* (sandbox)
• Full read/write access to all endpoints
• ⚠️ NEVER expose in client-side code or public repositories
• Required for: write operations, authentication, payment verification, AI recommendations

Publishable Keys (Client-Safe):

• Format: tybrite_pk_live_* (production) or tybrite_pk_test_* (sandbox)
• Read-only access (GET requests only, plus POST semantic search)
• ✅ Safe for client-side JavaScript, mobile apps, and public code
• Allowed for: browsing products, search, CMS content, pricing queries

Endpoint-Specific Requirements:

• Authentication endpoints (/v1/auth/*): Secret key required
• Payment verification (POST /v1/payments/verify): Secret key required
• AI Recommendations (POST /v1/recommendations): Secret key required
• Semantic Search (POST /v1/search): Both key types allowed (read-only operation)
• All write operations: Secret key required
• All read operations: Both key types allowed

Using a publishable key for restricted operations returns 403 Forbidden.

Query Parameters

code · string · required

The unique gift card code to look up (e.g. V5G6-4N7H-9P2R-8W1S).

fields · string

Comma-separated list of fields to include in the embedded gift_card object.

Allowed Fields:

• id, code, balance, initial_balance, currency, status
• expiry_date, customer_id, issued_date, last_used_date
• maximum_usage_percentage, redemption_count
• created_at, updated_at

Unknown field names will return a 400 error.

Response

200

application/json

Success

valid · boolean

True when the gift card is active, has balance > 0, and is not expired.

balance · number

status · enum<string>

Available options: active, full_redeemed, inactive

expiry_date · string<date> | null

maximum_usage_percentage · number | null

gift_card · object

Show child attributes