Registry / communication / customerio-node

customerio-node

library4.3.0jsnpmunverified

The customerio-node package provides an official Node.js client for interacting with the Customer.io Journeys REST API. It allows developers to perform core actions such as identifying customers, tracking events, deleting profiles, and sending transactional emails, SMS, push, and Inbox messages. The current stable version is 4.3.0, with regular patch and minor releases addressing bug fixes and adding new transactional messaging capabilities. Major versions, like v4.0.0, introduce breaking changes, primarily for API consistency. While this client is robust for the Journeys API, for new integrations, Customer.io generally recommends using their Data Pipelines JavaScript client (`@customerio/cdp-analytics-js`), which provides a unified interface across various data sources. This library is designed for Node.js environments and warns against use in alternative runtimes due to potential API differences.

communication http-networking crm-productivity

npm install customerio-node

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CUSTOMERIO-NODE

customerio-node

communicationjavascriptv4.3.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

TrackClient

✓ import { TrackClient } = from 'customerio-node';

✗ const TrackClient = require('customerio-node').TrackClient;

While CommonJS `require` is shown in the README, ESM `import` is preferred in modern Node.js. Both patterns work.

RegionUS

✓ import { RegionUS } from 'customerio-node';

✗ import RegionUS from 'customerio-node';

Region constants are named exports. Do not use default import.

ApiClient

✓ import { ApiClient } from 'customerio-node';

✗ const ApiClient = require('customerio-node').Api;

The `ApiClient` class (introduced around v3.4.0) provides methods for customer lookup, suppression, and exports. It's a named export, distinct from `TrackClient`.

This quickstart demonstrates how to initialize the Customer.io `TrackClient` and identify a customer with their basic attributes, using environment variables for credentials.

import { TrackClient, RegionUS } from 'customerio-node'; const siteId = process.env.CUSTOMERIO_SITE_ID ?? ''; const apiKey = process.env.CUSTOMERIO_API_KEY ?? ''; if (!siteId || !apiKey) { console.error('CUSTOMERIO_SITE_ID and CUSTOMERIO_API_KEY environment variables are required.'); process.exit(1); } const cio = new TrackClient(siteId, apiKey, { region: RegionUS }); async function identifyCustomer() { try { await cio.identify('customer_123', { email: 'customer@example.com', created_at: Math.floor(Date.now() / 1000), first_name: 'Jane', last_name: 'Doe', plan: 'premium' }); console.log('Customer identified successfully.'); } catch (error) { console.error('Failed to identify customer:', error); } } identifyCustomer();

Debug

Known issues

breakingThe parameter `amp_body` for transactional email requests was renamed to `body_amp` for consistency across Customer.io APIs.

fix

Update your transactional email payloads to use `body_amp` instead of `amp_body`.

affects: >=4.0.0

gotchaWhen updating an existing customer's identifier (e.g., email), you must reference the customer using their `cio_id` in the format `cio_<cio_id_value>`. Using any other ID will lead to attribute update failures or create a new profile.

fix

Ensure the `id` passed to `cio.identify()` for updates is prefixed with `cio_` (e.g., `cio.identify(`cio_${customer.cio_id}`, { email: 'new@example.com' });`).

affects: >=3.0.0

gotchaUsing this library with alternative JavaScript runtimes (e.g., Deno, Cloudflare Workers) that are not Node.js may cause issues due to subtle differences in APIs and standard library implementations.

fix

For non-Node.js runtimes, consider using Customer.io's Track and App APIs directly with your runtime's built-in HTTP client or the React Native SDK if applicable.

affects: >=3.0.0

gotchaThe `cio.destroy(id)` method deletes a person but does not suppress them. This means the person can be re-added to Customer.io. If permanent suppression is desired, a different method is required.

fix

If you need to suppress a person, use `cio.suppress(id)` instead of `cio.destroy(id)` to prevent them from being re-added and to comply with privacy regulations.

affects: >=3.0.0

gotchaCustomer.io accounts can be in different regions (US or EU). If you do not explicitly specify your region when initializing the client, it defaults to `RegionUS`. Incorrect region configuration can lead to data routing issues or logging data in the wrong region.

fix

Always explicitly set the `region` option in the `TrackClient` constructor to `RegionUS` or `RegionEU` to match your Customer.io account's configured region: `new TrackClient(siteId, apiKey, { region: RegionEU });`

affects: >=3.0.0

Errors

Common errors & fixes

Customer.io API returned status 400: Bad Request

When using `getCustomersByEmail`, query parameters were not being correctly passed to the Customer.io API, resulting in a 400 error.

fix

This issue was fixed in `v3.5.0` of the `customerio-node` client. Ensure you are on version `3.5.0` or higher. If the problem persists, double-check the email format and other query parameters.

Attribute update failure in Customer.io

Attempting to update an existing customer's identifier (e.g., email) without using the `cio_id` prefix for the customer ID.

fix

When updating, the `id` argument for `cio.identify()` must be formatted as `cio_<cio_id_value>`.

Upgrade

Version history

4.3.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

46 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/customerio/customerio-node ↗

packagehttps://www.npmjs.com/package/customerio-node ↗

homepagehttps://customer.io ↗