API Integration

API Integration Guide

Connect any e-commerce platform to Commerce Index using the REST API. This guide covers authentication, rate limits, credit costs, and code examples for common operations.

Getting API Keys

Navigate to Developer Settings > API Keys in your CI dashboard. Click Generate New Key to create an API key. You will also need your Merchant ID, visible at the top of the Developer Settings page.

Security: API keys grant full access to your merchant data. Store them securely in environment variables. Never commit keys to version control or expose them in client-side code.

Authentication

Every API request requires two headers for authentication:

X-CI-Api-KeyYour API key from Developer Settings

X-CI-Merchant-IdYour merchant identifier

Base URL: https://api.commerceindex.com/v1

Rate Limits by Tier

Tier	Rate Limit	Monthly Credits
Free	2 requests/second	1,000 credits
Pro	10 requests/second	10,000 credits
Scale	50 requests/second	100,000 credits
Enterprise	200 requests/second	1,000,000+ credits

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

Credit Costs per Endpoint

Category	Credits	Examples
Instant	1 credit	Health check, product lookup, inventory level
Standard	5 credits	Create product, update deal, list orders
Deep	25 credits	CI Score calculation, margin analysis, agent digest
Ultra	100 credits	Full report generation, competitor analysis, AI recommendations

Response Headers

Every API response includes credit and tier information in the headers:

X-CI-Credits-CostNumber of credits consumed by this request

X-CI-Credits-RemainingCredits remaining in your current billing period

X-CI-TierYour current plan tier (free, pro, scale, enterprise)

JavaScript Example

// Create a product
const createProduct = await fetch('https://api.commerceindex.com/v1/products', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-CI-Api-Key': process.env.CI_API_KEY,
    'X-CI-Merchant-Id': process.env.CI_MERCHANT_ID
  },
  body: JSON.stringify({
    title: 'Premium Wireless Headphones',
    sku: 'WH-PRO-100',
    price: 79.99,
    compare_at_price: 99.99,
    currency: 'USD',
    category: 'Electronics',
    inventory: { available: 250, location: 'warehouse-east' }
  })
});
const product = await createProduct.json();
console.log('Product created:', product.id);
console.log('Credits remaining:', createProduct.headers.get('X-CI-Credits-Remaining'));

// Get CI Score for a product
const scoreRes = await fetch(`https://api.commerceindex.com/v1/products/${product.id}/score`, {
  headers: {
    'X-CI-Api-Key': process.env.CI_API_KEY,
    'X-CI-Merchant-Id': process.env.CI_MERCHANT_ID
  }
});
const score = await scoreRes.json();
console.log(`CI Score: ${score.score}/1000 (Grade: ${score.grade})`);

// Create a deal
const dealRes = await fetch('https://api.commerceindex.com/v1/deals', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-CI-Api-Key': process.env.CI_API_KEY,
    'X-CI-Merchant-Id': process.env.CI_MERCHANT_ID
  },
  body: JSON.stringify({
    title: 'Summer Sale - 20% Off',
    discount_type: 'percentage',
    discount_value: 20,
    product_ids: [product.id],
    starts_at: '2026-03-20T00:00:00Z',
    ends_at: '2026-03-27T00:00:00Z'
  })
});
const deal = await dealRes.json();
console.log('Deal created:', deal.id);

Python Example

import requests
import os

BASE_URL = "https://api.commerceindex.com/v1"
HEADERS = {
    "X-CI-Api-Key": os.environ["CI_API_KEY"],
    "X-CI-Merchant-Id": os.environ["CI_MERCHANT_ID"],
    "Content-Type": "application/json"
}

# Create a product
product_res = requests.post(f"{BASE_URL}/products", headers=HEADERS, json={
    "title": "Premium Wireless Headphones",
    "sku": "WH-PRO-100",
    "price": 79.99,
    "compare_at_price": 99.99,
    "currency": "USD",
    "category": "Electronics",
    "inventory": {"available": 250, "location": "warehouse-east"}
})
product = product_res.json()
print(f"Product created: {product['id']}")
print(f"Credits remaining: {product_res.headers['X-CI-Credits-Remaining']}")

# Get CI Score
score_res = requests.get(
    f"{BASE_URL}/products/{product['id']}/score",
    headers=HEADERS
)
score = score_res.json()
print(f"CI Score: {score['score']}/1000 (Grade: {score['grade']})")

# Create a deal
deal_res = requests.post(f"{BASE_URL}/deals", headers=HEADERS, json={
    "title": "Summer Sale - 20% Off",
    "discount_type": "percentage",
    "discount_value": 20,
    "product_ids": [product["id"]],
    "starts_at": "2026-03-20T00:00:00Z",
    "ends_at": "2026-03-27T00:00:00Z"
})
deal = deal_res.json()
print(f"Deal created: {deal['id']}")

cURL Example

# Create a product
curl -X POST https://api.commerceindex.com/v1/products \
  -H "Content-Type: application/json" \
  -H "X-CI-Api-Key: $CI_API_KEY" \
  -H "X-CI-Merchant-Id: $CI_MERCHANT_ID" \
  -d '{
    "title": "Premium Wireless Headphones",
    "sku": "WH-PRO-100",
    "price": 79.99,
    "compare_at_price": 99.99,
    "currency": "USD",
    "category": "Electronics"
  }'

# Get CI Score for a product
curl https://api.commerceindex.com/v1/products/prod_abc123/score \
  -H "X-CI-Api-Key: $CI_API_KEY" \
  -H "X-CI-Merchant-Id: $CI_MERCHANT_ID"

# Response:
# {
#   "product_id": "prod_abc123",
#   "score": 847,
#   "grade": "A",
#   "components": {
#     "fulfillment": 91,
#     "communication": 88,
#     "consistency": 85,
#     "policy_adherence": 82
#   },
#   "trend": "improving",
#   "computed_at": "2026-03-17T10:30:00Z"
# }

# Create a deal
curl -X POST https://api.commerceindex.com/v1/deals \
  -H "Content-Type: application/json" \
  -H "X-CI-Api-Key: $CI_API_KEY" \
  -H "X-CI-Merchant-Id: $CI_MERCHANT_ID" \
  -d '{
    "title": "Summer Sale - 20% Off",
    "discount_type": "percentage",
    "discount_value": 20,
    "product_ids": ["prod_abc123"],
    "starts_at": "2026-03-20T00:00:00Z",
    "ends_at": "2026-03-27T00:00:00Z"
  }'