List gift cards

Retrieve gift cards belonging to a specific customer, scoped to the authenticated store.

Only active, non-zero balance, non-expired gift cards are returned (sorted by balance descending). Accessible with both publishable (tybrite_pk_*) and secret (tybrite_sk_*) API keys.

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

GET /v1/gift-cards

List gift cards

cURL

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

200

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

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.

Headers

x-auth-token · string

Customer session access_token from /v1/auth/login or /v1/auth/verify-otp. Required when customer_id is supplied so the gateway can prove the caller owns that customer record.

Query Parameters

customer_id · string<uuid> · required

Filter gift cards by customer ID. Required for listing a customer's gift cards.

fields · string

Comma-separated list of fields to include in the response.

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

gift_cards · object[]

Show child attributes