Contents: [ Installing the Library , Sending Events , Combining Anonymous and Identifiable User Data , Storing User Profiles , Tracking Revenue , Additional Resources ]
[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: ''

Combining Anonymous and Identifiable User Data

It's important to send the same distinct_id with each event that an individual user triggers. Mixpanel determines the user performing an event by the distinct_id sent with that event. If the same event is sent twice with different distinct_ids, then Mixpanel ties those events to different users.

It can be more convenient to refer to a user by an identifier other than the distinct_id, especially if it is randomly generated. You can create an alias as an additional identifier for the user, therefor keeping a randomly generated distinct_id consistent.

An alias is a string stored in a Mixpanel lookup table that connects to the distinct_id. Any data sent to Mixpanel with an alias as the distinct_id writes to disk using the alias's corresponding anonymous distinct_id.

As a result you can identify a user by an authenticated id in the form of an alias without changing the distinct_id that is ultimately written in Mixpanel servers. Read more about identity management here.

// Create an alias for an existing distinct id
mixpanel.alias('distinct_id', 'your_alias');

Typically, you only call mixpanel.alias() when the user first signs up and a new internal id maps to them. Once written, aliases are not editable.


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:

Is this article helpful?



Please sign in to leave a comment.