API Basics

The Commerce Compose API provides programmatic access to all platform features. This guide covers the fundamentals of authentication, endpoints, and basic integration patterns.

Authentication

All API requests require authentication using API keys. You can manage your API keys from the Commerce Compose dashboard.

API Key Authentication

curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     https://api.commercecompose.com/v1/connections

Rate Limiting

The API implements rate limiting to ensure fair usage:

• Standard Plan: 1,000 requests per hour
• Professional Plan: 10,000 requests per hour
• Enterprise Plan: 100,000 requests per hour

Rate limit headers are included in all responses:

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

Base URL

All API requests should be made to:

https://api.commercecompose.com/v1

Response Format

All API responses follow a consistent JSON format:

{
  "success": true,
  "data": {
    // Response data here
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "request_id": "req_123456789"
  }
}

Error Handling

The API uses standard HTTP status codes and provides detailed error messages:

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid",
    "details": {
      "field": "authorization",
      "suggestion": "Check your API key in the dashboard"
    }
  }
}

Common Error Codes

Core Endpoints

Connections

Manage platform connections:

# List all connections
GET /connections

# Get a specific connection
GET /connections/{connection_id}

# Create a new connection
POST /connections

# Update a connection
PUT /connections/{connection_id}

# Delete a connection
DELETE /connections/{connection_id}

Workflows

Manage data orchestration workflows:

# List all workflows
GET /workflows

# Get a specific workflow
GET /workflows/{workflow_id}

# Create a new workflow
POST /workflows

# Update a workflow
PUT /workflows/{workflow_id}

# Delete a workflow
DELETE /workflows/{workflow_id}

Data Mappings

Configure data transformations:

# List all mappings
GET /mappings

# Get a specific mapping
GET /mappings/{mapping_id}

# Create a new mapping
POST /mappings

# Update a mapping
PUT /mappings/{mapping_id}

# Delete a mapping
DELETE /mappings/{mapping_id}

SDKs and Libraries

JavaScript/Node.js

npm install @commercecompose/sdk

import { CommerceCompose } from '@commercecompose/sdk';

const client = new CommerceCompose({
  apiKey: 'your-api-key',
  environment: 'production' // or 'sandbox'
});

// List connections
const connections = await client.connections.list();

// Create a workflow
const workflow = await client.workflows.create({
  name: 'Product Sync',
  source: 'shopify',
  target: 'magento',
  schedule: 'every 5 minutes'
});

Python

pip install commerce-compose

from commerce_compose import CommerceCompose

client = CommerceCompose(
    api_key='your-api-key',
    environment='production'
)

# List connections
connections = client.connections.list()

# Create a workflow
workflow = client.workflows.create({
    'name': 'Product Sync',
    'source': 'shopify',
    'target': 'magento',
    'schedule': 'every 5 minutes'
})

PHP

composer require commerce-compose/sdk

use CommerceCompose\CommerceCompose;

$client = new CommerceCompose([
    'api_key' => 'your-api-key',
    'environment' => 'production'
]);

// List connections
$connections = $client->connections->list();

// Create a workflow
$workflow = $client->workflows->create([
    'name' => 'Product Sync',
    'source' => 'shopify',
    'target' => 'magento',
    'schedule' => 'every 5 minutes'
]);

Webhooks

Receive real-time notifications about platform events:

Setting Up Webhooks

POST /webhooks
{
  "url": "https://your-app.com/webhooks",
  "events": ["workflow.completed", "connection.failed"],
  "secret": "your-webhook-secret"
}

Webhook Events

Webhook Payload

{
  "event": "workflow.completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "workflow_id": "wf_123456789",
    "status": "completed",
    "records_processed": 150,
    "duration_ms": 2500
  }
}

Testing

Sandbox Environment

Use the sandbox environment for testing:

# Base URL for sandbox
https://api-sandbox.commercecompose.com/v1

Test API Key

Use the test API key provided in your dashboard for development:

curl -H "Authorization: Bearer test_key_123456789" \
     https://api-sandbox.commercecompose.com/v1/connections

Best Practices

Error Handling

Always implement proper error handling:

try {
  const result = await client.workflows.create(workflowData);
} catch (error) {
  if (error.code === 'RATE_LIMIT_EXCEEDED') {
    // Implement exponential backoff
    await delay(1000 * Math.pow(2, retryCount));
  } else if (error.code === 'VALIDATION_ERROR') {
    // Handle validation errors
    console.error('Validation errors:', error.details);
  }
}

Retry Logic

Implement retry logic for transient failures:

const retryWithBackoff = async (fn, maxRetries = 3) => {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      if (error.code === 'RATE_LIMIT_EXCEEDED') {
        await delay(1000 * Math.pow(2, i));
      }
    }
  }
};

Logging

Implement comprehensive logging:

const client = new CommerceCompose({
  apiKey: 'your-api-key',
  logger: {
    info: (message) => console.log(`[INFO] ${message}`),
    error: (message) => console.error(`[ERROR] ${message}`),
    debug: (message) => console.debug(`[DEBUG] ${message}`)
  }
});

Next Steps

Now that you understand the API basics, explore:

• Advanced API Usage: Advanced patterns and optimizations
• Webhook Integration: Real-time event handling
• SDK Reference: Complete SDK documentation
• API Reference: Complete endpoint documentation

Ready to integrate? Start with the Getting Started Guide to set up your first connection! 🚀