CI
Commerce Index/Docs
Signals API

Commerce Index Signals

API-first access to brand, product, and market signals derived from Commerce Index events.

Subtitle: Structured, aggregated signals derived from the events you send to Commerce Index.

What Are CI Signals?

Commerce Index Signals (CI Signals) are structured, aggregated signals derived from the events you send to Commerce Index (views, purchases, and later more), as well as cross-brand data where available.

Instead of pulling raw events or building your own aggregation pipelines, you can use CI Signals to answer questions like:

  • "How is my brand performing over the last 30 days?"
  • "Is this product hot, steady, or cold right now?"
  • "What are the key context signals I should know about this SKU or brand before I make a decision?"

CI Signals is designed to be:

API-first

Simple REST endpoints, JSON responses

Opinionated

Includes trends and tiers (up/flat/down, high/medium/low)

Composable

Easy to use in dashboards, BI, agents, internal tools

At launch, CI Signals focuses on brand and product activity using the events you already send via CI Proof.

Available Signal Endpoints (v0)

CI Signals v0 exposes three main endpoints. These can be used independently or together, depending on what you are building.

Brand Signals/api/v1/signals/brand

Aggregated view of brand-level activity: views, purchases, conversion, trends, and top products.

Product Signals/api/v1/signals/product

Activity for a single product: views & purchases, conversion rate, trend vs previous period, and activity tier (high/medium/low) + comment.

Context Signals/api/v1/signals/context

A compact, opinionated summary with a headline, key signals, and optional recommendations. This is the "noise-clearing" API.

Authentication

All Signals endpoints require an API key:

X-CI-Api-Key: <your-api-key>
Content-Type: application/json

You will receive an API key during onboarding. Treat it like any other secret.

API Reference

GET
/api/v1/signals/brand
Brand Signals

Aggregated view of brand-level activity: views, purchases, conversion, trends, and top products.

Typical Uses:

  • •Brand activity overview in your internal dashboards
  • •Monitoring "are we trending up or down" at a glance
  • •Feeding pricing / growth / operations decisions with context

Parameters

brand_idstring
Required
Your CI-assigned brand identifier
windowstringTime window: 1d, 7d, 30d, or 90d (default: 30d)
GET /api/v1/signals/brand?brand_id=brand_xyz&window=30d
X-CI-Api-Key: <your-api-key>
Content-Type: application/json
GET
/api/v1/signals/product
Product Signals

Activity for a single product: views & purchases, conversion rate, trend vs previous period, and activity tier (high/medium/low) + comment.

Typical Uses:

  • •PDP-level decisioning ("is this product hot or cold?")
  • •Merchandising dashboards (finding top movers and underperformers)
  • •Powering UI labels (e.g., "Popular right now") in your own frontend

Parameters

brand_idstring
Required
Your CI-assigned brand identifier
product_idstring
Required
Your product identifier
windowstringTime window: 1d, 7d, 30d, or 90d (default: 7d)
GET /api/v1/signals/product?brand_id=brand_xyz&product_id=prod_123&window=7d
X-CI-Api-Key: <your-api-key>
Content-Type: application/json
POST
/api/v1/signals/context
Context Signals

A compact, opinionated summary with a headline, key signals, and optional recommendations. This is the "noise-clearing" API.

Typical Uses:

  • •In a "Context" sidebar in your CI dashboard
  • •For agents / assistants that need a quick summary before taking action
  • •For internal tools (e.g., a Slack bot that replies with this payload)

Parameters

brand_idstring
Required
Your brand identifier (in body)
product_idstringOptional product ID for product-specific context
countrystringCountry code (default: US)
windowstringTime window (default: 7d)
POST /api/v1/signals/context
X-CI-Api-Key: <your-api-key>
Content-Type: application/json

{
  "brand_id": "brand_xyz",
  "product_id": "prod_123",
  "country": "US",
  "window": "7d"
}

Signal Values Reference

Trend Direction
upMetric increased >5% vs previous period
flatMetric changed <5% vs previous period
downMetric decreased >5% vs previous period
Activity Tier
highAbove average activity for this brand
mediumNormal activity levels
lowBelow average activity

How Signals Are Computed

Signals are derived from the view and purchase events you send via:

  • •The CI JavaScript snippet (Proof integration)
  • •Or server-side /api/collect/product-view and /api/collect/product-purchase endpoints

We aggregate events over the requested window (e.g., last 7 days), then compare them to a previous window to compute trend (up/flat/down).

We compute confidence based on:

  • •Volume of data in that window
  • •Consistency of data over time

As CI expands and more brands integrate, CI Signals will also incorporate category and market-level context.

Next Steps

To start using CI Signals, make sure you have:

  1. Integrated CI Proof (view/purchase events), or
  2. Arranged a data integration with the Commerce Index team

Then:

  1. Get your API key
  2. Call your first Signals endpoint

You can find full API references under:

Examples & Recipes →REST API →FAQ →