Customer.io NodeJS

A node client for the Customer.io Journeys REST API. If you're new to Customer.io, we recommend that you integrate with our Data Pipelines JavaScript client instead.

Supported Node.js versions

This project is developed for and tested against the versions of Node.js that the Node.js project itself supports — the Current release plus the Active LTS and Maintenance LTS lines. See the Node.js release schedule for details. When a Node.js version reaches end-of-life, support for it is dropped in the next release of this library, which may be a breaking change.

The engines field in package.json reflects the current minimum supported version.

Alternative Node runtimes

As of v5.0.0 the SDK is built on top of standard fetch, so it runs on any runtime that implements the WHATWG fetch standard.

Bun is exercised in CI alongside Node.js, so the supported matrix is:

• Node.js (Current, Active LTS, Maintenance LTS; see Supported Node.js versions above)
• Bun (latest)

Other fetch-compatible runtimes (Deno, Cloudflare Workers, etc.) should work but are not part of our test matrix. If you hit a runtime-specific issue, please open one against the issue tracker.

Installation

npm i --save customerio-node

Usage

Creating a new instance

To start using the library, you first need to create an instance of the CIO class:

const { TrackClient, RegionUS, RegionEU } = require("customerio-node");
let cio = new TrackClient(siteId, apiKey, { region: RegionUS });

Both the siteId and apiKey are required to create a Basic Authorization header, allowing us to associate the data with your account.

Your account region is optional. If you do not specify your region, the default will be the US region (RegionUS). If your account is in the EU and you do not provide the correct region, we'll route requests from the US to RegionEU accordingly. This may cause data to be logged in the US.

Optionally you can specify defaults that will forwarded to the underlying request instance. The node http docs has a list of the possible options.

This is useful to override the default 10s timeout. Example:

const cio = new TrackClient('123', 'abc', {
  timeout: 5000
});

Retries

Requests that fail with a transient error are retried automatically with exponential backoff and jitter. This applies to every client (TrackClient, APIClient, and PipelinesClient). Transient failures are network errors (connection reset/refused, DNS, timeout) and the retryable HTTP status codes 408, 429, 500, 502, 503, 504, 522, and 524. A Retry-After response header is honored when present. Other 4xx responses (e.g. 400, 401, 404, 422) are returned immediately without retrying.

Retries are safe to replay: each call builds its payload once and the exact same request body is reused for every attempt.

Pass a retry object to tune or disable the policy. Any fields you omit fall back to the defaults shown below:

const cio = new TrackClient('123', 'abc', {
  retry: {
    maxRetries: 3, // set to 0 to disable retries entirely
    minTimeoutMs: 200,
    maxTimeoutMs: 5000,
    retryStatusCodes: [408, 429, 500, 502, 503, 504, 522, 524],
    respectRetryAfter: true,
    retryAfterMaxSeconds: 300,
    maxTotalBackoffMs: 30000,
  },
});

The backoff for attempt n (zero-based) is min(maxTimeoutMs, (random() + 1) * minTimeoutMs * 2 ** n). The total time spent sleeping across all retries for a single call is capped at maxTotalBackoffMs; if the next backoff would exceed it, the last error is thrown instead.

---

Using Promises

All calls to the library will return a native promise, allowing you to chain calls as such:

const customerId = 1;

cio.identify(customerId, { first_name: "Finn" }).then(() => {
  return cio.track(customerId, {
    name: "updated",
    data: {
      updated: true,
      plan: "free",
    },
  });
});

or use async/await:

const customerId = 1;

await cio.identify(customerId, { first_name: "Finn" });

return cio.track(customerId, {
  name: "updated",
  data: {
    updated: true,
    plan: "free",
  },
});

---

API reference

Method-level documentation lives in the docs/ folder:

• Track API — TrackClient
• App API — APIClient
• Pipelines (CDP) API — PipelinesClient
• Webhooks — verifyRequestSignature

The full generated TypeScript API reference can be produced with npm run docs (Typedoc).

Further examples

We've included functional examples in the examples/ directory of the repo to further assist in demonstrating how to use this library to integrate with Customer.io

Tests

npm install && npm test

License

Released under the MIT license. See file LICENSE for more details.