Behio Storefront SDK
Catalog & Products

Promotions & Gift Cards

Active promotions, gift card balance check and purchase

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

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.

Require another category in the cart

The admin create/update promotion contract accepts cartRequiredCategoryIds. An empty array keeps the existing unconditional behavior. A nonempty array requires at least one positive-quantity cart product in any listed category. The categories must belong to the same shop. The target scope is separate: for example, target the keychain category and require a painting-set category.

This condition supports simple PERCENTAGE and FIXED_AMOUNT promotions; order-level tiers and other discount mechanisms are rejected. Cart contents, including bundle components, determine eligibility on every cart and checkout read. Removing the qualifying product removes the saving. Catalog batches, product promotion lists and listing badges do not present this conditional saving as an unconditional sale price. Customer-entered codes retain the platform's existing composition policy; verify the intended offer together with any configured code before activation.

A quantity condition in other categories

The merchant's cartRequiredCategoryIds chooses qualifying categories, separately from the discounted target categories. cartRequiredCategoryQuantity sets the minimum total qualifying units and defaults to1. Count each positive cart product quantity once, even when it belongs to several required categories; include positive bundle components and the public category context of variants. For example, a10% keychain offer with minimum1 and a higher-priority20% offer with minimum2 recompute when the cart changes. Multiple different models and multiple units of one model both qualify. Priority selects one per-product offer; these two percentages are not added together.

The cart, shipping threshold and checkout use the actual cart contents. A catalog batch containing the same models does not unlock this conditional price.

On this page