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
}

Show a live countdown only when the merchant opted in (showCountdown); otherwise render the static end date. Server-render the initial remainder (pass the server clock down) so hydration does not flicker, tick once per second and remove the timer at zero. Keep tickers off product cards; one timer on the product page is enough:

const promo = items[0];
if (promo.endsAt && promo.showCountdown) {
  const remaining = promo.endsAt - serverNow; // then tick client-side
  // "Ends in 2 d 14 h 03 m"
} else if (promo.endsAt) {
  // static: "until 20. 7."
}

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.

Purchase a gift card

Customers can buy a gift card directly (no cart involved). The purchase creates a regular order; the code is generated and emailed to the recipient only after the order is paid:

const { data } = await client.catalog.purchaseGiftCard({
  amount: 1000,                        // whole currency units, 50 to 50000
  buyerEmail: '[email protected]',     // gets the order confirmation
  recipientEmail: '[email protected]',// gets the code once paid
  recipientName: 'Jana',               // optional
  personalMessage: 'Všechno nejlepší!',// optional, shown in the email
  paymentMethodId: onlineMethod.id,    // optional, from catalog.listPaymentMethods()
});

// data:
// {
//   orderId, orderNumber,
//   grandTotal, currency,
//   paymentRedirectUrl,  // hosted gateway URL, redirect the customer;
//                        // null for offline methods (order awaits payment)
// }

Amounts are validated server-side (integer, 50 to 50000).
Skip cash-on-delivery methods in the picker, a virtual code has nothing to deliver against.
Exactly one gift card is generated per paid order, no matter how many payment notifications arrive.