Tracker: 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 (e.g., via the Tracking code – Quick Setup Guide).
• API Token: You need a customerscore-key (API token) generated in your Customerscore.io 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!

Request header requirements

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

Please ensure to include the generated token in the request header as customerscore-key. Additionally, specify Content-Type: application/json.

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.

API Request Specifications

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

Example of body request

You can send multiple events (up to 100 events) in a single request.

{
    "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"}
            }
        }
    ]
}

Maximum request body size is limited to 5 MB and you can send up to 100 events within single request.

Field Descriptions

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

Event Object Structure

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

• name (String, Required): The name of the event (e.g., "subscription_upgraded").
• timestamp (Number, Required): The time the event occurred, in milliseconds (Unix timestamp).
• identification (Object, Required): Identifies the user associated with the event.
  • customer (String, Required): The external ID of the customer.
  • contact (String, Optional): The external ID of the specific contact.
• data (Object, Optional): Additional properties to update or associate with the event.
  • customer (Object): Key-value pairs of attributes to update on the customer level.
  • contact (Object): Key-value pairs of attributes to update on the contact level (e.g., email, contact_name).

Responses