Set Up Commerce Connect
Why setup matters
Section titled “Why setup matters”Commerce Connect sits between Optimizely and your external commerce platform. A correctly configured connector ensures product data flows reliably, content editors see accurate catalog information, and transactional operations route properly to your commerce backend. Poor setup leads to stale product data, broken checkout flows, and frustrated editors.
This guide walks through the complete setup process: installing the connector, configuring authentication, mapping data fields, setting up sync schedules, and verifying the integration.
What you will do
Section titled “What you will do”- Install the Commerce Connect package
- Configure connector authentication
- Map product data fields
- Set up sync schedules
- Verify the data pipeline
Install the Commerce Connect package
Section titled “Install the Commerce Connect package”Add the Commerce Connect NuGet package to your Optimizely project.
dotnet add package Optimizely.CommerceConnect
dotnet add package Optimizely.CommerceConnect.Shopify # or your platformRegister the connector in your application startup.
public void ConfigureServices(IServiceCollection services)
{
services.AddCommerceConnect(options =>
{
options.Platform = CommercePlatform.Shopify;
options.SyncInterval = TimeSpan.FromMinutes(15);
options.EnableTransactionProxy = true;
});
}Configure connector authentication
Section titled “Configure connector authentication”Each connector needs credentials to communicate with your commerce platform’s API.
{
"CommerceConnect": {
"Platform": "Shopify",
"ApiUrl": "https://your-store.myshopify.com/admin/api/2024-01",
"ApiKey": "your-api-key",
"ApiSecret": "your-api-secret",
"AccessToken": "your-access-token",
"WebhookSecret": "your-webhook-secret"
}
}Store sensitive values like API keys in environment variables or a secrets manager rather than in configuration files.
Map product data fields
Section titled “Map product data fields”Commerce Connect needs to know how fields in your external platform map to Optimizely content properties. Define a mapping configuration for products, categories, and variants.
services.AddCommerceConnect(options =>
{
options.ProductMapping = new DataMapping
{
// External field -> Optimizely property
Fields = new Dictionary<string, string>
{
["title"] = "Name",
["body_html"] = "Description",
["vendor"] = "Brand",
["product_type"] = "Category",
["handle"] = "UrlSlug",
["published_at"] = "PublishDate"
},
ImageMapping = new ImageMapping
{
SourceField = "images",
UrlProperty = "src",
AltProperty = "alt"
}
};
options.VariantMapping = new DataMapping
{
Fields = new Dictionary<string, string>
{
["sku"] = "Code",
["price"] = "ListPrice",
["compare_at_price"] = "OriginalPrice",
["inventory_quantity"] = "StockQuantity",
["weight"] = "Weight"
}
};
options.CategoryMapping = new DataMapping
{
Fields = new Dictionary<string, string>
{
["title"] = "Name",
["handle"] = "UrlSlug",
["body_html"] = "Description"
}
};
});For custom fields that do not have a direct mapping, implement a transform function.
options.ProductMapping.Transforms.Add(
new FieldTransform
{
SourceField = "tags",
TargetProperty = "SearchTags",
Transform = (value) =>
{
// Convert comma-separated tags to array
var tags = value?.ToString()
.Split(',', StringSplitOptions
.RemoveEmptyEntries)
.Select(t => t.Trim())
.ToArray();
return tags ?? Array.Empty<string>();
}
});Set up sync schedules
Section titled “Set up sync schedules”Configure how frequently product data syncs from your commerce platform into Optimizely.
| Sync type | Trigger | Use case |
|---|---|---|
| Scheduled full sync | Timer (every 15-60 min) | Catches all changes including bulk updates |
| Webhook real-time sync | Commerce platform event | Immediate updates for product publishes |
| Manual sync | Admin action | On-demand after bulk imports |
services.AddCommerceConnect(options =>
{
// Full sync every 30 minutes
options.FullSyncInterval = TimeSpan.FromMinutes(30);
// Enable webhook for real-time updates
options.EnableWebhooks = true;
options.WebhookEndpoint = "/api/commerce-connect/webhook";
// Sync only published products
options.SyncFilter = (product) =>
product.Status == "active";
// Handle sync errors
options.OnSyncError = (error) =>
_logger.LogError(error,
"Commerce Connect sync error");
});Verify the data pipeline
Section titled “Verify the data pipeline”After configuration, verify that products flow correctly from your commerce platform into Optimizely.
- Trigger a manual sync from the Optimizely admin panel under Commerce Connect settings
- Check the sync log for errors — common issues include authentication failures, field mapping mismatches, and rate limiting
- Browse the CMS catalog to confirm products appear with correct names, descriptions, and images
- Query Graph to verify products are indexed and searchable
- Test a transaction by adding a product to cart and verifying the operation routes to your commerce platform
| Verification step | What to check | Common issues |
|---|---|---|
| Sync log | No errors in last sync run | API credentials expired, rate limits hit |
| CMS catalog | Products visible with correct data | Field mapping errors, missing required fields |
| Graph explorer | Products queryable via GraphQL | Sync not triggering Graph re-index |
| Cart operation | Add-to-cart succeeds | Transaction proxy misconfigured |
| Webhook delivery | Real-time updates arrive | Webhook URL not accessible, secret mismatch |
Common issues
Section titled “Common issues”| Problem | Cause | Fix |
|---|---|---|
| Products not syncing | API credentials invalid | Regenerate and update credentials |
| Missing product images | Image URL mapping incorrect | Verify the ImageMapping.UrlProperty path |
| Stale pricing | Webhook not configured | Enable webhooks or reduce sync interval |
| Graph not updating | CMS publish not triggering sync | Verify Graph integration is active |