Skip to main content
The first step at checkout is identifying the customer so their purchase, points, and redemptions attach to the right profile. You look them up by their customer ID, and create a profile if they’re new.

​
The Get-or-Create Flow

You don’t always have to create customers explicitly. The Track Orders and Track Events APIs auto-create a profile if the customerId doesn’t exist yet. The explicit get-or-create flow below is recommended when you want to show a balance or trigger onboarding campaigns before the order is placed.

​
Step 1: Look Up the Customer

Check if the customer exists by retrieving their balance: 
curl -X GET 'https://api.gameball.co/api/v4.0/integrations/customers/{customerId}/balance' \
  -H 'APIKey: YOUR_API_KEY' \
  -H 'SecretKey: YOUR_SECRET_KEY'
If the customer is found, skip to Show Customer Balance. If not, create them below.

​
Step 2: Create the Customer (if new)

curl -X POST 'https://api.gameball.co/api/v4.0/integrations/customers' \
  -H 'Content-Type: application/json' \
  -H 'APIKey: YOUR_API_KEY' \
  -H 'SecretKey: YOUR_SECRET_KEY' \
  -d '{
    "customerId": "12345",
    "customerAttributes": {
      "displayName": "John Doe",
      "email": "john@doe.com",
      "mobile": "+20123456789"
    }
  }'

{
  "customerId": "12345",
  "name": "John Doe",
  "email": "john@doe.com",
  "mobile": "+20123456789",
  "createdAt": "2025-10-19T12:00:00Z"
}
Behind the scenes, Gameball creates the loyalty profile, triggers any configured onboarding campaigns (such as a welcome bonus), and prepares the profile for earning, tiering, and redemption.

​
Tips & Gotchas

This call is idempotent. If the customer already exists, the profile is updated rather than duplicated, so it’s safe to call on every checkout.
  • Capture at least one contact field (mobile or email) in your POS UI.
  • Call this as soon as you’ve collected the identifier, before checkout.
  • Keep the customerId consistent with every other channel (see Choosing Your Customer ID).