Coupon types

What each villacoupon3 type does and which response field carries the result. See discount-fields for the full contract and coupon-test-matrix for live examples.

Type	Behaviour	Result lands in
fixed	Flat baht off the cart	cartDiscount
percentage	Percentage off, honours maxDiscountAmount	cartDiscount
bogo	Buy N get 1 free, pools units across SKUs	bogoDiscount
two_for_x	Buy N for a set price, per-set cap	two4Discount
free_shipping	Waives the delivery fee	shippingDiscount + isFreeShipping
shipping	Fixed baht off the delivery fee	shippingDiscount
specific_sku	Percentage off matching SKUs only	specificSkuDiscount

Two ways to express a partial shipping discount

Both of these exist in production data and behave identically:

• shipping with discountValue: 50
• free_shipping with maxDiscountAmount: 50

The second is the one that caused a bug: it is typed as free shipping but is not a full waiver. VillaCoupon3 disambiguates with freeShipping: false. Consumers must read that boolean rather than the type — see 2026-07-29-coupon-test-sheet-failures.

Restrictions

Field	Effect
orderSource	WEB / APP — an app-only coupon rejects a web order
applicableWithNationwide	Whether the coupon applies to nationwide shipping
minOrderAmount	Minimum subtotal; below it the coupon silently doesn’t apply
excludeControlledProducts	Excludes alcohol and similar from the applicable total
maxDiscountAmount	Caps the computed amount
Start / expiry dates	Outside the window the coupon lands in failedCoupons

minOrderAmount is worth calling out when testing: a free-shipping coupon with a 5,000 baht minimum applied to a 365 baht basket produces no discount and no error, which reads as “the coupon is broken”.

Auto-applied promotions

Coupons flagged isPromotion apply without the customer typing a code. The site fetches them via /api/calculatePrice/suggestCoupon and passes them in couponCodeList alongside any typed code. In the test sheet these appear as “no code” with a numeric coupon id.