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

> Build custom coupon redemption experiences for loyalty points using Gameball APIs

Once your coupon system is configured, the next step is to create intuitive UI components that allow customers to easily view their points and redeem them for coupons. A smooth, engaging couponing experience not only makes it easy for customers to track their progress but also encourages them to redeem their rewards, increasing customer satisfaction and loyalty.

## Using Gameball Widget

The Gameball Widget is a pre-built interface that automatically handles the display and redemption of coupons. It simplifies the integration process by managing the UI and redemption flow for you.

<Steps>
  <Step title="Complete Configuration">
    Ensure all necessary configurations for your coupon system are set up in the Gameball dashboard.
  </Step>

  <Step title="Initialize Widget">
    Integrate the widget into your web application by including the provided widget script. For mobile platforms, use the corresponding SDKs supported by Gameball (Android, iOS, React Native).
  </Step>

  <Step title="Widget Display">
    The widget will display available coupons and provide an option to create new coupons based on the customer's points balance.
  </Step>
</Steps>

<Frame>
  <img src="https://873157020-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FElcuAgxn15Pk6F2fINKe%2Fuploads%2FfvU1MUW1ZMEjXEqgAUOn%2Fimage.png?alt=media&token=e4f0bb01-7abb-40c9-9307-f453db0730d8" alt="Coupons in widget example" />
</Frame>

## Building Your Own Redemption UI

While the Gameball widget offers a quick solution for managing coupon redemptions, some businesses may require more flexibility in design and user experience. If you prefer full control over the look, feel, and flow of the redemption process, building a custom UI is the way to go.

### Viewing Points Balance

Allow customers to view their points for a seamless redemption experience. Call the [Get Customer Balance API](/api-reference/customers/progress/get-customer-balance) and render the response:

```json theme={null}
{
  "pointsBalance": 1330,
  "pointsValue": 200,
  "pendingPoints": 100,
  "pendingPointsValue": 0,
  "totalPositivePoints": 1230,
  "totalPositivePendingPoints": 100,
  "totalNegativePoints": 0,
  "totalNegativePendingPoints": 0,
  "currency": "EGP",
  "pointsName": "Points"
}
```

### Calculating Points Available for Redemption

```text theme={null}
pointsAvailable = pointsBalance - pendingPoints
```

**Example:**

```text theme={null}
pointsAvailable = 1330 - 100 = 1230
```

### Validating Redemption Requests

```javascript theme={null}
function getCustomerBalance(customerUniqueId) {
  var customerBalanceResponse = {
    "pointsBalance": 1330,
    "pointsValue": 200,
    "pendingPoints": 100,
    "pendingPointsValue": 0,
    "totalPositivePoints": 1230,
    "totalPositivePendingPoints": 100,
    "totalNegativePoints": 0,
    "totalNegativePendingPoints": 0,
    "currency": "EGP",
    "pointsName": "Points"
  };

  var customerActualPoints = customerBalanceResponse["pointsBalance"];
  var customerPointsToRedeem = 60; // Points the customer wishes to redeem
  var minimumPointsRequiredToRedeem = 500; // Minimum points needed to redeem

  if (customerPointsToRedeem >= customerActualPoints || customerPointsToRedeem < minimumPointsRequiredToRedeem) {
    // Display an error message to the customer that they cannot redeem points.
  }
}
```

### Allowing Customers to Redeem Points for Coupons

Once customers can view their points, the next step is enabling them to redeem these points for discount coupons.

**Creating a Redemption Page:**

1. Set up a page where customers enter points to redeem
2. Display available points and monetary equivalent
3. Call the [Generate Coupon API](/api-reference/coupons/generate-coupon) with the calculated value:

```json theme={null}
{
  "value": 100,
  "customerId": "customer@gmail.com"
}
```

**Displaying the Discount Code:**

After creating a coupon, show the generated code:

```json theme={null}
{
  "code": "FreeShippingOFF"
}
```

### Showing Available Coupons to Customers

Retrieve customer coupons using the [Get Customer Coupons API](/api-reference/customers/customers#get-customer-coupons) and render a list:

```json theme={null}
[
  {
    "code": "_nqjuejhuy",
    "isUsed": false,
    "value": 11.75,
    "currency": "USD",
    "creationDate": "2022-05-03T11:08:42.298758",
    "couponType": "fixed_rate_settings"
  },
  {
    "code": "1qol7apahr",
    "isUsed": false,
    "value": 10.0,
    "currency": "USD",
    "creationDate": "2022-05-03T11:07:22.718595",
    "couponType": "fixed_rate_settings"
  }
]
```

### Applying Coupons at Checkout

1. Check coupon validity (e.g., ensure `isUsed` is false)
2. Apply coupon logic to compute new totals
3. Prepare and send Order API request with updated values

**Example JSON Request Body:**

```json theme={null}
{
  "customerId": "customer456",
  "orderId": "6253e03b",
  "orderDate": "2023-05-5T16:53:28.190Z",
  "totalPrice": "53.25",
  "totalPaid": "65",
  "totalDiscount": "11.75",
  "totalShipping": "0",
  "totalTax": "0",
  "lineItems": [],
  "discountCodes": ["_NQJUEJHUY"],
  "extra": {
    "paymentMethod": "credit card",
    "billingAddress": "Alabama"
  },
  "redeemedAmount": 11.75,
  "holdReference": null,
  "guest": false
}
```

***

## Related Resources

<CardGroup cols={2}>
  <Card title="Get Customer Balance API" icon="code" href="/api-reference/customers/progress/get-customer-balance">
    Retrieve customer balance including available and pending points
  </Card>

  <Card title="Generate Coupon API" icon="ticket" href="/api-reference/coupons/generate-coupon">
    Create a coupon based on predefined redemption rules
  </Card>

  <Card title="Get Customer Coupons API" icon="list" href="/api-reference/customers/customers#get-customer-coupons">
    Retrieve customer's available coupons
  </Card>

  <Card title="Build Your Own UI" icon="layout" href="/tutorials/experiences/more/build-your-own-ui">
    Back to Build Your Own UI overview
  </Card>
</CardGroup>