Customer.io Node.js Client

Common errors

• Customer.io API returned status 400: Bad Request

  cause 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

  cause 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>`.

Warnings

• breaking The 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`.
• gotcha When 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' });`).
• gotcha Using 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.
• gotcha The `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.
• gotcha Customer.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 });`

Install

• npm install customerio-node npm
• yarn add customerio-node yarn
• pnpm add customerio-node pnpm

Imports

• TrackClient
  wrong:

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

  correct:

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

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

  import RegionUS from 'customerio-node';

  correct:

  import { RegionUS } from 'customerio-node';

  Region constants are named exports. Do not use default import.
• ApiClient
  wrong:

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

  correct:

  import { ApiClient } from 'customerio-node';

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

Quickstart

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();