Promotions

const { promotions, pagination } = await client.promotions.listPromotions({
  status: 'active',
  cartTotal: '120.00',
  limit: 50,
  fields: 'id,name,type,value,min_purchase,image'
});

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

const promo = await client.promotions.getPromotion({
  id: 'promotion_uuid',
  fields: 'name,type,value,min_purchase,image' // Optional
});

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

const promo = await client.promotions.getPromotion({
  id: 'promotion_uuid',
  expand: 'products',
});

if (promo.type === 'bundle') {
  for (const item of promo.bundle_products_resolved ?? []) {
    if (!item.product) continue; // product no longer available
    console.log(`${item.product.name} ×${item.quantity} — ${item.product.image}`);
    // item.product = { product_id, name, price, image, category }
  }
}

if (promo.type === 'bogo') {
  const buy  = promo.bogo_required_products_resolved ?? [];
  const free = promo.bogo_free_products_resolved ?? [];
  // render "Buy <buy[].product.name>, get <free[].product.name> free"
}

const promo = await client.promotions.getPromotion({ id: 'promotion_uuid' });
// without expand, products are ids only:
// returns promo.bundle_products = [{ productId, quantity, discountedPrice }]

if (promo.type === 'bundle') {
  const items = await Promise.all(
    (promo.bundle_products ?? []).map(async (b) => ({
      ...b,
      product: await client.products.getProduct({ id: b.productId }),
    }))
  );
  // render each item.product with its b.discountedPrice
}

const result = await client.promotions.calculatePromotionDiscount({
  id: 'promotion_uuid',
  requestBody: {
    cart: [
      { product_id: 'prod_a', quantity: 2, price: 25.00 },
      { product_id: 'prod_b', quantity: 1, price: 40.00 },
    ],
  },
});

if (result.eligible) {
  console.log(`You save $${result.discount}`);   // e.g. 9.00
  const total = 90.00 - result.discount;          // apply it to your cart total
} else {
  console.log(`Not eligible: ${result.reason}`);  // e.g. "Minimum purchase of $120 not met"
}

{
  "promotion_id": "promotion_uuid",
  "type": "discount",
  "eligible": true,
  "discount": 9.00,
  "reason": null
}

const result = await client.promotions.calculatePromotionDiscount({
  id: 'promotion_uuid',
  requestBody: {
    cart: [{ product_id: 'prod_a', quantity: 2, price: 25.00 }],
    country: 'GB',
    region: 'Scotland',
  },
});

const best = await client.promotions.calculateBestPromotion({
  requestBody: {
    cart: [
      { product_id: 'prod_a', quantity: 2, price: 25.00 },
      { product_id: 'prod_b', quantity: 1, price: 40.00 },
    ],
  },
});

if (best.promotion) {
  console.log(`Applied "${best.promotion.name}" — you save $${best.discount}`);
  // best.promotion = { id, name, type }
  const total = 90.00 - best.discount;
} else {
  console.log('No promotions apply to this cart.');
}

{ "promotion": null, "discount": 0 }

const { merchant_store_id, promotion_id } = placement; // from getAdSlot / getMarketplaceCollection

// Resolve products in one call:
const promo = await client.promotions.getPromotion({
  id: promotion_id,
  storeId: merchant_store_id,
  expand: 'products',
});
// returns same Promotion shape as above, scoped to merchant_store_id

// Compute the discount against that merchant's cart:
const result = await client.promotions.calculatePromotionDiscount({
  id: promotion_id,
  storeId: merchant_store_id,
  requestBody: { cart: [{ product_id: 'prod_a', quantity: 1, price: 25.0 }] },
});
// returns { promotion_id, type, eligible, discount, reason }

// Or find the best deal among that merchant's promotions:
const best = await client.promotions.calculateBestPromotion({
  storeId: merchant_store_id,
  requestBody: { cart: [{ product_id: 'prod_a', quantity: 1, price: 25.0 }] },
});
// returns { promotion: { id, name, type } | null, discount }