Product & Inventory Sync
How Commerce Index keeps your product catalog, orders, and inventory levels synchronized with Shopify — in real time via webhooks, with manual re-sync as a fallback.
How Sync Works
Initial Full Sync
When you first connect your Shopify store, CI performs a full catalog import. This fetches all products, variants, pricing, images, inventory levels, and recent orders using the Shopify Admin API with pagination. Depending on catalog size, this takes 30 seconds to a few minutes.
Webhook Registration
After the initial sync, CI registers webhooks with Shopify for product, order, and inventory events. Shopify sends a POST request to your CI instance whenever a change occurs — no polling required.
Real-Time Updates
As changes happen in Shopify — new products, price updates, orders, inventory adjustments — webhooks fire and CI processes them within seconds. Each webhook payload is verified via HMAC before processing.
Conflict Resolution
If a webhook arrives out of order, CI uses the updated_at timestamp to determine the most recent version. Stale updates are discarded. CI always treats Shopify as the source of truth for product data.
Webhook Events
CI subscribes to the following Shopify webhook topics. Each event triggers a specific sync handler with the payload shown below.
Fired when a new product is created in Shopify. CI imports the product, all variants, pricing, and images.
{
"id": 7891234567890,
"title": "Premium Wireless Headphones",
"vendor": "AudioTech",
"product_type": "Electronics",
"status": "active",
"variants": [
{
"id": 4412345678901,
"title": "Black",
"sku": "WH-PRO-BLK",
"price": "149.99",
"inventory_quantity": 250,
"inventory_item_id": 4512345678901
}
],
"created_at": "2026-03-15T10:30:00-04:00"
}Fired when any product field changes — title, description, price, variant, or status. CI updates the matching record.
{
"id": 7891234567890,
"title": "Premium Wireless Headphones v2",
"status": "active",
"variants": [
{
"id": 4412345678901,
"title": "Black",
"sku": "WH-PRO-BLK",
"price": "139.99",
"inventory_quantity": 245
},
{
"id": 4412345678902,
"title": "White",
"sku": "WH-PRO-WHT",
"price": "139.99",
"inventory_quantity": 180
}
],
"updated_at": "2026-03-16T08:15:00-04:00"
}Fired when a product is permanently deleted from Shopify. CI marks the product as deleted and pauses any active deals referencing it.
{
"id": 7891234567890
}Fired when a new order is placed. CI records the order for revenue tracking, deal attribution, and health score calculation.
{
"id": 5551234567890,
"order_number": 1042,
"financial_status": "paid",
"total_price": "289.98",
"currency": "USD",
"line_items": [
{
"id": 1112345678901,
"product_id": 7891234567890,
"variant_id": 4412345678901,
"title": "Premium Wireless Headphones v2",
"sku": "WH-PRO-BLK",
"quantity": 2,
"price": "139.99"
}
],
"created_at": "2026-03-16T12:00:00-04:00"
}Fired when an order is modified — fulfillment status changes, refunds, cancellations. CI updates order status and recalculates affected metrics.
{
"id": 5551234567890,
"order_number": 1042,
"financial_status": "partially_refunded",
"fulfillment_status": "fulfilled",
"total_price": "289.98",
"refunds": [
{
"id": 8881234567890,
"created_at": "2026-03-17T09:00:00-04:00",
"refund_line_items": [
{
"line_item_id": 1112345678901,
"quantity": 1,
"subtotal": "139.99"
}
]
}
],
"updated_at": "2026-03-17T09:00:00-04:00"
}Fired when inventory quantity changes at any location. CI updates stock levels, triggers low-stock alerts, and notifies agents if thresholds are breached.
{
"inventory_item_id": 4512345678901,
"location_id": 6612345678901,
"available": 12,
"updated_at": "2026-03-17T14:30:00-04:00"
}Sync Frequency
The primary sync mechanism. Shopify sends webhooks within seconds of any change. CI processes them immediately upon receipt. No configuration needed — webhooks are registered automatically when you connect your store.
Trigger a full re-sync from Settings → Shopify → Re-Sync. This re-fetches your entire catalog and reconciles it with CI's records. Useful after bulk imports, migration, or if you suspect data drift.
# Trigger manual re-sync via API
curl -X POST https://api.commerceindex.ai/v1/shopify/sync \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"mode": "full", "shop_domain": "mystore.myshopify.com"}'
# Response
{
"status": "sync_started",
"sync_id": "sync_abc123",
"estimated_duration_seconds": 45,
"products_to_sync": 342
}Troubleshooting
Product not appearing in CI
- Check the SKU: Products without a SKU on at least one variant may be skipped during sync. Add a SKU in Shopify and trigger a re-sync.
- Check product status: Only products with status "active" are imported. Draft and archived products are excluded.
- Wait for sync: If the product was just created, give the webhook a few seconds to arrive. Check the sync log in Settings for confirmation.
Webhook delivery failures
- Check Shopify webhook settings: Go to Shopify Admin → Settings → Notifications → Webhooks. Verify the CI endpoint URL is correct and the webhook is active (not failing).
- Review delivery attempts: Shopify shows the last delivery attempt and response code. A 200 means CI received it. 4xx/5xx errors indicate a problem on the CI side.
- Shopify retries: Shopify retries failed webhooks up to 19 times over 48 hours. If all retries fail, the webhook is deleted. You will need to re-register via Settings → Shopify → Reconnect.
Inventory mismatch
- Trigger a manual sync: Go to Settings → Shopify → Re-Sync or use the API endpoint above. This reconciles inventory levels across all locations.
- Multi-location stores: CI aggregates inventory across all Shopify locations. If you recently added or removed a location, trigger a re-sync to pick up the change.
- Third-party fulfillment: If you use a 3PL that updates inventory outside Shopify, ensure those changes propagate to Shopify first. CI only syncs from Shopify, not directly from 3PLs.