Coupons Entity

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
}

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.

Aspect	Coupons	Promotions
Activation	Customer enters code	Automatic
Distribution	Earned or shared	System applies
Use Case	Targeted offers, loyalty rewards	Cart-based discounts

Coupon APIs

Complete API reference

Coupon Tutorial

Implementation guide

Getting Started

General

Experiences

More

Coupon Types

Coupon Properties

Example Coupon

Coupon Lifecycle

Coupon Operations

Generate from Points

Validate and Lock

Use in Order

Coupons vs Promotions

Coupon APIs

Coupon Tutorial

​Coupon Types

​Coupon Properties

​Example Coupon

​Coupon Lifecycle

​Coupon Operations

​Generate from Points

​Validate and Lock

​Use in Order

​Coupons vs Promotions

​Related Resources

Coupon APIs

Coupon Tutorial

Coupon Types

Coupon Properties

Example Coupon

Coupon Lifecycle

Coupon Operations

Generate from Points

Validate and Lock

Use in Order

Coupons vs Promotions

Related Resources