Skip to main content
Attributes are data points stored about each customer—their name, email, purchase history, and custom business-specific information. These enable personalized campaigns, targeted messaging, and customer segmentation.

​
Attribute Types

​
Standard Attributes

Built-in fields recognized across Gameball:
AttributeTypePurpose
displayNameStringName shown in leaderboards and UI
firstNameStringCustomer’s first name
lastNameStringCustomer’s last name
emailStringEmail address (required for email-based merging)
mobileStringPhone number (required for mobile-based merging)
dateOfBirthStringBirth date for age-based campaigns
genderStringGender for demographic targeting
cityStringCity for location-based campaigns
countryStringCountry for regional targeting
zipStringPostal code
preferredLanguageStringLanguage preference for communications
joinDateStringWhen customer joined
channelStringAcquisition channel (mobile, web, pos, callcenter)

​
Purchase History Attributes

Automatically tracked when using the Orders API:
AttributeTypeDescription
totalSpentNumberLifetime spending total
totalOrdersIntegerNumber of orders placed
avgOrderAmountNumberAverage order value
lastOrderDateStringDate of most recent purchase

​
Custom Attributes

Flexible key-value pairs for business-specific data: 
{
  "customerId": "customer_123",
  "customerAttributes": {
    "displayName": "Sarah Johnson",
    "email": "sarah@example.com",
    "custom": {
      "vip_status": "Gold",
      "subscription_tier": "Premium",
      "favorite_category": "Electronics"
    }
  }
}
Reserved Properties: The Standard Attributes and Purchase History Attributes listed above are reserved and cannot be sent within the custom object. Only send standard attributes at the root level of customerAttributes, and use the custom object exclusively for your business-specific data fields.

​
Setting Attributes

POST /api/v4.0/integrations/customers
{
  "customerId": "customer_123",
  "customerAttributes": {
    "displayName": "Sarah Johnson",
    "email": "sarah@example.com",
    "city": "New York",
    "custom": {
      "membership_level": "Gold"
    }
  }
}
Updating a customer merges the data—existing attributes not included remain unchanged.

​
Use Cases

  • Personalization: Use names and preferences for tailored experiences
  • Segmentation: Target campaigns by demographics, location, or purchase history
  • Channel Merging: Email/mobile attributes unify profiles across channels
  • Campaign Conditions: “Reward VIP customers in NYC with 2x points”

Create/Update Customer

API endpoint for setting attributes

Omni-Channel Handling Guide

Unify customer profiles across channels