Customer.io
v1.0.0
OpenAPI 3.1.0

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.

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
      • event
        enum
        const:  
        Product List Viewed
        required

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

        values
        • Product List Viewed
      • type
        enum
        const:  
        track
        required

        The event type. Must be track for event calls.

        values
        • track
      • userId
        Type: string
        required

        The unique identifier for the user.

      • 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.

      • properties
        Type: object

        Properties describing the 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.

Responses
  • application/json
  • application/json
  • 401

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

Request Example for post/track
curl https://cdp.customer.io/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
  }
}'

{}

A successful request returns an empty object response.

Models