> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gameball.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Coupons Entity

> Discount codes that customers earn through loyalty or receive from campaigns

**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

```json theme={null}
{
  "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

```json theme={null}
POST /api/v4.0/integrations/coupons/predefined
{
  "customerId": "customer_123",
  "ruleId": 42
}
```

### Validate and Lock

```json theme={null}
POST /api/v4.0/integrations/coupons/SAVE10/validate
{
  "customerId": "customer_123",
  "lock": true
}
```

**Response**:

```json theme={null}
{
  "isValid": true,
  "lockReference": "lock_ref_456",
  "discountType": "percentage",
  "discountAmount": 10
}
```

### Use in Order

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

***

## Coupons vs Promotions

<Note>
  **Coupons** require customer to enter a code.\
  **Promotions** apply automatically based on conditions.
</Note>

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

***

## Related Resources

<CardGroup cols={2}>
  <Card title="Coupon APIs" icon="code" href="/api-reference/coupons/coupons">
    Complete API reference
  </Card>

  <Card title="Coupon Tutorial" icon="book-open" href="/tutorials/experiences/gameball-discounts-engine/coupons">
    Implementation guide
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.