CommercePulse API

Integrate CommercePulse analytics and insights directly into your applications with our RESTful API

REST
API Architecture
JSON
Response Format
HTTPS
Secure Only
v1
Current Version

🚀 Quick Start

1. Get Your API Key

Generate your API key from your CommercePulse dashboard under Settings > API Access.

# Your API key will look like:
cp_live_1234567890abcdef...

2. Make Your First Request

All API requests require authentication using your API key in the Authorization header. 

curl -X GET \
  https://api.getcommercepulse.com/v1/metrics \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

🔐 Authentication

Base URL

https://api.getcommercepulse.com/v1

API Key Authentication

Include your API key in the Authorization header of every request:

Authorization: Bearer cp_live_1234567890abcdef...

Security Note

Keep your API keys secure and never expose them in client-side code. Use environment variables or secure key management systems.

📊 Core Endpoints

Get Business Metrics

GET
GET /v1/metrics

Retrieve comprehensive business metrics including revenue, orders, customers, and more.

Query Parameters

period 7d, 30d, 90d, 1y
start_date YYYY-MM-DD
end_date YYYY-MM-DD

Example Response

{
  "total_revenue": 12459.30,
  "total_orders": 87,
  "avg_order_value": 143.21,
  "unique_customers": 64,
  "growth_rate": 15.2
}

Get AI Insights

GET
GET /v1/insights

Retrieve AI-generated business insights and recommendations.

Query Parameters

category revenue, customer, product
limit 1-10 (default: 5)

Example Response

{
  "insights": [
    {
      "id": "ins_123",
      "category": "revenue",
      "title": "Bundle Opportunity",
      "content": "Product A + B bundle...",
      "impact": "high",
      "created_at": "2025-01-21T10:30:00Z"
    }
  ]
}

Customer Analytics

GET
GET /v1/customers

Access customer segmentation and analytics data.

Query Parameters

segment vip, loyal, at_risk, new
page Page number

Example Response

{
  "customers": [
    {
      "segment": "vip",
      "count": 12,
      "avg_order_value": 245.30,
      "lifetime_value": 1200.00
    }
  ],
  "total": 64
}

Generate New Insight

POST
POST /v1/insights/generate

Trigger AI to generate a new business insight based on latest data.

Request Body

{
  "focus_area": "revenue",
  "priority": "high"
}

Example Response

{
  "success": true,
  "insight": {
    "id": "ins_456",
    "category": "revenue",
    "content": "New insight generated...",
    "impact": "high"
  }
}

⚡ Rate Limits

100
Requests per hour
Free Plan
1,000
Requests per hour
Pro Plan
Custom
Requests per hour
Enterprise

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642781234

🚨 Error Handling

Error Response Format

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid",
    "details": "Please check your API key and try again"
  }
}

Common Error Codes

400 Bad Request

Invalid request parameters

401 Unauthorized

Invalid or missing API key

403 Forbidden

Insufficient permissions

429 Rate Limited

Too many requests

500 Server Error

Internal server error

503 Service Unavailable

Temporary maintenance

💻 Code Examples

JavaScript (Node.js)

const axios = require('axios');

const client = axios.create({
  baseURL: 'https://api.getcommercepulse.com/v1',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

// Get business metrics
async function getMetrics() {
  try {
    const response = await client.get('/metrics?period=30d');
    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.response.data);
  }
}

// Generate AI insight
async function generateInsight() {
  try {
    const response = await client.post('/insights/generate', {
      focus_area: 'revenue'
    });
    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.response.data);
  }
}

Python

import requests

class CommercePulseAPI:
    def __init__(self, api_key):
        self.base_url = 'https://api.getcommercepulse.com/v1'
        self.headers = {
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        }

    def get_metrics(self, period='30d'):
        response = requests.get(
            f'{self.base_url}/metrics',
            params={'period': period},
            headers=self.headers
        )
        return response.json()

    def generate_insight(self, focus_area='revenue'):
        response = requests.post(
            f'{self.base_url}/insights/generate',
            json={'focus_area': focus_area},
            headers=self.headers
        )
        return response.json()

# Usage
api = CommercePulseAPI('YOUR_API_KEY')
metrics = api.get_metrics()
print(metrics)

PHP

apiKey = $apiKey;
    }

    public function getMetrics($period = '30d') {
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $this->baseUrl . '/metrics?period=' . $period);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer ' . $this->apiKey,
            'Content-Type: application/json'
        ]);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

        $response = curl_exec($ch);
        curl_close($ch);

        return json_decode($response, true);
    }
}

$api = new CommercePulseAPI('YOUR_API_KEY');
$metrics = $api->getMetrics();
print_r($metrics);
?>

cURL

# Get metrics
curl -X GET \
  "https://api.getcommercepulse.com/v1/metrics?period=30d" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

# Generate insight
curl -X POST \
  "https://api.getcommercepulse.com/v1/insights/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "focus_area": "revenue",
    "priority": "high"
  }'

# Get customer segments
curl -X GET \
  "https://api.getcommercepulse.com/v1/customers?segment=vip" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

🔔 Webhooks

Get real-time notifications when important events happen in your CommercePulse account.

Available Events

insight.generated
New AI insight created
metrics.updated
Business metrics refreshed
alert.triggered
Business alert activated

Webhook Payload

{
  "event": "insight.generated",
  "data": {
    "insight_id": "ins_123",
    "category": "revenue",
    "impact": "high",
    "created_at": "2025-01-21T10:30:00Z"
  },
  "account_id": "acc_456"
}

📚 SDKs & Libraries

JavaScript SDK

Official Node.js and browser SDK

npm install commercepulse

Python SDK

Official Python library

pip install commercepulse

PHP SDK

Official PHP package

composer install commercepulse

Don't see your language? We're working on more SDKs. Let us know what you need!

⚡ API Status

All Systems Operational
99.9%
Uptime
< 200ms
Avg Response Time
24/7
Monitoring
View Detailed Status Page →

Need Help with the API?

Our team is here to help you integrate CommercePulse into your applications.

Contact Support View Full Docs

Developer Support

Email: developers@getcommercepulse.com

Response time: 2-4 hours

Community

Join our developer Discord

Share code and get help