Commerce Connectors

Commerce connectors let you connect your e-commerce platform directly from the Inception Agents dashboard. No code changes, no API tokens to manage manually — authenticate via OAuth and your catalog starts syncing automatically.

Supported Platforms

How Connectors Work

┌──────────────┐     OAuth/Token     ┌──────────────────┐
│  Dashboard   │ ──────────────────> │ Commerce Platform │
│  Setup UI    │                     │  (Shopify, etc.)  │
└──────┬───────┘                     └────────┬─────────┘
       │                                      │
       │  Store credentials                   │  Webhooks
       ▼                                      ▼
┌──────────────┐     Pull/Push       ┌──────────────────┐
│  Supabase    │ <─────────────────> │  Sync Pipeline   │
│  (encrypted) │                     │  (KV + API)      │
└──────────────┘                     └──────────────────┘

1. Connect — Authenticate with your commerce platform via the dashboard setup wizard
2. Sync — The connector pulls your full catalog (products, collections, pricing, inventory)
3. Push — Product data is transformed and pushed to Cloudflare KV for edge-fast serving
4. Webhooks — Real-time updates when products change, inventory shifts, or prices update

Dashboard Setup

Step 1: Navigate to Connectors

Open the Inception Agents Dashboard and navigate to Connectors in the sidebar.

Step 2: Choose Your Platform

Click + Add Connector and select your commerce platform from the list.

Step 3: Authenticate

For Shopify and BigCommerce (OAuth):

• Click “Connect” to start the OAuth flow
• You’ll be redirected to your platform’s authorization page
• Grant the requested permissions (read access to products, collections, inventory)
• You’ll be redirected back to the dashboard

For Salesforce Commerce Cloud:

• Enter your SFCC instance URL
• Provide your SCAPI Client ID and Client Secret
• Enter your Organization ID and Short Code
• Click “Test Connection” to verify

For Adobe Commerce:

• Enter your Magento 2 store URL
• Generate an Integration Token in your Adobe Commerce admin (System → Integrations)
• Paste the Access Token into the dashboard
• Click “Test Connection” to verify

For WooCommerce:

• Enter your WooCommerce store URL
• Generate REST API keys in WooCommerce (Settings → Advanced → REST API)
• Select “Read” permission scope
• Paste the Consumer Key and Consumer Secret into the dashboard
• Click “Test Connection” to verify

Step 4: Configure Sync

After authenticating, configure your sync preferences:

• Sync scope — All products, specific collections, or filtered by category
• Sync frequency — How often to pull full catalog updates (depends on your plan tier)
• Webhook events — Which events trigger real-time updates

Step 5: Initial Sync

Click Start Sync to begin the initial catalog import. Depending on catalog size:

Freshness Tiering

Data sync frequency depends on your plan:

All tiers include webhook ingestion for instant updates on critical events (product created, price changed, inventory depleted).

What Gets Synced

Products

• Title, description, body HTML
• SKU, barcode, weight
• Images (URLs and alt text)
• SEO title and description
• Tags and categories

Variants

• Price, compare-at price
• Inventory quantity and policy
• Options (size, color, etc.)
• SKU per variant

Collections

• Collection title and description
• Product membership
• Sort order and rules (smart collections)

Inventory

• Available quantity per location
• Inventory tracking status
• Low-stock thresholds

Webhook Events

When webhooks are configured, the following events trigger real-time sync:

Webhooks are verified using HMAC-SHA256 signatures (Shopify, BigCommerce, WooCommerce) or certificate verification (SFCC, Adobe Commerce).

Connector Health

Monitor connector status from the dashboard:

• 🟢 Healthy — Sync running, webhooks active, no errors
• 🟡 Warning — Webhook delivery delays or partial sync failures
• 🔴 Error — Authentication expired, API errors, or sync halted

The dashboard shows:

• Last successful sync timestamp
• Total products synced
• Webhook delivery rate
• Error log with retry status

Enterprise Reliability

All connectors include enterprise-grade reliability patterns:

Rate Limiting

Platform-specific token bucket rate limiter that auto-adapts from API response headers. For example, Shopify’s X-Shopify-Shop-Api-Call-Limit header is used to dynamically adjust request pacing. Each platform has its own bucket with configurable burst and sustained rates.

Circuit Breaker

Automatic failure isolation using a closed → open → half_open state machine. When a platform API returns consecutive errors, the circuit breaker opens to prevent cascading failures. After a cooldown period, it enters half-open state and probes with a single request to test recovery. Prevents one degraded connector from affecting others.

Webhook Replay Protection

In-memory dedup with TTL eviction prevents duplicate webhook processing. Common during platform retries or network instability. Each webhook is identified by a unique delivery ID and rejected if already processed within the TTL window.

Security Hardening

• Path traversal prevention — all file paths (media downloads, exports) are validated to prevent directory traversal attacks
• Media type whitelist — only approved MIME types are processed during media sync
• GTIN validation — 8/12/13/14-digit format validation with Luhn check digit verification
• Webhook signature verification — HMAC-SHA256 for Shopify, BigCommerce, and WooCommerce; certificate verification for SFCC and Adobe Commerce

Troubleshooting

OAuth token expired

Shopify and BigCommerce OAuth tokens are long-lived but can be revoked. If you see authentication errors, disconnect and reconnect the connector from the dashboard.

Webhook delivery failures

Check the webhook logs in the dashboard. Common causes:

• Cloudflare Worker URL is unreachable (check DNS)
• HMAC verification mismatch (reconnect the connector)
• Rate limiting on the commerce platform side

Sync stuck in progress

If an initial sync hangs for more than 30 minutes:

1. Check the connector logs for specific error messages
2. Verify your commerce platform API is accessible
3. Try disconnecting and reconnecting the connector
4. For large catalogs (50K+ products), contact support

Products not appearing at edge

After sync completes, products should appear within your freshness tier’s polling interval. If not:

1. Verify the KV push completed (check connector logs)
2. Confirm the edge worker is reading from the correct KV namespace
3. Test with curl -H "User-Agent: GPTBot" https://your-domain.com/products/your-product

API Access

Connectors can also be managed programmatically. See the Connectors API Reference for endpoints.