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

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