Skip to main content
Events represent customer actions tracked in Gameball. Every meaningful action—adding items to cart, watching a video, completing a purchase—can be captured as an event with optional metadata to power reward campaigns and personalized messaging.

​
Event Structure

An event consists of:
  1. Event Name: Identifies the action (e.g., profile_completed, song_liked)
  2. Event Metadata: Optional details about the action

​
Basic Event

{
  "events": {
    "profile_completed": {}
  },
  "customerId": "customer_123"
}

​
Event with Metadata

{
  "events": {
    "add_to_cart": {
      "product_id": "231402",
      "product_title": "iPhone 12",
      "price": 1350.00,
      "category": "Mobile Phones",
      "vendor": "Apple"
    }
  },
  "customerId": "customer_123"
}

​
Best Practices

​
Event Naming Conventions

Use past tense for event names to indicate actions that have already occurred: ✅ Good Examples:
  • song_liked - indicates the song was already liked
  • profile_completed - the profile completion action finished
  • video_watched - the video viewing is complete
❌ Avoid:
  • like_song - present tense, unclear if action completed
  • complete_profile - imperative form
  • watch_video - present tense
Using past tense makes it clear the action has completed, which is important for campaigns that trigger after specific events occur.

​
Events vs Orders

Orders are special events. When you use the Orders API, Gameball automatically creates a place_order event. You don’t need to manually track order events.
Use Events API for: Custom actions (likes, shares, views), non-purchase interactions
Use Orders API for: E-commerce purchases, cashback, redemption

​
Event-Based Campaigns

Events power campaigns through the Gameball dashboard:
  • Reward Campaigns: “Award 100 points for first add_to_cart event”
  • Communication Campaigns: “Send message when add_to_cart includes specific category”
  • Event Engine Operators: Equals, Different Values, Accumulative Total, Repeated Value

Tracking Events Tutorial

Implementation guide with examples

Send Events API

API endpoint documentation