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

# Gameball POS Integration (v4)

> Complete guide to integrate Gameball with your point-of-sale (POS) system using REST APIs

This guide walks you through integrating Gameball's loyalty program with your point-of-sale (POS) system using REST APIs, so you can deliver a consistent, rewarding experience to your in-store shoppers without a mobile app or separate interface.

> [!NOTE]
>
> Whether you're operating in retail chains, mall kiosks, or standalone stores, Gameball's REST APIs plug loyalty directly into your existing POS workflow, no third-party apps or extra overhead.

## What You Can Do

* **Identify customers** by registering new ones or recognizing existing ones at checkout
* **Display loyalty balance** so customers see their points and what they're worth
* **Reward purchases** with points and campaigns in real time
* **Redeem points** for discounts at checkout, securely and quickly
* **Refund orders** and automatically restore the customer's points
* **Track events and referrals** for additional engagement (optional)

## The End-to-End Checkout Flow

Most POS integrations follow the same sequence at checkout. This is the path the core guide pages walk through, in order:

```mermaid theme={null}
sequenceDiagram
    participant C as Cashier / POS
    participant G as Gameball API
    C->>G: GET balance (identify customer)
    alt Customer not found
        C->>G: POST create customer
        G-->>C: Customer profile
    end
    G-->>C: Balance, points value, expiring points
    C->>C: Display balance to customer
    opt Customer redeems points
        C->>G: POST hold points
        G-->>C: holdReference
    end
    C->>G: POST order (with holdReference if redeeming)
    G-->>C: rewardedPoints, pointsRedeemed
    C->>C: Show earned points
```

## Integration Guide

> [card] [Getting Started & API Setup](https://docs.gameball.co/installation-guides/v4/pos/getting-started.md)
>
> Requirements, credentials, environments, and choosing your customer ID

> [card] [Identify the Customer](https://docs.gameball.co/installation-guides/v4/pos/customer-management.md)
>
> Get or create customers at checkout

> [card] [Show Customer Balance](https://docs.gameball.co/installation-guides/v4/pos/customer-balance.md)
>
> Retrieve and display customer loyalty balance

> [card] [Track Orders & Earn Points](https://docs.gameball.co/installation-guides/v4/pos/track-orders.md)
>
> Submit in-store orders to award loyalty points

> [card] [Redeem Points at Checkout](https://docs.gameball.co/installation-guides/v4/pos/integrate-redemption.md)
>
> Let customers apply points as a discount

> [card] [Refund Order](https://docs.gameball.co/installation-guides/v4/pos/refund-order.md)
>
> Refund or cancel orders and restore customer points

> [card] [Fetch Order Details](https://docs.gameball.co/installation-guides/v4/pos/fetch-order-details.md)
>
> Retrieve order transaction history and customer activities

> [card] [Track Events](https://docs.gameball.co/installation-guides/v4/pos/track-events.md)
>
> Track customer events and actions at your POS

> [card] [Track Referrals](https://docs.gameball.co/installation-guides/v4/pos/track-referrals.md)
>
> Implement referral tracking and rewards

> [card] [Go-Live Checklist](https://docs.gameball.co/installation-guides/v4/pos/go-live-checklist.md)
>
> Verify your integration before going live

## Requirements

* **POS System**: Must support API integration (REST API calls)
* **Network**: Internet connectivity for API calls
* **Authentication**: Gameball API key and secret
* **QR Scanner** (Optional): For QR code-based customer verification

## How POS Integration Differs from Mobile SDKs

Unlike mobile SDKs, POS integration:

* Uses **REST APIs** instead of native SDKs
* Requires **server-side API calls** from your POS backend
* Focuses on **checkout workflows** rather than app experiences
* Supports **QR code verification** for customer identification
* Enables **real-time point redemption** during checkout


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