Skip to main content
Coupons are discount codes customers redeem for benefits during checkout. They can be generated by converting loyalty points, earned through reward campaigns, or created for promotional purposes.

​
Coupon Types

TypeDescriptionExample
percentage_discountPercentage discount applied to the order total10% off
fixed_discountFixed monetary value deducted from the order$20 off
fixed_rate_discountFixed monetary value issued in a specific currency50 SAR off
free_shippingShipping fees waived for the orderFree delivery
free_productSpecific product added to the order for freeFree gift with purchase
customCustom coupon behavior handled by your integrationPartner-specific logic

​
Coupon Properties

PropertyTypeDescription
codeStringUnique coupon code customers enter
typeStringDiscount type (see above)
valueNumberDiscount value (percentage or amount)
usageLimitNumberMaximum uses across all customers
limitPerCustomerNumberUses per customer
startDateString (ISO 8601)When coupon becomes active
expiryDateString (ISO 8601)When coupon expires
cappingNumberMax discount amount (for percentage)
minOrderValueNumberMinimum order total required
entitledProductIdsArraySpecific products eligible
entitledVariantIdsArraySpecific variants eligible
entitledCollectionIdsArrayProduct collections eligible

​
Example Coupon

{
  "code": "SAVE10",
  "type": "percentage_discount",
  "value": 10,
  "usageLimit": 100,
  "limitPerCustomer": 1,
  "startDate": "2024-10-20T14:16:00Z",
  "expiryDate": "2025-01-20T15:14:00Z",
  "capping": 50,
  "minOrderValue": 100
}

​
Coupon Lifecycle

StepDescriptionAPI
GenerationCreate coupon via points or campaignPOST /api/v4.0/integrations/coupons/predefined
ValidationCheck if coupon is validPOST /api/v4.0/integrations/coupons/{code}/validate
LockingReserve for specific transactionPOST /api/v4.0/integrations/coupons/{code}/validate?lock=true
BurningMark as usedPOST /api/v4.0/integrations/coupons/burn
ReleaseUnlock if transaction cancelledPOST /api/v4.0/integrations/coupons/release

​
Coupon Operations

​
Generate from Points

POST /api/v4.0/integrations/coupons/predefined
{
  "customerId": "customer_123",
  "ruleId": 42
}

​
Validate and Lock

POST /api/v4.0/integrations/coupons/SAVE10/validate
{
  "customerId": "customer_123",
  "lock": true
}
Response: 
{
  "isValid": true,
  "lockReference": "lock_ref_456",
  "discountType": "percentage",
  "discountAmount": 10
}

​
Use in Order

POST /api/v4.0/integrations/orders
{
  "customerId": "customer_123",
  "orderId": "ORD456",
  "redemption": {
    "couponsLockReference": "lock_ref_456"
  }
}

​
Coupons vs Promotions

Coupons require customer to enter a code.
Promotions apply automatically based on conditions.
AspectCouponsPromotions
ActivationCustomer enters codeAutomatic
DistributionEarned or sharedSystem applies
Use CaseTargeted offers, loyalty rewardsCart-based discounts

Coupon APIs

Complete API reference

Coupon Tutorial

Implementation guide