Promotions

Reference for the PromotionsService class in the Tybrite SDK.

The PromotionsService class (accessed via client.promotions) handles active store discounts, marketing campaigns, and coupon validation logic. Promotions support an image field for displaying visual banners and campaign assets.

Methods

listPromotions

Retrieve a list of promotions based on their lifecycle status. This is useful for building a “Deals” or “Coupons” page on your storefront.

const { promotions, pagination } = await client.promotions.listPromotions({
  status: 'active',
  cartTotal: '10000',
  limit: 50,
  fields: 'id,name,discount_value,discount_type,image'
});

console.log(`Available promotions: ${promotions.length}`);

Filter: cartTotal Providing a cartTotal allows the engine to pre-filter promotions that the customer is actually eligible for based on their current shopping bag value.

---

getPromotion

Fetch full configuration data for a promotion, including its exact discount logic and validity dates.

const promo = await client.promotions.getPromotion({
  id: 'promo-uuid-or-code',
  fields: 'name,discount_value,discount_type,min_purchase,image' // Optional
});

if (promo.image) {
  console.log(`Promotion Banner: ${promo.image}`);
}

---

Data Schema

Promotion Structure

Field	Type	Description
id	uuid	Unique promotion identifier.
name	string	Promotion display name.
type	enum	fixed, discount, bundle, bogo.
image	string	URL of the promotion banner.
discount_value	number	The numerical value of the discount.
discount_type	enum	percentage, fixed.

---

Pro Marketing Tip: Use the image field to build high-impact promotional carousels. By associating visual assets directly with your discount logic, you can ensure that your marketing banners always reflect the current campaign status and validity.

---

Response Codes

All promotion endpoints are GET and accept both publishable and secret keys. The status query parameter is validated against a strict enum.

Code	Meaning
200	Success.
400	Invalid status enum (must be one of active, inactive, scheduled, expired) or malformed query parameter.
401	Invalid or missing API key.
404	Promotion not found (single-resource endpoint only). List endpoint returns 200 with an empty array.
429	Rate limit exceeded.
500	Internal server error.