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
| Type | Description | Example |
|---|
percentage_discount | Percentage discount applied to the order total | 10% off |
fixed_discount | Fixed monetary value deducted from the order | $20 off |
fixed_rate_discount | Fixed monetary value issued in a specific currency | 50 SAR off |
free_shipping | Shipping fees waived for the order | Free delivery |
free_product | Specific product added to the order for free | Free gift with purchase |
custom | Custom coupon behavior handled by your integration | Partner-specific logic |
Coupon Properties
| Property | Type | Description |
|---|
code | String | Unique coupon code customers enter |
type | String | Discount type (see above) |
value | Number | Discount value (percentage or amount) |
usageLimit | Number | Maximum uses across all customers |
limitPerCustomer | Number | Uses per customer |
startDate | String (ISO 8601) | When coupon becomes active |
expiryDate | String (ISO 8601) | When coupon expires |
capping | Number | Max discount amount (for percentage) |
minOrderValue | Number | Minimum order total required |
entitledProductIds | Array | Specific products eligible |
entitledVariantIds | Array | Specific variants eligible |
entitledCollectionIds | Array | Product 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
| Step | Description | API |
|---|
| Generation | Create coupon via points or campaign | POST /api/v4.0/integrations/coupons/predefined |
| Validation | Check if coupon is valid | POST /api/v4.0/integrations/coupons/{code}/validate |
| Locking | Reserve for specific transaction | POST /api/v4.0/integrations/coupons/{code}/validate?lock=true |
| Burning | Mark as used | POST /api/v4.0/integrations/coupons/burn |
| Release | Unlock if transaction cancelled | POST /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
}
{
"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 require customer to enter a code.
Promotions apply automatically based on conditions.
| Aspect | Coupons | Promotions |
|---|
| Activation | Customer enters code | Automatic |
| Distribution | Earned or shared | System applies |
| Use Case | Targeted offers, loyalty rewards | Cart-based discounts |
