CI
Commerce Index/Docs
Reference

API Reference

Complete API documentation for Commerce Index. All endpoints require authentication via API key and merchant ID headers.

Authentication

All API requests require an API key and merchant ID passed via headers. API keys can be scoped to limit access to specific resources.

// Authentication
// Include these headers with every API request:
const headers = {
  'Content-Type': 'application/json',
  'X-CI-Api-Key': 'your_api_key',       // Required
  'X-CI-Merchant-Id': 'merch_xyz789'    // Required
};

// API keys can be created in the dashboard under
// Settings → API Keys. Each key has scopes that
// control which endpoints it can access:
//
// Scopes: products:read, products:write, deals:read,
//         deals:write, orders:read, orders:write,
//         agents:read, agents:write, health:read,
//         events:write, webhooks:manage

Products

GET
/api/v1/products
1 credit

List all products with pagination and filtering.

Response

{
  "products": [
    {
      "id": "prod_abc123",
      "title": "Wireless Bluetooth Headphones",
      "price": 79.99,
      "compare_at_price": 99.99,
      "inventory": 42,
      "status": "active",
      "ci_score": 87,
      "created_at": "2026-01-10T08:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 156
  }
}

JavaScript Example

const response = await fetch('https://api.commerceindex.ai/v1/products?page=1&per_page=20&status=active', {
  headers: {
    'X-CI-Api-Key': 'your_api_key',
    'X-CI-Merchant-Id': 'merch_xyz789'
  }
});
const data = await response.json();
console.log(data.products);
GET
/api/v1/products/:id
1 credit

Get a single product by ID with full details.

Response

{
  "id": "prod_abc123",
  "title": "Wireless Bluetooth Headphones",
  "price": 79.99,
  "compare_at_price": 99.99,
  "description": "Premium wireless headphones...",
  "inventory": 42,
  "status": "active",
  "ci_score": 87,
  "images": ["https://cdn.example.com/img1.jpg"],
  "variants": [...],
  "created_at": "2026-01-10T08:00:00Z",
  "updated_at": "2026-03-15T12:30:00Z"
}
POST
/api/v1/products
2 credits

Create a new product.

Request Body

{
  "title": "Wireless Bluetooth Headphones",
  "price": 79.99,
  "compare_at_price": 99.99,
  "description": "Premium wireless headphones with ANC",
  "inventory": 100,
  "images": ["https://cdn.example.com/img1.jpg"],
  "tags": ["electronics", "audio"]
}

Response

{
  "id": "prod_new456",
  "title": "Wireless Bluetooth Headphones",
  "price": 79.99,
  "status": "active",
  "created_at": "2026-03-17T10:00:00Z"
}
PUT
/api/v1/products/:id
2 credits

Update an existing product.

Request Body

{
  "price": 69.99,
  "inventory": 85
}

Response

{
  "id": "prod_abc123",
  "title": "Wireless Bluetooth Headphones",
  "price": 69.99,
  "inventory": 85,
  "updated_at": "2026-03-17T10:05:00Z"
}
DELETE
/api/v1/products/:id
1 credit

Delete a product (soft delete).

Response

{ "deleted": true, "id": "prod_abc123" }
POST
/api/v1/products/:id/match
5 credits

Deep match a product against the Commerce Index catalog. Returns matching products across the marketplace.

Request Body

{
  "match_depth": "deep",
  "include_pricing": true,
  "max_results": 10
}

Response

{
  "matches": [
    {
      "product_id": "ci_prod_789",
      "title": "Similar Wireless Headphones",
      "similarity_score": 0.94,
      "price_range": { "min": 59.99, "max": 89.99 },
      "merchant_count": 12
    }
  ],
  "match_confidence": 0.91
}

JavaScript Example

const response = await fetch('https://api.commerceindex.ai/v1/products/prod_abc123/match', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-CI-Api-Key': 'your_api_key',
    'X-CI-Merchant-Id': 'merch_xyz789'
  },
  body: JSON.stringify({
    match_depth: 'deep',
    include_pricing: true,
    max_results: 10
  })
});
const matches = await response.json();
GET
/api/v1/products/:id/similar
3 credits

Find similar products in the catalog based on attributes and CI Score.

Response

{
  "similar": [
    {
      "product_id": "prod_def456",
      "title": "Premium Over-Ear Headphones",
      "price": 89.99,
      "ci_score": 82,
      "similarity": 0.87
    }
  ]
}

Deals

GET
/api/v1/deals
1 credit

List all deals with filtering by status, agent, and date range.

Response

{
  "deals": [
    {
      "id": "deal_xyz789",
      "product_id": "prod_abc123",
      "discount_pct": 20,
      "original_price": 99.99,
      "deal_price": 79.99,
      "status": "active",
      "created_by": "deal_agent",
      "expires_at": "2026-03-20T23:59:59Z"
    }
  ],
  "pagination": { "page": 1, "per_page": 20, "total": 8 }
}
POST
/api/v1/deals
3 credits

Create a new deal on a product.

Request Body

{
  "product_id": "prod_abc123",
  "discount_pct": 20,
  "starts_at": "2026-03-17T00:00:00Z",
  "expires_at": "2026-03-20T23:59:59Z",
  "max_redemptions": 100
}

Response

{
  "id": "deal_new123",
  "product_id": "prod_abc123",
  "discount_pct": 20,
  "deal_price": 79.99,
  "status": "active",
  "created_at": "2026-03-17T10:00:00Z"
}

JavaScript Example

const response = await fetch('https://api.commerceindex.ai/v1/deals', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-CI-Api-Key': 'your_api_key',
    'X-CI-Merchant-Id': 'merch_xyz789'
  },
  body: JSON.stringify({
    product_id: 'prod_abc123',
    discount_pct: 20,
    starts_at: '2026-03-17T00:00:00Z',
    expires_at: '2026-03-20T23:59:59Z',
    max_redemptions: 100
  })
});
PUT
/api/v1/deals/:id
2 credits

Update an existing deal.

Request Body

{
  "discount_pct": 25,
  "expires_at": "2026-03-25T23:59:59Z"
}

Response

{
  "id": "deal_xyz789",
  "discount_pct": 25,
  "deal_price": 74.99,
  "updated_at": "2026-03-17T10:15:00Z"
}
DELETE
/api/v1/deals/:id
1 credit

Cancel/delete a deal.

Response

{ "deleted": true, "id": "deal_xyz789" }

Orders

GET
/api/v1/orders
1 credit

List orders with filtering by status, date range, and deal association.

Response

{
  "orders": [
    {
      "id": "order_123",
      "total": 79.99,
      "currency": "USD",
      "status": "paid",
      "items": [
        {
          "product_id": "prod_abc123",
          "quantity": 1,
          "unit_price": 79.99,
          "deal_id": "deal_xyz789"
        }
      ],
      "created_at": "2026-03-16T14:30:00Z"
    }
  ],
  "pagination": { "page": 1, "per_page": 20, "total": 342 }
}
GET
/api/v1/orders/:id
1 credit

Get a single order with full details.

Response

{
  "id": "order_123",
  "total": 79.99,
  "currency": "USD",
  "status": "paid",
  "customer_ref": "cust_anon_456",
  "items": [...],
  "shipping": { "status": "shipped", "tracking": "1Z999AA10123456784" },
  "created_at": "2026-03-16T14:30:00Z"
}
POST
/api/v1/orders
2 credits

Create/import an order (typically from your e-commerce platform).

Request Body

{
  "external_id": "shopify_order_789",
  "total": 79.99,
  "currency": "USD",
  "items": [
    {
      "product_id": "prod_abc123",
      "quantity": 1,
      "unit_price": 79.99
    }
  ]
}

Response

{
  "id": "order_new456",
  "external_id": "shopify_order_789",
  "status": "created",
  "created_at": "2026-03-17T10:00:00Z"
}

Agents

GET
/api/v1/agents
1 credit

List all configured agents with their status and trust tier.

Response

{
  "agents": [
    {
      "type": "pricing_agent",
      "status": "active",
      "trust_tier": "supervised",
      "approval_mode": "auto",
      "decisions_count": 45,
      "success_rate": 0.89
    },
    {
      "type": "deal_agent",
      "status": "active",
      "trust_tier": "trusted",
      "approval_mode": "auto",
      "decisions_count": 234,
      "success_rate": 0.93
    }
  ]
}

JavaScript Example

const response = await fetch('https://api.commerceindex.ai/v1/agents', {
  headers: {
    'X-CI-Api-Key': 'your_api_key',
    'X-CI-Merchant-Id': 'merch_xyz789'
  }
});
const { agents } = await response.json();
agents.forEach(a => console.log(`${a.type}: ${a.trust_tier} (${a.status})`));
GET
/api/v1/agents/:type
1 credit

Get detailed info for a specific agent type.

Response

{
  "type": "pricing_agent",
  "status": "active",
  "trust_tier": "supervised",
  "approval_mode": "auto",
  "guardrails": {
    "confidence_threshold": 0.85,
    "max_actions_per_hour": 50,
    "max_financial_impact": 1000
  },
  "stats": {
    "total_decisions": 45,
    "success_rate": 0.89,
    "avg_confidence": 0.82,
    "days_active": 12
  }
}
POST
/api/v1/agents/:type/enable
1 credit

Enable an agent.

Response

{ "type": "pricing_agent", "status": "active" }
POST
/api/v1/agents/:type/disable
1 credit

Disable an agent immediately. Cancels pending actions.

Response

{ "type": "pricing_agent", "status": "disabled", "cancelled_actions": 2 }
PUT
/api/v1/agents/:type/guardrails
2 credits

Update guardrails for an agent.

Request Body

{
  "approval_mode": "auto",
  "confidence_threshold": 0.85,
  "max_actions_per_hour": 30,
  "max_financial_impact": 500,
  "trust_tier_auto_upgrade": true
}

Response

{
  "type": "pricing_agent",
  "guardrails": {
    "approval_mode": "auto",
    "confidence_threshold": 0.85,
    "max_actions_per_hour": 30,
    "max_financial_impact": 500,
    "trust_tier_auto_upgrade": true
  },
  "updated_at": "2026-03-17T10:00:00Z"
}
GET
/api/v1/agents/:type/decisions
1 credit

List recent decisions made by an agent.

Response

{
  "decisions": [
    {
      "id": "dec_abc123",
      "action": "price_adjustment",
      "product_id": "prod_abc123",
      "confidence": 0.92,
      "status": "approved",
      "financial_impact": 45.50,
      "created_at": "2026-03-17T09:30:00Z"
    }
  ],
  "pagination": { "page": 1, "per_page": 20, "total": 45 }
}

Health

GET
/api/v1/health/score
1 credit

Get your current CI Health Score with component breakdown.

Response

{
  "score": 87,
  "grade": "A",
  "components": {
    "pricing_accuracy": 92,
    "inventory_health": 85,
    "fulfillment_rate": 88,
    "deal_performance": 83
  },
  "trend": "improving",
  "updated_at": "2026-03-17T08:00:00Z"
}

JavaScript Example

const response = await fetch('https://api.commerceindex.ai/v1/health/score', {
  headers: {
    'X-CI-Api-Key': 'your_api_key',
    'X-CI-Merchant-Id': 'merch_xyz789'
  }
});
const health = await response.json();
console.log(`CI Score: ${health.score} (${health.grade})`);
GET
/api/v1/health/margin-guard
2 credits

Get margin analysis and guard status for your products.

Response

{
  "overall_margin": 0.34,
  "at_risk_products": 3,
  "alerts": [
    {
      "product_id": "prod_abc123",
      "current_margin": 0.08,
      "min_margin": 0.10,
      "recommendation": "Increase price or reduce deal discount"
    }
  ]
}
GET
/api/v1/health/decision-graph
2 credits

Get the decision graph showing agent activity and outcomes over time.

Response

{
  "period": "7d",
  "total_decisions": 156,
  "approved": 142,
  "rejected": 8,
  "pending": 6,
  "daily": [
    { "date": "2026-03-11", "decisions": 22, "success_rate": 0.91 },
    { "date": "2026-03-12", "decisions": 25, "success_rate": 0.88 }
  ]
}

Events

POST
/api/v1/events
1 credit

Submit a custom event to the Commerce Index event pipeline.

Request Body

{
  "type": "product.viewed",
  "data": {
    "product_id": "prod_abc123",
    "source": "homepage_carousel"
  }
}

Response

{
  "event_id": "evt_new789",
  "type": "product.viewed",
  "received_at": "2026-03-17T10:00:00Z"
}
GET
/api/v1/events/types
1 credit

List all available event types and their schemas.

Response

{
  "event_types": [
    { "type": "product.viewed", "description": "Product page was viewed" },
    { "type": "product.purchased", "description": "Product was purchased" },
    { "type": "deal.redeemed", "description": "A deal was used in checkout" },
    { "type": "agent.decision", "description": "Agent made a decision" }
  ]
}

Webhooks

POST
/api/v1/webhooks
1 credit

Register a new webhook endpoint.

Request Body

{
  "url": "https://your-server.com/webhooks/ci",
  "events": ["product.updated", "order.created", "deal.created"],
  "secret": "whsec_your_webhook_secret"
}

Response

{
  "id": "wh_abc123",
  "url": "https://your-server.com/webhooks/ci",
  "events": ["product.updated", "order.created", "deal.created"],
  "status": "active",
  "created_at": "2026-03-17T10:00:00Z"
}
GET
/api/v1/webhooks
1 credit

List all registered webhooks.

Response

{
  "webhooks": [
    {
      "id": "wh_abc123",
      "url": "https://your-server.com/webhooks/ci",
      "events": ["product.updated", "order.created"],
      "status": "active",
      "last_delivery": "2026-03-17T09:45:00Z"
    }
  ]
}
DELETE
/api/v1/webhooks/:id
1 credit

Delete a webhook endpoint.

Response

{ "deleted": true, "id": "wh_abc123" }

What's Next?

Webhook Setup

Configure webhooks to receive real-time event notifications.

Guardrails

Configure safety limits for AI agent actions.