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

# Events Capture API

> Documentation for Linkrunner Event Capture API

This documentation is for tracking custom events from your backend only! For tracking events from your app please go through the [Flutter](https://docs.linkrunner.io/sdk/flutter/usage#tracking-custom-events) or [React Native](https://docs.linkrunner.io/sdk/react-native/usage#tracking-custom-events) documentation.

<Note>
  Events are only stored and displayed for attributed users. The user must have been registered via the `.signup` function in one of the [SDKs](/sdk/flutter#user-registration) for their events to appear on Linkrunner. To attribute a test user, follow the [Integration Testing](/testing/integration-testing) guide. You can verify your events are being captured on the [Events Settings](https://dashboard.linkrunner.io/dashboard/settings/events) page. For capturing revenue, it is recommended to use the [capture-payment](/api-reference/revenue-tracking) API instead of capture-event.
</Note>

## Base URL

```
https://api.linkrunner.io/api/v1
```

## Authentication

Generate your server key from [https://dashboard.linkrunner.io/settings?s=data-apis](https://dashboard.linkrunner.io/settings?p_id=4\&s=data-apis)

In the request header add the below attribute:

```
linkrunner-key: YOUR-SERVER-KEY
```

## Capture Event

```
POST: /capture-event
```

### Request Body

```json theme={null}
{
  "event_name": "product_viewed",
  "event_data": {
    "product_id": "ABC123",
    "category": "electronics",
    "amount": 249.99,
    "currency": "USD",
    "is_featured": true
  },
  "user_id": "user_12345"
}
```

| Parameter   | Type   | Description                                               |
| ----------- | ------ | --------------------------------------------------------- |
| event\_name | string | **Required**. Name of the event to track                  |
| event\_data | object | **Optional**. Additional data associated with the event   |
| user\_id    | string | **Required**. User identifier to associate with the event |

### Responses

1. **201** Event captured successfully
2. **400** Missing required parameters
3. **401** Invalid server key

#### Sample Response

Upon successful event capture, the API returns:

```json theme={null}
{
  "msg": "Event capture request received!",
  "status": 200,
  "data": null
}
```

## Common Event Names

Here are some common event names you might want to track:

| Event Name             | Description                        |
| ---------------------- | ---------------------------------- |
| `purchase_initiated`   | User starts a purchase             |
| `purchase_completed`   | User completes a purchase          |
| `item_viewed`          | User views an item/product         |
| `cart_added`           | User adds item to cart             |
| `checkout_started`     | User starts checkout               |
| `search_performed`     | User performs a search             |
| `content_viewed`       | User views content                 |
| `level_completed`      | User completes a level (for games) |
| `achievement_unlocked` | User unlocks an achievement        |
| `user_referred`        | User refers someone                |

## Revenue Sharing with Ad Networks

To enable revenue sharing with ad networks like Google Ads and Meta, include an `amount` parameter as a number in your custom event data. This allows the ad networks to optimize campaigns based on the revenue value of conversions:

```json theme={null}
{
  "event_name": "purchase_completed",
  "event_data": {
    "product_id": "ABC123",
    "category": "electronics",
    "amount": 149.99
  },
  "user_id": "user_12345"
}
```

<Note>
  For revenue sharing with ad networks to work properly, ensure the `amount`
  parameter is passed as a number, not as a string.
</Note>

## Best Practices

1. **Consistent naming**: Use consistent naming conventions for your events (snake\_case is recommended)
2. **Structured data**: Include structured data with each event to get more insights
3. **Meaningful events**: Track events that provide valuable insights into user behavior
4. **Data efficiency**: Don't include sensitive or unnecessary data in event payloads

## Example

### Tracking a Purchase Event

```javascript theme={null}
// Using fetch API
fetch("https://api.linkrunner.io/api/v1/capture-event", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "linkrunner-key": "YOUR-SERVER-KEY",
  },
  body: JSON.stringify({
    event_name: "purchase_completed",
    event_data: {
      order_id: "ORD-12345",
      product_ids: ["P-001", "P-002"],
      total_amount: 125.99,
      currency: "USD",
      payment_method: "credit_card",
    },
    user_id: "user_12345",
  }),
})
  .then((response) => response.json())
  .then((data) => console.log(data))
  .catch((error) => console.error("Error:", error));
```

## Error Handling

The API will return appropriate HTTP status codes along with error messages when issues occur:

* **400 Bad Request**: Check your request parameters
* **401 Unauthorized**: Verify your server key
* **429 Too Many Requests**: You've exceeded the rate limit, please try again later
* **500 Internal Server Error**: Contact support if this persists

For any help please reach out to [support@linkrunner.io](mailto:support@linkrunner.io)

## Meta Ecommerce Events

If you are tracking Ecommerce events (like `add_to_cart` or `view_content`) to sync with Meta Catalog Sales, **you must first map your custom event with the standard commerce event in the Linkrunner Dashboard** before sending the event.

*Note: Any event you want to send for an add to cart action should be mapped with **AddToCart** for Commerce Event Manager. For example, map **add\_to\_cart** with **AddToCart**.*

*Similarly, any event you want to send for viewing a product should be mapped with **ViewContent**. For example, map **item\_viewed** with **ViewContent** or **view\_content** with **ViewContent**.*

While you can include any custom attributes in the `event_data` object, Meta requires specific fields for ecommerce events in order to correctly attribute catalog sales and optimize campaigns.

### Example Ecommerce Payload

Here is an example of the exact `event_data` structure you need to send for Meta Commerce Manager:

For comprehensive details on each field requirement, refer to our [Meta Commerce Manager](/ecommerce-manager/meta-commerce-manager#understanding-event_data) documentation.

```json theme={null}
{
  "event_name": "add_to_cart",
  "event_data": {
    "content_ids": ["whshct4mwc"],
    "contents": [
      {
        "id": "whshct4mwc",
        "quantity": 2,
        "item_price": 1000
      }
    ],
    "content_type": "product",
    "currency": "INR",
    "value": 2000.0,
    "num_items": 2,
    "order_id": "order_id_1234"
  },
  "user_id": "user_12345"
}
```

To verify your events are being correctly received by Meta, please follow our [Testing Ecommerce Events](/ecommerce-manager/meta-commerce-manager#testing-ecommerce-events) guide.