Pipelines API - Ecommerce Events

Ecommerce Semantic Events

This document describes semantic events for ecommerce in the Customer.io Pipelines API.

Semantic events are special payloads for our track endpoint based on the event name. When you send an ecommerce event with a specific name (like Product Viewed or Order Completed), Customer.io and downstream integrations recognize it and handle it appropriately.

With semantic events, you can set up your events and they'll work with any of our destinations that support ecommerce events.

Server addresses: US and EU

Customer.io hosts services in the United States (US) and European Union. Select the appropriate server address for your region.

Region	Server Address
US	https://cdp.customer.io
EU	https://cdp-eu.customer.io

If you're in our EU region, you'll need to specify the EU URL when you initialize our server-side libraries.

Authentication

The Data Pipelines API uses basic authentication with your API key as the username and a blank password.

Server

The base URL for all Data Pipelines calls in our United States (US) region.

Client Libraries

Shell Curl

Track Ecommerce Event

Send ecommerce semantic events to track customer shopping behavior, from browsing products to completing orders.

These semantic events follow standard structures recognized by Customer.io and downstream integrations for ecommerce analytics.

Headers

X-Strict-Mode
enum
const:
1

When set to 1, enables strict validation that returns proper HTTP error codes (400/401) for validation failures. When not set or set to any other value, the API operates in permissive mode, logging errors but returning HTTP 200.
values
- 1

Body

required

application/json

userId
Type: string
required

The unique identifier for the user.

type
enum
const:
track
required

The event type. Must be track for event calls.

values
track
event
enum
const:
Product List Viewed
required

The event name. Must be Product List Viewed for this semantic event.

values
Product List Viewed
timestamp
Type: stringFormat: date-time

The ISO-8601 timestamp when the event occurred. If not provided, Customer.io records the time when the request is received.

properties
Type: object

Properties describing the product list viewed.

context
Type: object · Context

Additional context about the event, such as device information, IP address, user agent, etc. Most of our libraries collect this automatically.

integrations
Type: object · Integrations

Control which integrations receive this event. By default, all enabled integrations receive events.

Responses

application/json
application/json
401

Unauthorized request. Make sure that you provided the right credentials.

post/track

curl https://cdp.customer.io/v1/track \
  --request POST \
  --header 'X-Strict-Mode: 1' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic username:password' \
  --data '{
  "userId": "user_12345",
  "type": "track",
  "event": "Product List Viewed",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "properties": {
    "list_id": "all_shoes",
    "category": "shoes",
    "products": [
      {
        "product_id": "coolshoes-123",
        "sku": "abc-123-xyz",
        "category": "shoes",
        "name": "Cool Shoes",
        "brand": "A Shoe Brand",
        "variant": "red",
        "price": 139.99,
        "quantity": 1,
        "coupon": "NEWUSER20",
        "position": 3,
        "url": "https://www.example.com/product/123",
        "image_url": "https://www.example.com/product/123.jpg"
      }
    ],
    "additionalProperty": null
  },
  "context": {
    "additionalProperty": "anything"
  },
  "integrations": {
    "All": false,
    "Mixpanel": true,
    "Segment": true
  }
}'

Show Schema

{}

A successful request returns an empty object response.

Pipelines API - Ecommerce Events

Ecommerce Semantic Events

Server addresses: US and EU

Authentication

Authentication

Track Ecommerce Event

Models