Your First Integration

This tutorial will walk you through creating your first Commerce Compose integration. We’ll connect a Shopify store to a WooCommerce site and set up product synchronization.

Prerequisites

Before starting, make sure you have:

• ✅ Commerce Compose Account: Active account with API access
• ✅ Shopify Store: Admin access to your Shopify store
• ✅ WooCommerce Site: Admin access to your WordPress/WooCommerce site
• ✅ API Credentials: Access to platform API keys and tokens

Step 1: Set Up Your Commerce Compose Account

1.1 Access Your Dashboard

1. Log in to your Commerce Compose dashboard
2. Navigate to the Connections section
3. Click “Add New Connection”

1.2 Generate API Keys

1. Go to Settings → API Keys
2. Click “Generate New Key”
3. Give your key a descriptive name (e.g., “Production Integration”)
4. Copy the API key and store it securely

# Your API key will look like this
cc_live_1234567890abcdef1234567890abcdef

Step 2: Connect Your Shopify Store

2.1 Create Shopify App

1. Go to your Shopify Partner account
2. Create a new private app
3. Configure the following permissions:
   • Products: Read and write access
   • Inventory: Read and write access
   • Orders: Read access
   • Customers: Read access

2.2 Get Shopify Credentials

1. Note your Shop Domain (e.g., your-store.myshopify.com)
2. Copy your Access Token
3. Note your API Version (recommend using latest)

2.3 Add Shopify Connection

// Using the Commerce Compose SDK
import { CommerceCompose } from '@commercecompose/sdk';

const client = new CommerceCompose({
  apiKey: 'cc_live_1234567890abcdef1234567890abcdef'
});

// Create Shopify connection
const shopifyConnection = await client.connections.create({
  name: 'My Shopify Store',
  platform: 'shopify',
  credentials: {
    shopDomain: 'your-store.myshopify.com',
    accessToken: 'shpat_1234567890abcdef1234567890abcdef',
    apiVersion: '2024-01'
  },
  settings: {
    syncProducts: true,
    syncInventory: true,
    syncOrders: false,
    syncCustomers: false
  }
});

console.log('Shopify connection created:', shopifyConnection.id);

Step 3: Connect Your WooCommerce Site

3.1 Install WooCommerce REST API

1. Ensure WooCommerce is installed and activated
2. Go to WooCommerce → Settings → Advanced → REST API
3. Click “Add Key”
4. Set permissions to “Read/Write”
5. Generate the key and copy the credentials

3.2 Add WooCommerce Connection

// Create WooCommerce connection
const wooConnection = await client.connections.create({
  name: 'My WooCommerce Site',
  platform: 'woocommerce',
  credentials: {
    siteUrl: 'https://your-site.com',
    consumerKey: 'ck_1234567890abcdef1234567890abcdef',
    consumerSecret: 'cs_1234567890abcdef1234567890abcdef'
  },
  settings: {
    syncProducts: true,
    syncInventory: true,
    syncOrders: false,
    syncCustomers: false
  }
});

console.log('WooCommerce connection created:', wooConnection.id);

Step 4: Create Data Mapping

4.1 Define Product Mapping

// Create product mapping
const productMapping = await client.mappings.create({
  name: 'Product Sync',
  sourceConnection: shopifyConnection.id,
  targetConnection: wooConnection.id,
  entityType: 'product',
  fieldMappings: {
    'title': 'name',
    'description': 'description',
    'price': 'regular_price',
    'sale_price': 'sale_price',
    'sku': 'sku',
    'inventory_quantity': 'stock_quantity',
    'status': 'status'
  },
  transformations: {
    'price': {
      type: 'currency_conversion',
      params: {
        from: 'USD',
        to: 'USD',
        multiplier: 1.0
      }
    },
    'status': {
      type: 'value_mapping',
      params: {
        'active': 'publish',
        'draft': 'draft',
        'archived': 'private'
      }
    }
  }
});

console.log('Product mapping created:', productMapping.id);

4.2 Configure Sync Schedule

// Create sync workflow
const syncWorkflow = await client.workflows.create({
  name: 'Product Sync Workflow',
  description: 'Sync products from Shopify to WooCommerce',
  schedule: 'every 5 minutes',
  mappings: [productMapping.id],
  settings: {
    conflictResolution: 'source_wins',
    errorHandling: 'continue_on_error',
    notifications: {
      onSuccess: true,
      onError: true,
      onWarning: true
    }
  }
});

console.log('Sync workflow created:', syncWorkflow.id);

Step 5: Test Your Integration

5.1 Run Manual Sync

// Trigger manual sync
const syncResult = await client.workflows.trigger(syncWorkflow.id);

console.log('Sync started:', syncResult.id);
console.log('Status:', syncResult.status);

5.2 Monitor Progress

// Check sync status
const status = await client.workflows.getExecution(syncResult.id);

console.log('Records processed:', status.recordsProcessed);
console.log('Records succeeded:', status.recordsSucceeded);
console.log('Records failed:', status.recordsFailed);
console.log('Duration:', status.durationMs, 'ms');

5.3 Verify Results

1. Check Shopify: Verify products are unchanged
2. Check WooCommerce: Verify products were created/updated
3. Check Dashboard: Review sync logs and metrics

Step 6: Configure Monitoring

6.1 Set Up Alerts

// Create alert for sync failures
const alert = await client.alerts.create({
  name: 'Sync Failure Alert',
  type: 'workflow_failed',
  conditions: {
    workflowId: syncWorkflow.id,
    threshold: 1 // Alert on any failure
  },
  actions: {
    email: ['[email protected]'],
    webhook: 'https://your-app.com/alerts'
  }
});

6.2 Set Up Dashboard

1. Go to your Commerce Compose dashboard
2. Navigate to Analytics → Workflows
3. Select your sync workflow
4. Configure the dashboard widgets:
   • Sync Success Rate
   • Records Processed
   • Average Duration
   • Error Log

Step 7: Advanced Configuration

7.1 Add Inventory Sync

// Create inventory mapping
const inventoryMapping = await client.mappings.create({
  name: 'Inventory Sync',
  sourceConnection: shopifyConnection.id,
  targetConnection: wooConnection.id,
  entityType: 'inventory',
  fieldMappings: {
    'product_id': 'product_id',
    'quantity': 'stock_quantity',
    'location_id': 'location_id'
  },
  filters: {
    'quantity': {
      operator: 'gt',
      value: 0
    }
  }
});

7.2 Add Order Sync (Read-Only)

// Create order mapping (read-only from Shopify)
const orderMapping = await client.mappings.create({
  name: 'Order Sync',
  sourceConnection: shopifyConnection.id,
  targetConnection: wooConnection.id,
  entityType: 'order',
  direction: 'read_only',
  fieldMappings: {
    'order_number': 'order_number',
    'total': 'total',
    'status': 'status',
    'customer_email': 'customer_email'
  }
});

Troubleshooting

Common Issues

Connection Authentication Failed

// Test connection
const testResult = await client.connections.test(shopifyConnection.id);

if (!testResult.success) {
  console.error('Connection failed:', testResult.error);
  // Check credentials and permissions
}

Data Mapping Errors

// Validate mapping
const validation = await client.mappings.validate(productMapping.id);

if (!validation.valid) {
  console.error('Mapping errors:', validation.errors);
  // Fix field mappings and transformations
}

Sync Performance Issues

// Optimize workflow
const optimizedWorkflow = await client.workflows.update(syncWorkflow.id, {
  settings: {
    batchSize: 100, // Reduce batch size
    concurrency: 2, // Reduce concurrency
    timeout: 300000 // Increase timeout to 5 minutes
  }
});

Best Practices

1. Start Small

• Begin with a single entity type (e.g., products only)
• Test thoroughly before adding more complexity
• Monitor performance and adjust settings

2. Use Staging Environment

// Use sandbox environment for testing
const client = new CommerceCompose({
  apiKey: 'cc_test_1234567890abcdef1234567890abcdef',
  environment: 'sandbox'
});

3. Implement Error Handling

// Comprehensive error handling
try {
  const result = await client.workflows.trigger(syncWorkflow.id);
  console.log('Sync successful:', result.id);
} catch (error) {
  console.error('Sync failed:', error.message);
  
  // Log error details
  await logError({
    workflow: syncWorkflow.id,
    error: error.message,
    timestamp: new Date().toISOString()
  });
  
  // Send alert
  await sendAlert({
    type: 'sync_failed',
    workflow: syncWorkflow.id,
    error: error.message
  });
}

4. Monitor Performance

• Track sync duration and success rates
• Monitor API rate limits
• Set up alerts for failures
• Review logs regularly

Next Steps

Congratulations! You’ve successfully created your first Commerce Compose integration. Now explore:

• Advanced Workflows: Complex multi-step workflows
• Data Transformations: Advanced data mapping
• Performance Optimization: Scaling your integrations
• API Reference: Complete API documentation

Ready to scale? Learn how to optimize your integration for production use! 🚀