Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.shopi.lk/llms.txt

Use this file to discover all available pages before exploring further.

​
shop.checkout.validatePromo(params)

Validates a promo code and returns the calculated discount amount. Call this when the customer applies a promo code — before placing the order. 
const result = await shop.checkout.validatePromo({
  code: 'SAVE10',
  subtotal: 5000,
  cart_items: cart,
});

if (result.valid) {
  console.log(result.discount_amount); // e.g. 500
  console.log(result.message);         // e.g. "10% discount applied!"
} else {
  console.log(result.error);           // e.g. "This promo code has expired"
}

​
Parameters

ParamTypeRequiredDescription
codestring✅The promo code string entered by customer
subtotalnumber❌Cart subtotal — required for minimum order checks
cart_itemsCartItem[]❌Required for product-specific promo codes

​
Response

{
  valid: boolean;
  error?: string;         // present when valid is false
  message?: string;       // present when valid is true
  discount_amount?: number;
  promo_code?: {
    id: string;           // pass this to createOrder
    code: string;
    discount_type: 'percentage' | 'fixed';
    discount_value: number;
    applies_to: 'all' | 'specific';
  };
}

​
Example — Promo code input UI

promoForm.addEventListener('submit', async (e) => {
  e.preventDefault();
  const code = promoInput.value.trim();
  if (!code) return;

  applyBtn.disabled = true;
  promoFeedback.textContent = 'Checking...';

  const subtotal = cart.reduce((s, i) => s + i.price * i.quantity, 0);

  const result = await shop.checkout.validatePromo({
    code,
    subtotal,
    cart_items: cart,
  });

  if (result.valid && result.discount_amount) {
    promoFeedback.className = 'success';
    promoFeedback.textContent = result.message ?? 'Promo applied!';

    // Show discount line in order summary
    discountLine.textContent = `-${formatPrice(result.discount_amount)}`;
    totalLine.textContent = formatPrice(subtotal - result.discount_amount);

    // Store for order creation
    appliedPromo = result;
  } else {
    promoFeedback.className = 'error';
    promoFeedback.textContent = result.error ?? 'Invalid promo code';
    appliedPromo = null;
  }

  applyBtn.disabled = false;
});

​
Passing promo to createOrder

// After validatePromo succeeds, pass the ID and amount to createOrder
const order = await shop.checkout.createOrder({
  // ...other fields
  promo_code_id: appliedPromo.promo_code?.id,
  discount_amount: appliedPromo.discount_amount,
});
Always pass both promo_code_id and discount_amount to createOrder. Passing only one will result in incorrect order totals.