Server-side Events Tracking

This guide describes how to track events directly from your server. This is useful for backend processes, payment confirmations, or any action that doesn't happen in the user's browser.

Prerequisites

Tracking Setup — Server-side tracking works only when tracking is already set up for your domain (see Tracking Code Setup)
API Token — You need a customerscore-key (API token) generated in your Customerscore application under the API settings section
Tracker Key — You need your public trackerKey (e.g., CS-ABCD1), which can be found in your app settings

Authentication

You need to authenticate your requests using the customerscore-key in the request header. Keep this token secret!

Content-Type: application/json
customerscore-key: "your-generated-key"

Endpoint

Method	URL
POST	`https://api.customerscore.io/api/tracker/track`

Rate Limiting

Maximum of 200 requests per minute. If the limit is exceeded, the response will be:

HTTP status code: 429 Too Many Requests
Header: Retry-After — number of seconds to wait before retrying

Request Body

You can send multiple events (up to 100 events) in a single request. Maximum request body size is limited to 5 MB.

Example Request

curl -X POST "https://api.customerscore.io/api/tracker/track" \
  -H "Content-Type: application/json" \
  -H "customerscore-key: your-generated-key" \
  -d '{
    "trackerKey": "CS-ABCD1",
    "events": [
      {
        "name": "my-event-name",
        "timestamp": 1712123456789,
        "identification": {
          "customer": "cus_456",
          "contact": "con_123"
        },
        "data": {
          "customer": { "my-value": "184" },
          "contact": { "email": "thomas@example.com" }
        }
      }
    ]
  }'

Full Request Body Example

{
  "trackerKey": "CS-ABCD1",
  "events": [
    {
      "name": "my-event-name",
      "timestamp": 1712123456789,
      "identification": {
        "customer": "cus_456",
        "contact": "con_123"
      },
      "data": {
        "customer": { "my-value": "184" },
        "contact": { "email": "thomas@example.com" }
      }
    },
    {
      "name": "your-event-name",
      "timestamp": 1712123456789,
      "identification": {
        "customer": "cus_456",
        "contact": "con_789"
      },
      "data": {
        "customer": { "my-value": "345" },
        "contact": { "email": "peter@example.com", "contact_name": "Peter" }
      }
    }
  ]
}

Field Descriptions

The request body requires a trackerKey and an array of events.

Field	Type	Required	Description
`trackerKey`	string	Yes	Your public tracker key (e.g., `CS-ABCD1`)
`events`	array	Yes	A list of event objects to track. Limit is 100 events per request

Event Object Structure

Each object within the events array must include the following attributes:

Field	Type	Required	Description
`name`	string	Yes	The name of the event (e.g., `subscription_upgraded`)
`timestamp`	number	Yes	The time the event occurred, in milliseconds (Unix timestamp)
`identification`	object	Yes	Identifies the user associated with the event
`data`	object	No	Additional properties to update or associate with the event

Identification Object

Field	Type	Required	Description
`customer`	string	Yes	The external ID of the customer
`contact`	string	No	The external ID of the contact

Data Object

Field	Type	Required	Description
`customer`	object	No	Key-value pairs of attributes to update on the customer level
`contact`	object	No	Key-value pairs of attributes to update on the contact level (e.g., `email`, `contact_name`)

Response Codes

Code	Description
200	The events have been successfully received and forwarded for processing
400	Bad request (e.g., missing required fields, invalid JSON)
401	Unauthorized - Missing or invalid `customerscore-key` in the header
403	Forbidden - The key does not have permission to perform this action
405	Method Not Allowed - Only POST is accepted
429	Too Many Requests - Rate limit exceeded

Tracking Code Setup Metrics & Attributes