Skip to main content
This documentation is for tracking custom events from your backend only! For tracking events from your app please go through the Flutter or React Native documentation.
Events are only stored and displayed for attributed users. The user must have been registered via the .signup function in one of the SDKs for their events to appear on Linkrunner. To attribute a test user, follow the Integration Testing guide. You can verify your events are being captured on the Events Settings page. For capturing revenue, it is recommended to use the capture-payment API instead of capture-event.

​
Base URL

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

​
Authentication

Generate your server key from https://dashboard.linkrunner.io/settings?s=data-apis In the request header add the below attribute: 
linkrunner-key: YOUR-SERVER-KEY

​
Capture Event

POST: /capture-event

​
Request Body

{
  "event_name": "product_viewed",
  "event_data": {
    "product_id": "ABC123",
    "category": "electronics",
    "amount": 249.99,
    "currency": "USD",
    "is_featured": true
  },
  "user_id": "user_12345"
}
ParameterTypeDescription
event_namestringRequired. Name of the event to track
event_dataobjectOptional. Additional data associated with the event
user_idstringRequired. 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: 
{
  "msg": "Event capture request received!",
  "status": 200,
  "data": null
}

​
Common Event Names

Here are some common event names you might want to track:
Event NameDescription
purchase_initiatedUser starts a purchase
purchase_completedUser completes a purchase
item_viewedUser views an item/product
cart_addedUser adds item to cart
checkout_startedUser starts checkout
search_performedUser performs a search
content_viewedUser views content
level_completedUser completes a level (for games)
achievement_unlockedUser unlocks an achievement
user_referredUser 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: 
{
  "event_name": "purchase_completed",
  "event_data": {
    "product_id": "ABC123",
    "category": "electronics",
    "amount": 149.99
  },
  "user_id": "user_12345"
}
For revenue sharing with ad networks to work properly, ensure the amount parameter is passed as a number, not as a string.

​
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

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

​
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 documentation. 
{
  "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 guide.