Common Fields (Customer.io): the data mapping that makes retention automations actually fire

Overview

If you’re sending data into Customer.io, “common fields” are the difference between a clean retention engine and a constant stream of “why didn’t this person enter the flow?” debugging. If you want a second set of eyes on your data mapping before you scale cart recovery or repeat-purchase journeys, book a strategy call—it’s usually faster than chasing edge cases after the fact.

Common fields are Customer.io’s expected, standardized person attributes (and a few system-style fields) that it uses for identity, deliverability, compliance, and segmentation. When you map them correctly at ingestion time, your triggers and segments behave predictably—especially when you’re stitching together web events, Shopify/OMS data, and ESP/SMS consent.

How It Works

In retention programs, most “automation issues” aren’t messaging problems—they’re data-entry problems. Common fields act like the canonical schema Customer.io recognizes, so when data enters the platform (via Track API, Pipelines, SDKs, imports, or an integration), Customer.io knows which attributes are identity keys, which ones are channel permissions, and which ones are timestamps it can reliably compute against.

• Identity resolution leans on common identifiers. At minimum, you need a stable id (your internal customer ID) and usually email and/or phone. If those aren’t consistently set, events land on anonymous profiles or duplicate people—then your cart recovery flow triggers on the “wrong” profile (or not at all).
• Segmentation depends on standardized fields being typed correctly. Timestamps like created_at need to be real timestamps (not strings like “2026/03/25”), and booleans need to be booleans (not “true” as text). If types drift, “purchased in the last 30 days” and “new customer” segments get unreliable.
• Channel eligibility and compliance are enforced through these fields. If unsubscribe / consent fields aren’t mapped the way Customer.io expects, you’ll either over-message (risk) or under-message (revenue leak). This shows up most often with SMS where phone exists but consent state is missing or inconsistent.
• Event-to-person attachment is only as good as the person record. A cart_updated event without a resolvable identifier (or with a stale email) won’t attach to the right person, so your “abandoned cart after 2 hours” trigger never fires for that shopper.

Real D2C scenario: A shopper starts checkout on mobile, then completes purchase on desktop. If your web events identify by email only at checkout, the earlier cart events may remain anonymous. When you later send order_completed tied to a known customer id, you’ve now got two profiles—one with cart events, one with purchase history—so your winback and post-purchase cross-sell segments break. Correctly setting common identifiers early (and merging anonymous activity) prevents this.

Step-by-Step Setup

The goal here is boring but critical: every source that sends data into Customer.io should agree on the same identity keys and should map the same “common fields” consistently. Do this once, and your retention workflows stop behaving like a mystery novel.

1. Pick your canonical person identifier.
   Decide what id will be (Shopify customer ID, your internal user ID, etc.). Use the same value across Track API, server events, and any pipeline/integration. Avoid using email as the primary ID if you can—emails change.
2. Standardize the core common fields you’ll always set.
   At minimum for D2C retention: id, email (if you email), phone (if you SMS), created_at (customer created timestamp), and your consent/unsubscribe state. Decide which system is the source of truth for each (Shopify, Attentive, Postscript, your CDP, etc.).
3. Map fields at ingestion (don’t “fix it later” in Journeys).
   If you’re using an integration/pipeline, map incoming fields to Customer.io’s common fields in that connector’s field mapping. If you’re using the Track API, ensure your /identify calls set these attributes on the person record consistently.
4. Ensure timestamps are real timestamps and in the same unit.
   Customer.io commonly expects Unix timestamps (seconds) or ISO-8601 depending on the endpoint/tooling. Pick one format per ingestion method and stick to it. A single milliseconds-vs-seconds mismatch can push created_at 1000x into the future and wreck “new customer” segments.
5. Handle anonymous-to-known transitions.
   If you track pre-checkout behavior, implement anonymous event tracking and then merge anonymous activity when the shopper identifies (email capture, account creation, checkout). This is where cart recovery accuracy is won or lost.
6. Validate with a real person record.
   Create a test customer, send identify + a few events (viewed product, added to cart, started checkout), then confirm in Customer.io that (a) events attach to the same profile, and (b) the profile shows the expected common fields with correct types.

When Should You Use This Feature

You don’t “use” common fields like a campaign feature—you rely on them any time you care about segmentation accuracy and trigger reliability. In practice, the brands that invest here are the ones that can confidently scale automations without constantly adding exceptions.

• Cart recovery that depends on identity resolution. If your cart events come from the browser but your customer record lives in Shopify, common identifiers and correct email/phone mapping determine whether the cart flow hits the right person.
• Repeat purchase and replenishment timing. You need accurate created_at and purchase timestamps (often as events) to build segments like “first-time buyers 21–35 days post-purchase” without drift.
• Reactivation and winback suppression. Common fields plus consistent purchase events let you exclude recent buyers, refunded orders, or suppressed contacts so winback doesn’t cannibalize margin or annoy active customers.
• Multi-channel orchestration (email + SMS). Reliable email, phone, and consent state prevents “SMS sent to someone who never opted in” or “email skipped because the profile looks unsubscribed due to a bad field mapping.”

Operational Considerations

Common fields are simple on paper, but the operational reality is messy: multiple tools, multiple IDs, and multiple definitions of “subscribed.” If you want segments and triggers you can trust, you need to treat data-in as a system, not a one-time setup.

• One person, one truth (or you’ll get duplicates). If Shopify sends id=123 and your site sends id=email, Customer.io can’t reliably unify. Pick a canonical id, then attach email/phone as attributes.
• Consent state needs a single source of truth. Decide whether SMS consent lives in your SMS tool, Shopify, or your CDP—and mirror it into Customer.io in a consistent field. The most common failure is “phone exists” but consent is missing, so teams either under-send (lost revenue) or hack around it (risk).
• Type drift breaks segments silently. A boolean field that arrives as “TRUE” (string) from one source and true (boolean) from another can cause segment conditions to miss people. Normalize at ingestion.
• Event timing vs. attribute timing matters. If your purchase comes in as an attribute update instead of an event, you lose ordering and “within X hours” logic. Keep behavioral moments (purchase, refund, shipment) as events; keep stable descriptors (email, phone, created_at) as attributes.
• Backfills can flood triggers. If you import people and set created_at to “now” for historical customers, every “welcome” or “new customer” segment lights up. Backfill with true historical timestamps and gate automations with additional conditions.

Implementation Checklist

Before you trust any retention automation, run this checklist against every data source feeding Customer.io. It’s the fastest way to prevent flaky triggers and segment surprises.

• Canonical person id defined and used across all data-in methods
• email and/or phone mapped consistently (same formatting rules every time)
• created_at populated with the true customer creation timestamp (correct unit + timezone handling)
• Consent/unsubscribe state mapped from a single source of truth
• Anonymous web events implemented (if you rely on browse/cart behavior) and merge strategy confirmed
• Key retention events (added_to_cart, checkout_started, order_completed, refunded) standardized with consistent naming + required properties
• Field types validated (timestamps, booleans, numbers) using real sample payloads
• Test profile verified in Customer.io: one profile, all events attached, segments match expectations

Expert Implementation Tips

Most retention teams don’t lose revenue because they lack flows—they lose it because the data feeding those flows is inconsistent. These are the operator moves that keep Customer.io predictable as you scale.

• Identify early, not late. Capture email (or another stable identifier) as soon as possible—email capture modal, SMS capture, account creation—so cart and product-view events attach to the eventual buyer.
• Normalize phone numbers to E.164 at the edge. Don’t wait until it’s inside Customer.io. If one system sends “(555) 123-4567” and another sends “+15551234567”, you’ll fight duplicates and SMS eligibility issues.
• Use events for lifecycle moments; use attributes for state. “Order completed” should be an event with order_id, value, items. “VIP tier” can be an attribute. This keeps segmentation flexible and avoids losing history.
• Design segments around what you can guarantee. If you can’t reliably capture checkout_started, don’t build your recovery program around it—use added_to_cart + time window until you fix tracking.
• Protect automations from backfill noise. Add a guardrail condition like “person created_at is after integration launch date” or “event occurred after X” when you’re importing historical data.

Common Mistakes to Avoid

These are the mistakes that repeatedly show up when D2C brands wire multiple tools into Customer.io. They’re also the ones that quietly tank deliverability, segmentation, and revenue attribution.

• Using email as id in one place and a numeric customer ID in another. This creates duplicates and splits event history across profiles.
• Sending cart events without an identifier and never merging anonymous activity. Your cart recovery becomes “best effort” instead of deterministic.
• Milliseconds vs. seconds timestamps. This single bug can invalidate every “within the last X days” segment.
• Overwriting good data with nulls. One integration sends phone=null and wipes a previously valid phone number—suddenly SMS audiences shrink for no apparent reason.
• Inconsistent event naming across platforms. “Order Completed” vs “order_completed” vs “purchase” forces you to build brittle trigger logic and increases orchestration overhead.
• Consent modeled as a custom field with inconsistent values. If one system uses “subscribed” and another uses “true”, you’ll mis-segment channel eligibility.

Summary

If your data-in mapping is clean, Customer.io becomes a reliable retention engine: segments stay stable, triggers fire when they should, and multi-channel orchestration doesn’t require constant patching.

If it’s messy, you’ll spend your time debugging duplicates, missing events, and broken “new vs returning” logic instead of improving LTV.

Implement Common Fields with Propel

When teams tighten up common fields, we usually see cart recovery and repeat purchase programs get simpler overnight—because you stop building workarounds for data gaps. If you’re aligning multiple sources feeding Customer.io (Shopify + web events + SMS consent + support/returns), it’s worth pressure-testing the schema and identity rules before you scale.

If you want an operator-level review of your data-in setup—IDs, anonymous merges, timestamp hygiene, and consent mapping—book a strategy call and we’ll walk through the exact places retention automations tend to break.