> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gameball.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> Customer actions that trigger rewards, campaigns, and personalized experiences

**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

```json theme={null}
{
  "events": {
    "profile_completed": {}
  },
  "customerId": "customer_123"
}
```

### Event with Metadata

```json theme={null}
{
  "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

<Tip>
  Using past tense makes it clear the action has completed, which is important for campaigns that trigger after specific events occur.
</Tip>

***

## Events vs Orders

<Note>
  **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.
</Note>

**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

***

## Related Resources

<CardGroup cols={2}>
  <Card title="Tracking Events Tutorial" icon="book-open" href="/tutorials/experiences/tracking-events">
    Implementation guide with examples
  </Card>

  <Card title="Send Events API" icon="code" href="/api-reference/events/send-events">
    API endpoint documentation
  </Card>
</CardGroup>