{"id":10707,"library":"customerio-node","title":"Customer.io Node.js Client","description":"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.","status":"active","version":"4.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/customerio/customerio-node","tags":["javascript","customerio","node","typescript"],"install":[{"cmd":"npm install customerio-node","lang":"bash","label":"npm"},{"cmd":"yarn add customerio-node","lang":"bash","label":"yarn"},{"cmd":"pnpm add customerio-node","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While CommonJS `require` is shown in the README, ESM `import` is preferred in modern Node.js. Both patterns work.","wrong":"const TrackClient = require('customerio-node').TrackClient;","symbol":"TrackClient","correct":"import { TrackClient } = from 'customerio-node';"},{"note":"Region constants are named exports. Do not use default import.","wrong":"import RegionUS from 'customerio-node';","symbol":"RegionUS","correct":"import { RegionUS } from 'customerio-node';"},{"note":"The `ApiClient` class (introduced around v3.4.0) provides methods for customer lookup, suppression, and exports. It's a named export, distinct from `TrackClient`.","wrong":"const ApiClient = require('customerio-node').Api;","symbol":"ApiClient","correct":"import { ApiClient } from 'customerio-node';"}],"quickstart":{"code":"import { TrackClient, RegionUS } from 'customerio-node';\n\nconst siteId = process.env.CUSTOMERIO_SITE_ID ?? '';\nconst apiKey = process.env.CUSTOMERIO_API_KEY ?? '';\n\nif (!siteId || !apiKey) {\n  console.error('CUSTOMERIO_SITE_ID and CUSTOMERIO_API_KEY environment variables are required.');\n  process.exit(1);\n}\n\nconst cio = new TrackClient(siteId, apiKey, { region: RegionUS });\n\nasync function identifyCustomer() {\n  try {\n    await cio.identify('customer_123', {\n      email: 'customer@example.com',\n      created_at: Math.floor(Date.now() / 1000),\n      first_name: 'Jane',\n      last_name: 'Doe',\n      plan: 'premium'\n    });\n    console.log('Customer identified successfully.');\n  } catch (error) {\n    console.error('Failed to identify customer:', error);\n  }\n}\n\nidentifyCustomer();","lang":"typescript","description":"This quickstart demonstrates how to initialize the Customer.io `TrackClient` and identify a customer with their basic attributes, using environment variables for credentials."},"warnings":[{"fix":"Update your transactional email payloads to use `body_amp` instead of `amp_body`.","message":"The parameter `amp_body` for transactional email requests was renamed to `body_amp` for consistency across Customer.io APIs.","severity":"breaking","affected_versions":">=4.0.0"},{"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' });`).","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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 });`","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"When using `getCustomersByEmail`, query parameters were not being correctly passed to the Customer.io API, resulting in a 400 error.","error":"Customer.io API returned status 400: Bad Request"},{"fix":"When updating, the `id` argument for `cio.identify()` must be formatted as `cio_<cio_id_value>`.","cause":"Attempting to update an existing customer's identifier (e.g., email) without using the `cio_id` prefix for the customer ID.","error":"Attribute update failure in Customer.io"}],"ecosystem":"npm"}