Promotions & Gift Cards

Promotions

Get active promotions for a product (flash sales, seasonal discounts):

const { items } = await client.catalog.getProductPromotions('wireless-headphones');

Promotion Object

{
  id: string;
  name: string;
  type: 'FLASH_SALE' | 'SEASONAL' | 'CLEARANCE' | ...;
  discountType: 'PERCENTAGE' | 'FIXED_AMOUNT';
  discountValue: number;
  endsAt: number | null;  // Unix timestamp — use for countdown timer
}

Countdown Timer

Use endsAt to build a countdown:

const promo = items[0];
if (promo.endsAt) {
  const remaining = promo.endsAt - Date.now();
  const hours = Math.floor(remaining / 3600000);
  // Show "Ends in X hours"
}

Gift Cards

Check Balance

const balance = await client.catalog.checkGiftCard('GC-ABCD-EFGH-IJKL');
// { valid: true, balance: 500, currency: 'CZK' }
// { valid: false, balance: 0, currency: 'CZK' }

Apply to Cart

const cart = await client.cart.applyGiftCard('GC-ABCD-EFGH-IJKL');

Remove from Cart

const cart = await client.cart.removeGiftCard();

Gift card balance is deducted atomically at checkout. If the gift card covers the full order amount, the order is marked as paid immediately.