Discounts And Promotions

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_abc', quantity: 1 }],
  discount_codes: ['WELCOME10', 'BLACKFRIDAY20', 'LOYALTY5'],
  customer: { email: 'user@example.com' },
  return_url: 'https://yoursite.com/return'
});

async function validateDiscount(code, productId) {
  try {
    const discount = await client.discounts.retrieveByCode(code);
    
    // Check expiration
    if (discount.expires_at && new Date(discount.expires_at) < new Date()) {
      return { valid: false, reason: 'Code expired' };
    }
    
    // Check usage limit
    if (discount.usage_limit && discount.times_used >= discount.usage_limit) {
      return { valid: false, reason: 'Code exhausted' };
    }
    
    // Check product eligibility
    if (discount.restricted_to.length > 0) {
      if (!discount.restricted_to.includes(productId)) {
        return { valid: false, reason: 'Code not valid for this product' };
      }
    }
    
    return { valid: true, discount };
  } catch (error) {
    return { valid: false, reason: 'Code not found or unavailable' };
  }
}

// Usage
const result = await validateDiscount('SUMMER2025', 'pdt_abc');
if (result.valid) {
  console.log('Discount applies:', result.discount.amount);
} else {
  console.log('Cannot apply:', result.reason);
}

await client.discounts.update('dsc_existing', {
  preserve_on_plan_change: true,
});

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  // Omit discount_codes. Existing discounts configured with
  // preserve_on_plan_change: true carry forward.
});

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  discount_codes: ['UPGRADE20'], // replaces old discounts
});

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_basic',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  discount_codes: [], // empty array removes all discounts
});

// WRONG: client-side only
if (code.length > 0) {
  applyDiscount(code);
}

// CORRECT: server-side validation
try {
  const discount = await client.discounts.retrieveByCode(code);
  if (isEligible(discount)) {
    // proceed with checkout
  }
} catch (error) {
  // Unknown or unavailable code; reject the checkout request.
}

// Both codes may not apply if they have conflicting restrictions
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_basic', quantity: 1 }],
  discount_codes: ['PREMIUM_ONLY', 'BASIC_ONLY'], // one or both may fail
  return_url: 'https://yoursite.com/return'
});

// WRONG: removes all discounts
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  discount_codes: [], // this clears discounts
});

// CORRECT: preserves discounts whose preserve_on_plan_change property is true
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  // omit discount_codes
});

// WRONG: assumes code is always valid
const discount = await client.discounts.retrieveByCode(code);
applyDiscount(discount);

// CORRECT: catch unknown codes, then check expiration and usage
try {
  const discount = await client.discounts.retrieveByCode(code);
  if (discount.expires_at && new Date(discount.expires_at) < new Date()) {
    showError('Code expired');
  } else if (discount.usage_limit && discount.times_used >= discount.usage_limit) {
    showError('Code exhausted');
  } else {
    applyDiscount(discount);
  }
} catch (error) {
  showError('Code not found');
}

// Applies to first 3 billing cycles of any subscription
const discount = await client.discounts.create({
  type: 'percentage',
  amount: 1500,
  code: 'FIRST_3_MONTHS',
  subscription_cycles: 3,
});

// Expires on a specific date, regardless of billing cycles
const discount2 = await client.discounts.create({
  type: 'percentage',
  amount: 1500,
  code: 'SUMMER_ONLY',
  expires_at: '2025-08-31T23:59:59Z',
});