Attributes

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:

Attribute	Type	Purpose
`displayName`	String	Name shown in leaderboards and UI
`firstName`	String	Customer’s first name
`lastName`	String	Customer’s last name
`email`	String	Email address (required for email-based merging)
`mobile`	String	Phone number (required for mobile-based merging)
`dateOfBirth`	String	Birth date for age-based campaigns
`gender`	String	Gender for demographic targeting
`city`	String	City for location-based campaigns
`country`	String	Country for regional targeting
`zip`	String	Postal code
`preferredLanguage`	String	Language preference for communications
`joinDate`	String	When customer joined
`channel`	String	Acquisition channel (mobile, web, pos, callcenter)

Purchase History Attributes

Automatically tracked when using the Orders API:

Attribute	Type	Description
`totalSpent`	Number	Lifetime spending total
`totalOrders`	Integer	Number of orders placed
`avgOrderAmount`	Number	Average order value
`lastOrderDate`	String	Date 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

Getting Started

General

Experiences

More

Attribute Types

Standard Attributes

Purchase History Attributes

Custom Attributes

Setting Attributes

Use Cases

Create/Update Customer

Omni-Channel Handling Guide

​Attribute Types

​Standard Attributes

​Purchase History Attributes

​Custom Attributes

​Setting Attributes

​Use Cases

​Related Resources

Create/Update Customer

Omni-Channel Handling Guide

Attribute Types

Standard Attributes

Purchase History Attributes

Custom Attributes

Setting Attributes

Use Cases

Related Resources