Discounts and promotion codes - Zahlo Merchant Developer Docs

Create coupons with a percentage or fixed minor-unit amount, then decide where a coupon can be used. A promotion code is customer-facing; the coupon is the underlying rule. Validate eligibility, duration, currency, expiry, and usage limits on the server.

Apply a coupon to a checkout

const checkout = await createCheckoutSession({
  lineItems: [{ priceId: "price_demo_1001", quantity: 1 }],
  couponId: "coupon_demo_1001",
  amountMinor: 1710,
  currency: "EUR",
  metadata: { orderId: "order_1001", discountId: "coupon_demo_1001" },
});

The example total is illustrative. Your server must calculate the discount from the current catalog and persist the pre-discount amount, discount amount, and final amount. Never trust a discount amount posted by the browser.

Checkout behavior

If customer-entered promotion codes are enabled, show a clear invalid, expired, or ineligible message and preserve the original cart. Recalculate after quantity, shipping address, currency, or tax changes. Use the same idempotency key when retrying the unchanged session creation request.

Refunds and reporting

Store the discount inputs with the order so a later partial refund can explain how the captured amount was formed. A refund is based on the payment amount, not a newly calculated catalog total.