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”
