API Reference

Complete reference for all Commerce Compose API endpoints, parameters, and responses.

Base Information

Base URL: https://api.commercecompose.com/v1
Authentication: Bearer token in Authorization header
Content-Type: application/json
Rate Limiting: Varies by plan (see API Basics)

Authentication

All requests require authentication using your API key:

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

Common Response Format

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

Error Response Format

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      "field": "field_name",
      "suggestion": "Helpful suggestion"
    }
  }
}

Connections API

List Connections

GET /connections

Query Parameters:

platform (optional): Filter by platform (shopify, woocommerce, etc.)
status (optional): Filter by status (active, inactive, error)
limit (optional): Number of results (default: 50, max: 100)
offset (optional): Pagination offset

Response:

{
  "success": true,
  "data": {
    "connections": [
      {
        "id": "conn_123456789",
        "name": "My Shopify Store",
        "platform": "shopify",
        "status": "active",
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z",
        "last_sync": "2024-01-15T10:25:00Z",
        "settings": {
          "sync_products": true,
          "sync_inventory": true,
          "sync_orders": false
        }
      }
    ],
    "pagination": {
      "total": 5,
      "limit": 50,
      "offset": 0,
      "has_more": false
    }
  }
}

Get Connection

GET /connections/{connection_id}

Response:

{
  "success": true,
  "data": {
    "id": "conn_123456789",
    "name": "My Shopify Store",
    "platform": "shopify",
    "status": "active",
    "credentials": {
      "shop_domain": "your-store.myshopify.com",
      "api_version": "2024-01"
    },
    "settings": {
      "sync_products": true,
      "sync_inventory": true,
      "sync_orders": false,
      "sync_customers": false
    },
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "last_sync": "2024-01-15T10:25:00Z",
    "sync_stats": {
      "total_products": 150,
      "total_orders": 25,
      "last_sync_duration": 2500
    }
  }
}

Create Connection

POST /connections

Request Body:

{
  "name": "My Shopify Store",
  "platform": "shopify",
  "credentials": {
    "shop_domain": "your-store.myshopify.com",
    "access_token": "shpat_1234567890abcdef",
    "api_version": "2024-01"
  },
  "settings": {
    "sync_products": true,
    "sync_inventory": true,
    "sync_orders": false,
    "sync_customers": false
  }
}

Response:

{
  "success": true,
  "data": {
    "id": "conn_123456789",
    "name": "My Shopify Store",
    "platform": "shopify",
    "status": "active",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Update Connection

PUT /connections/{connection_id}

Request Body:

{
  "name": "Updated Store Name",
  "settings": {
    "sync_products": true,
    "sync_inventory": true,
    "sync_orders": true
  }
}

Delete Connection

DELETE /connections/{connection_id}

Response:

{
  "success": true,
  "data": {
    "message": "Connection deleted successfully"
  }
}

Test Connection

POST /connections/{connection_id}/test

Response:

{
  "success": true,
  "data": {
    "status": "success",
    "message": "Connection test successful",
    "details": {
      "products_count": 150,
      "orders_count": 25,
      "api_version": "2024-01"
    }
  }
}

Workflows API

List Workflows

GET /workflows

Query Parameters:

status (optional): Filter by status (active, inactive, error)
connection_id (optional): Filter by connection
limit (optional): Number of results (default: 50, max: 100)
offset (optional): Pagination offset

Response:

{
  "success": true,
  "data": {
    "workflows": [
      {
        "id": "wf_123456789",
        "name": "Product Sync Workflow",
        "description": "Sync products from Shopify to WooCommerce",
        "status": "active",
        "schedule": "every 5 minutes",
        "last_run": "2024-01-15T10:25:00Z",
        "next_run": "2024-01-15T10:30:00Z",
        "created_at": "2024-01-15T10:30:00Z",
        "stats": {
          "total_runs": 150,
          "success_rate": 98.5,
          "avg_duration": 2500
        }
      }
    ]
  }
}

Get Workflow

GET /workflows/{workflow_id}

Response:

{
  "success": true,
  "data": {
    "id": "wf_123456789",
    "name": "Product Sync Workflow",
    "description": "Sync products from Shopify to WooCommerce",
    "status": "active",
    "schedule": "every 5 minutes",
    "mappings": ["map_123456789"],
    "settings": {
      "conflict_resolution": "source_wins",
      "error_handling": "continue_on_error",
      "batch_size": 100,
      "timeout": 300000
    },
    "notifications": {
      "on_success": true,
      "on_error": true,
      "on_warning": true
    },
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "last_run": "2024-01-15T10:25:00Z",
    "next_run": "2024-01-15T10:30:00Z"
  }
}

Create Workflow

POST /workflows

Request Body:

{
  "name": "Product Sync Workflow",
  "description": "Sync products from Shopify to WooCommerce",
  "schedule": "every 5 minutes",
  "mappings": ["map_123456789"],
  "settings": {
    "conflict_resolution": "source_wins",
    "error_handling": "continue_on_error",
    "batch_size": 100,
    "timeout": 300000
  },
  "notifications": {
    "on_success": true,
    "on_error": true,
    "on_warning": true
  }
}

Update Workflow

PUT /workflows/{workflow_id}

Request Body:

{
  "name": "Updated Workflow Name",
  "schedule": "every 10 minutes",
  "settings": {
    "batch_size": 200
  }
}

Delete Workflow

DELETE /workflows/{workflow_id}

Trigger Workflow

POST /workflows/{workflow_id}/trigger

Response:

{
  "success": true,
  "data": {
    "execution_id": "exec_123456789",
    "status": "started",
    "triggered_at": "2024-01-15T10:30:00Z"
  }
}

Get Workflow Execution

GET /workflows/{workflow_id}/executions/{execution_id}

Response:

{
  "success": true,
  "data": {
    "id": "exec_123456789",
    "workflow_id": "wf_123456789",
    "status": "completed",
    "started_at": "2024-01-15T10:30:00Z",
    "completed_at": "2024-01-15T10:30:05Z",
    "duration_ms": 5000,
    "stats": {
      "records_processed": 150,
      "records_succeeded": 148,
      "records_failed": 2,
      "errors": [
        {
          "record_id": "prod_123",
          "error": "Invalid product data",
          "details": "Missing required field: title"
        }
      ]
    }
  }
}

Mappings API

List Mappings

GET /mappings

Query Parameters:

entity_type (optional): Filter by entity type (product, order, customer)
connection_id (optional): Filter by connection
limit (optional): Number of results (default: 50, max: 100)
offset (optional): Pagination offset

Response:

{
  "success": true,
  "data": {
    "mappings": [
      {
        "id": "map_123456789",
        "name": "Product Sync",
        "entity_type": "product",
        "source_connection": "conn_123456789",
        "target_connection": "conn_987654321",
        "status": "active",
        "created_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}

Get Mapping

GET /mappings/{mapping_id}

Response:

{
  "success": true,
  "data": {
    "id": "map_123456789",
    "name": "Product Sync",
    "entity_type": "product",
    "source_connection": "conn_123456789",
    "target_connection": "conn_987654321",
    "field_mappings": {
      "title": "name",
      "description": "description",
      "price": "regular_price",
      "sku": "sku"
    },
    "transformations": {
      "price": {
        "type": "currency_conversion",
        "params": {
          "from": "USD",
          "to": "EUR",
          "multiplier": 0.85
        }
      }
    },
    "filters": {
      "status": {
        "operator": "eq",
        "value": "active"
      }
    },
    "status": "active",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Create Mapping

POST /mappings

Request Body:

{
  "name": "Product Sync",
  "entity_type": "product",
  "source_connection": "conn_123456789",
  "target_connection": "conn_987654321",
  "field_mappings": {
    "title": "name",
    "description": "description",
    "price": "regular_price",
    "sku": "sku"
  },
  "transformations": {
    "price": {
      "type": "currency_conversion",
      "params": {
        "from": "USD",
        "to": "EUR",
        "multiplier": 0.85
      }
    }
  },
  "filters": {
    "status": {
      "operator": "eq",
      "value": "active"
    }
  }
}

Update Mapping

PUT /mappings/{mapping_id}

Request Body:

{
  "name": "Updated Product Sync",
  "field_mappings": {
    "title": "name",
    "description": "description",
    "price": "regular_price",
    "sku": "sku",
    "inventory": "stock_quantity"
  }
}

Delete Mapping

DELETE /mappings/{mapping_id}

Validate Mapping

POST /mappings/{mapping_id}/validate

Response:

{
  "success": true,
  "data": {
    "valid": true,
    "errors": [],
    "warnings": [
      "Field 'inventory' not found in target schema"
    ],
    "sample_data": {
      "source": {
        "title": "Sample Product",
        "price": 29.99,
        "sku": "PROD-001"
      },
      "target": {
        "name": "Sample Product",
        "regular_price": 25.49,
        "sku": "PROD-001"
      }
    }
  }
}

Alerts API

List Alerts

GET /alerts

Response:

{
  "success": true,
  "data": {
    "alerts": [
      {
        "id": "alert_123456789",
        "name": "Sync Failure Alert",
        "type": "workflow_failed",
        "status": "active",
        "conditions": {
          "workflow_id": "wf_123456789",
          "threshold": 1
        },
        "actions": {
          "email": ["[email protected]"],
          "webhook": "https://app.com/alerts"
        },
        "created_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}

Create Alert

POST /alerts

Request Body:

{
  "name": "Sync Failure Alert",
  "type": "workflow_failed",
  "conditions": {
    "workflow_id": "wf_123456789",
    "threshold": 1
  },
  "actions": {
    "email": ["[email protected]"],
    "webhook": "https://app.com/alerts"
  }
}

Webhooks API

List Webhooks

GET /webhooks

Response:

{
  "success": true,
  "data": {
    "webhooks": [
      {
        "id": "webhook_123456789",
        "url": "https://app.com/webhooks",
        "events": ["workflow.completed", "connection.failed"],
        "status": "active",
        "created_at": "2024-01-15T10:30:00Z",
        "last_delivery": "2024-01-15T10:25:00Z"
      }
    ]
  }
}

Create Webhook

POST /webhooks

Request Body:

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

Analytics API

Get Workflow Analytics

GET /analytics/workflows/{workflow_id}

Query Parameters:

start_date (optional): Start date for analytics (ISO 8601)
end_date (optional): End date for analytics (ISO 8601)
granularity (optional): Data granularity (hour, day, week, month)

Response:

{
  "success": true,
  "data": {
    "workflow_id": "wf_123456789",
    "period": {
      "start": "2024-01-01T00:00:00Z",
      "end": "2024-01-15T23:59:59Z"
    },
    "metrics": {
      "total_runs": 150,
      "success_rate": 98.5,
      "avg_duration": 2500,
      "total_records": 15000,
      "error_count": 3
    },
    "timeline": [
      {
        "date": "2024-01-15",
        "runs": 10,
        "success_rate": 100,
        "avg_duration": 2400,
        "records_processed": 1000
      }
    ]
  }
}

Rate Limits

Rate Limit Headers

All API responses include rate limit headers:

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

Rate Limit by Plan

Plan	Requests/Hour	Burst Limit
Standard	1,000	100
Professional	10,000	1,000
Enterprise	100,000	10,000

Rate Limit Response

When rate limit is exceeded:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 3600 seconds.",
    "details": {
      "limit": 1000,
      "reset_time": 1642233600
    }
  }
}

Error Codes

Code	HTTP Status	Description
`INVALID_API_KEY`	401	API key is missing or invalid
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`VALIDATION_ERROR`	400	Request data is invalid
`RESOURCE_NOT_FOUND`	404	Requested resource doesn’t exist
`PERMISSION_DENIED`	403	Insufficient permissions
`CONNECTION_FAILED`	500	External platform connection failed
`WORKFLOW_RUNNING`	409	Workflow is already running
`INVALID_SCHEDULE`	400	Invalid cron schedule format

SDKs

JavaScript/Node.js

npm install @commercecompose/sdk

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

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

Python

pip install commerce-compose

from commerce_compose import CommerceCompose

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

PHP

composer require commerce-compose/sdk

use CommerceCompose;

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

Testing

Sandbox Environment

Use the sandbox environment for testing:

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

Test API Key

Use the test API key provided in your dashboard:

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

Support

For API support:

Documentation: docs.commercecompose.com
SDK Examples: github.com/commercecompose/sdk-examples
API Status: status.commercecompose.com
Support: support.commercecompose.com

Documentation

Tags

API Reference

Base Information

Authentication

Common Response Format

Error Response Format

Connections API

List Connections

Get Connection

Create Connection

Update Connection

Delete Connection

Test Connection

Workflows API

List Workflows

Get Workflow

Create Workflow

Update Workflow

Delete Workflow

Trigger Workflow

Get Workflow Execution

Mappings API

List Mappings

Get Mapping

Create Mapping

Update Mapping

Delete Mapping

Validate Mapping

Alerts API

List Alerts

Create Alert

Webhooks API

List Webhooks

Create Webhook

Analytics API

Get Workflow Analytics

Rate Limits

Rate Limit Headers

Rate Limit by Plan

Rate Limit Response

Error Codes

SDKs

JavaScript/Node.js

Python

PHP

Testing

Sandbox Environment

Test API Key

Support

Stay Updated with Commerce Insights

Successfully Subscribed!

Request Margin Audit

Margin Audit Request Submitted!

What happens next?

Join Waitlist

Demo Request Submitted!

What happens next?

Submit Resume

Application Submitted!

What happens next?

Cookie Settings

Essential Cookies

Analytics Cookies

Marketing Cookies

We value your privacy.

We value your privacy.

Essential

Analytics

Marketing