Skip to main content

​
Implement Points Redemption in Your App

Redemption allows customers to convert loyalty points into discounts, wallet credit, or order-based savings.
While the iOS SDK handles balance display, the backend handles all redemption logic for security. This page summarizes the SDK responsibilities and includes core logic extracted from the full Redemption Integration Tutorial. For the end-to-end journey, flows, and business logic, refer to:
👉 Points Redemption Tutorial

​
Redemption Architecture (Short Summary)

Gameball supports two primary redemption paths:

1. Direct Points Redemption

Customer redeems points directly (e.g., wallet value or fixed value rewards).
Your backend calls the Redeem API and updates the customer’s balance.

2. Checkout Redemption

Customer applies points during checkout.
Your backend calls the Order API (with redeemed points + discount values).
Both paths are fully documented with diagrams in the
Redemption Integration Tutorial.

​
SDK Role vs Backend Role

SDK Handles

  • Fetching customer balance
  • Showing points in UI
  • Updating UI after redemption
  • Sending orders (Track Order API wrapper)

Backend Handles

  • Validating redemption
  • Fraud prevention
  • Calculating discount
  • Calling Redeem API
  • Applying discount to the cart/order
  • Returning final result to the app
Never create redemptions directly from the iOS app.
Always call the Redeem API from your backend.

​
Step 1: Fetch Customer Balance (via SDK)

Use the SDK to show the balance before redemption. 
import Gameball

Gameball.shared.getCustomerBalance(for: "customer-123") { result in
    switch result {
    case .success(let balance):
        print("Available: \(balance.availablePoints)")
        print("Pending: \(balance.pendingPoints)")
    case .failure(let error):
        print(error.localizedDescription)
    }
}

​
Step 2: User Chooses a Redemption Amount

This is purely UI-level. Examples:
  • “Redeem 500 points”
  • “Apply maximum available points”
  • “Redeem enough points to reach 50% discount”
Your UI collects the desired amount and sends it to your backend.

​
Step 3: Backend Creates the Redemption Transaction

Your backend must:
1

Validate the selected points

Ensure the requested redemption amount is allowed and the customer has enough points.
2

Call the Redeem API

Use /transactions/cashback-and-redemptions/redeem to deduct points and create a redemption transaction.
3

Return discount info to the app

Your backend returns:
  • success/failure
  • discount amount
  • updated balance
  • any validation errors
Tutorial reference: 👉 Direct Redemption Flow →

​
Step 4: App Updates UI Based on Backend Response

Example app implementation: 
func redeemPoints(_ pointsToRedeem: Int) {
    yourBackendAPI.createRedemption(
        customerId: "customer-123",
        points: pointsToRedeem
    ) { result in
        switch result {
        case .success(let response):
            if response.success {
                self.showSuccessMessage()
                self.updateBalance()
            } else {
                self.showError(response.message)
            }
        case .failure(let error):
            self.showError(error.localizedDescription)
        }
    }
}

​
Checkout-Based Redemption (Order API)

For e-commerce checkout flows (cart, items, subtotals), use Order API through the SDK’s sendOrder() method. 
let order = OrderRequest(
    orderId: "order-123",
    customerId: "customer-123",
    amount: 149.99,
    currency: "USD",
    status: "paid",
    redeemedPoints: 500,
    discountAmount: 50.0
)

Gameball.shared.sendOrder(order) { result in
    // Handle result
}
Tutorial reference: 👉 **Checkout ****Redemption Flow **→

​
Redemption Scenarios (Summary)

Fixed Points Redemption

Customer redeems a fixed amount of points for a fixed-value reward.
Backend calls Redeem API → updates wallet.

Percentage / Flexible Redemption

The customer chooses how many points to apply.
Backend calculates the discount and calls the Redeem API.

Checkout Discount Redemption

Points reduce the order total.
Backend calls Order API.

Full Wallet Use

The customer uses all available points.
Backend performs full validation.
For visual diagrams & deeper flows: 👉 **Full **Points Redemption Tutorial