Contents: [ Installing the Library , Sending Events , Managing User Identity , Storing User Profiles , Tracking Revenue , Additional Resources ]
[ID Merge , Alias, ID Merge , NOTE , Setting Profile Properties, NOTE , Incrementing Numeric Properties, Appending to List Properties]

Visit the Dev Docs

A better version of this page exists at

The Mixpanel Node.js library provides Mixpanel tracking functionality in server-side applications built using Node.js.

Use the HTTP tracking API for server-side applications that do not use Node.js.

Additionally, Mixpanel offers client-side libraries for the following platforms:

The Mixpanel client-side libraries support a wide range of convenience features, and should be the starting point for using Mixpanel in client-side implementations.

The Mixpanel Node.js library will be most useful to you if you need to send data from a Node.js server, or for interacting with Mixpanel APIs in JavaScript outside of the browser (such as importing past events with a script).

Installing the Library

Install the Mixpanel Node.js library and create a Mixpanel instance in order to begin Mixpanel tracking.

Use npm to install Mixpanel in your project by calling npm install mixpanel. The Mixpanel module will be available in the Node project after installing the library.

Next, create a Mixpanel instance and initialize a Mixpanel client to communicate with Mixpanel servers. To do this, grab the Mixpanel factory and create an instance of the Mixpanel client by calling mixpanel.init(YOUR_PROJECT_TOKEN).

The project token is unique to your Mixpanel project. Instructions for finding your project token can be found here.

// grab the Mixpanel factory
var Mixpanel = require('mixpanel');

// create an instance of the mixpanel client
var mixpanel = Mixpanel.init('<YOUR_TOKEN>');

Sending Events

You can track events with mixpanel.track() after initializing a Mixpanel instance.

The mixpanel.track() method takes two arguments, an event name and a properties object which must include the distinct_id.

You have the option to add additional event properties to the call to add detail to that event. Read more about events and properties here.

var Mixpanel = require('mixpanel');
var mixpanel = Mixpanel.init('<YOUR_TOKEN>');

// track an event with optional properties
mixpanel.track('event name', {
    distinct_id: 'unique client id',
    property_1: 'value 1',
    property_2: 'value 2',
    property_3: 'value 3'

Mixpanel determines default geolocation data ($city, $region, mp_country_code) using the IP address on the incoming request. This can have the unintended effect of setting the location of all of your users to the location of your datacenter in server-side implementations.

It is therefore important to pass IP as a property in server-side implementations. Read about best practices for geolocation with server-side implementations.

var Mixpanel = require('mixpanel');
var mixpanel = Mixpanel.init('<YOUR_TOKEN>');

// track an event with optional properties
mixpanel.track('event name', {
    distinct_id: 'unique client id',
    ip: ''

Managing User Identity

Mixpanel groups events sent with different distinct_ids, presenting them in reports as different user event streams. You can connect events with different distinct_ids using alias, identify, or merge, ultimately attributing them to one user.

ID Merge

If a project has ID merge enabled, the $identify event can connect pre- and post-authentication events. If ID merge is not enabled, identify events will not link identities however alias can be used to connect pre and post registration events.


The alias method creates an alias which Mixpanel will use to remap one distinct_id to another. Multiple aliases can point to the same identifier.



A unique identifier that you want to use as an identifier for this user.



The current user identifier.

The following is a valid use of alias:

mixpanel.alias('new_id', 'existing_id');
//You can add multiple id aliases to the existing id
mixpanel.alias('newer_id', 'existing_id')

Aliases can also be chained. You cannot point to multiple identifiers..

ID Merge

If a project does not have ID Merge enabled, the best practice is to call alias once when a unique ID is first created for a user (e.g., when a user first registers for an account).


Aliases don't take effect until the alias request hits the Mixpanel server. Because of this, you'll need to take special care if you're using mixpanel.alias() with a custom consumer, so you can be sure that your alias message arrives before any events or updates associated with the new alias.

Storing User Profiles

You can send user profile updates to Mixpanel in addition to sending events.

Mixpanel can maintain a profile of each of your users, storing information you know about them.

A profile update changes the properties of a user profile, essentially changing the details tied to that profile or creating it if it does not exist.

You can use profiles and user profile properties to explore and segment users by who they are, in addition to what they did with event tracking. You can also use profiles to send messages, such as emails, SMS, or push notifications.

Setting Profile Properties

You can update or create a user profile with mixpanel.people.set(). The first argument is distinct_id, and the second argument is a JSON list of the properties to add to or update the profile with.

The following example sets a "Plan" property with a value "Premium", a first name, a last name, and a created date on the user's profile that has a distinct id of 13793.

Mixpanel automatically creates a new profile if there isn't already a profile with a distinct_id of 13793 in the project already.

If the user with a distinct_id of 13793 already has a property named "Plan" in their profile, the new value "Premium" overwrites the old value of "Free".

// grab the Mixpanel factory
var Mixpanel = require('mixpanel');
var mixpanel = Mixpanel.init('<YOUR_TOKEN>');

// create or update a user in Mixpanel
mixpanel.people.set('13793', {
    $first_name: 'Billy',
    $last_name: 'Bob',
    $created: (new Date('jan 1 2013')).toISOString(),
    plan: 'premium',


Pick your property names wisely. Feel free to use capitalization and spaces in between words.
There are a few limitations:

  • Your property names should not begin with $ or mp_. These properties are reserved for special properties sent by Mixpanel.
  • Your property names cannot begin or end with a space as they will automatically be trimmed.
  • Your property names and values cannot be longer than 255 characters. In practice they should be much shorter than that. Property names get cut off by our user interface at about 20 characters.

Click here to see a list of Mixpanel's reserved user profile properties.

Incrementing Numeric Properties

You can use mixpanel.people.increment() to increment the current value of numeric properties. This is useful when tracking a running count of properties, such as games played, emails sent, or points earned.

// increment a numeric property
mixpanel.people.increment('13793', 'games_played');
// increment a numeric property by a different amount
mixpanel.people.increment('13793', 'points', 15);
// increment multiple properties
mixpanel.people.increment('13793', {'points': 10, 'games_played': 1});

Appending to List Properties

Use mixpanel.people.append() to add an item to an existing list-valued property.

mixpanel.people.append() adds the values passed to it at the end of the list for each named property. Mixpanel creates a list containing one element as its value if the property does not already exist.

// append value to a list
mixpanel.people.append('13793', 'awards', 'Great Player');
// append multiple values to a list
mixpanel.people.append('13793', {'awards': 'Great Player', 'levels_finished': 'Level 4'});

Tracking Revenue

It is possible to track and analyze revenue generated from individual customers.

You can track a single transaction with mixpanel.track_charge(). This call adds transactions to the individual user profile. These values are visible in the Mixpanel Revenue report.

// record a transaction for revenue analytics
mixpanel.people.track_charge('13793', 39.99)

Additional Resources

Visit the Mixpanel-Node repository on GitHub for additional information, such as:

Did this answer your question?



Please sign in to leave a comment.