Gift Cards

Reference for the GiftCardsService class in the Tybrite SDK.

The GiftCardsService class (accessed via client.giftCards) manages the checking and redemption of store-issued gift cards.

Methods

listGiftCards

Retrieve all gift cards owned by a specific customer. This is used for displaying a user’s digital wallet in their account dashboard.

customerId is strictly required for this endpoint to identify which wallet to retrieve. In addition, an xAuthToken (the customer’s session JWT) must be supplied so the gateway can verify the requester owns that wallet.

const { gift_cards } = await client.giftCards.listGiftCards({
  customerId: 'customer-uuid',
  xAuthToken: customerSession.access_token, // Required — customer JWT
  fields: 'code,balance,status,expiry_date' // Optional field filtering
});

gift_cards.forEach(gc => {
  console.log(`GC: ${gc.code} | Balance: ${gc.balance}`);
});

When listing gift cards for a customer, the resolved xAuthToken JWT must match the customerId parameter. Otherwise the gateway returns 403. This means a leaked publishable key alone cannot enumerate another customer’s gift cards — the customer’s session token is required.

---

checkGiftCard

Retrieve the current balance and status of a gift card using its code. Because gift cards operate as bearer instruments (like cash), this endpoint deliberately does not require a customer ID.

This allows both registered users and guest checkout users to check balances.

const details = await client.giftCards.checkGiftCard({
  code: 'TYB-GIFT-123-456',
  fields: 'balance,status,expiry_date' // Optional
});

console.log(`Remaining Balance: ${details.balance}`);
console.log(`Status: ${details.status}`); // 'active', 'redeemed', or 'expired'

No customer auth required — the gift card code itself is the credential.

---

🛡️ Secure Redemption Architecture

Tybrite does not expose a standalone redemption endpoint for gift cards. This architectural decision prevents financial race conditions (double-spending) and ensures that all gift card deductions are natively tied to a unified accounting ledger and order generated during checkout.

To redeem a gift card, pass the code and amount during the order creation process:

const order = await client.orders.createOrder({
  idempotencyKey: 'checkout-123',
  xTimestamp: timestamp,
  xSignature: signature,
  requestBody: {
    // ...other order details...
    gift_card_redemption: { 
      code: 'TYB-GIFT-123-456', 
      amount: 5000 
    }
  }
});

This ensures the gift card balance is only deducted if the main order succeeds.

Card Lifecycle

Gift cards in Tybrite move through three states:

• Active: Valid for use and has a non-zero balance.
• Redeemed: The balance has been fully utilized.
• Expired: The card has passed its expires_at date and can no longer be used, regardless of balance.

---

To let customers pay for partial orders with gift cards, use checkGiftCard to see the available balance first, then include it in the gift_card_redemption object when calling createOrder.

---

Authentication Flow

listGiftCards requires the customer’s session JWT in addition to your API key. Obtain it via the AuthenticationService and pass it as xAuthToken:

// 1. Sign the customer in (magic link, OTP, or password)
const session = await client.authentication.signIn({
  requestBody: {
    email: '[e-mail]',
    password: 'their-password'
  }
});

// 2. Use the returned access token to list their gift cards
const { gift_cards } = await client.giftCards.listGiftCards({
  customerId: session.user.id,
  xAuthToken: session.access_token
});

The gateway validates that the JWT’s subject matches the requested customerId before returning any wallet contents.

Response Codes

Code	Meaning
200	Success.
400	Missing required customer_id (on listGiftCards).
401	Missing or invalid xAuthToken or API key.
403	Customer token does not match the customer_id.
404	Gift card not found (on checkGiftCard).