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.