API quickstart

This is the developer path: curl-first, no plugin assumed. If you’re on a supported platform (Shopify, WooCommerce, BigCommerce, Magento, OpenCart), the non-technical Get started guide is faster — the plugin handles steps 3 onward for you.

What you need#

• A CartAmplify account.
• Your product catalog accessible programmatically.
• A bearer API key (created with your account; available under Dashboard → API Keys).

Both sk_test_… (sandbox; recorded but excluded from production analytics) and sk_live_… (production) keys are available. Use sk_test_ until you’re ready to count traffic against analytics and personalization.

1. Create the workspace#

app.cartamplify.com — sign up, verify email, complete the workspace wizard. Configure every language you sell in; each language partitions catalog, events, and the personalization model independently.

2. Sync your catalog#

Bulk-paginated full sync via POST /v1/products/bulk. Up to 1000 products per page.

Sync state machine:

• Page 1 acquires a sync lock + records start time.
• Pages 2..N-1 upsert.
• The last page (page == pages) deletes any products not touched during this sync, rebuilds the search index, and releases the lock.

# Page 1 of 3
curl -X POST https://api.cartamplify.com/v1/products/bulk \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "pages": 3,
    "products": [
      {
        "id": "SKU-12345",
        "languageCode": "en",
        "title": "Blue Cotton Shirt",
        "uri": "https://example.com/products/sku-12345",
        "categories": ["Clothing > Men > Shirts"],
        "priceInfo": { "price": "29.99", "currencyCode": "USD" },
        "availability": "IN_STOCK"
      }
    ]
  }'

Repeat with page: 2, then page: 3. Skipping the last page leaves the sync lock open and stale products in place — always close the sync, even with an empty last page.

For incremental updates after the initial sync, use the single-product endpoints (POST/PUT/DELETE /v1/products/{item_id}/{language}).

3. Wire up event tracking#

Personalization, analytics, and training all depend on events. Fire them from your storefront as user actions happen.

curl -X POST https://api.cartamplify.com/v1/user-events \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "detail-page-view",
    "eventTime": "2026-05-27T10:30:00Z",
    "visitorId": "visitor_abc123",
    "languageCode": "en",
    "userInfo": {
      "ipAddress": "203.0.113.45",
      "userAgent": "Mozilla/5.0..."
    },
    "productDetails": [
      { "product": { "id": "SKU-12345" } }
    ]
  }'

Returns 202 Accepted with an eventId. Events are processed asynchronously.

There are seven event types; each needs different fields. See /v1/user-events reference for the full table.

4. Find your search widget ID#

A default search widget is created with your workspace. Find it on the Dashboard → AI Features → Search AI page; copy the widgetId from the widget detail panel. You’ll need this for every search request. Recommendation widget IDs live on Dashboard → AI Features → Recommendations AI → Widgets.

5. Make your first search call#

curl -X POST https://api.cartamplify.com/v1/search \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "visitorId": "visitor_abc123",
    "languageCode": "en",
    "eventTime": "2026-05-27T10:30:00Z",
    "userInfo": {
      "ipAddress": "203.0.113.45",
      "userAgent": "Mozilla/5.0..."
    },
    "widgetId": "wgt_search_main",
    "searchQuery": "blue shirt",
    "pageSize": 20
  }'

Response includes ranked product IDs, facets, an attributionToken, and per-stage latency. Hydrate the IDs from your own catalog.

6. Thread the attribution token#

Every search, browse, and recommendation response returns an attributionToken. Pass it through subsequent events (detail-page-view, add-to-cart, purchase-complete) so revenue attributes back to the originating surface.

# When the shopper clicks a search result:
curl -X POST https://api.cartamplify.com/v1/user-events \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "detail-page-view",
    "eventTime": "2026-05-27T10:30:42Z",
    "visitorId": "visitor_abc123",
    "languageCode": "en",
    "userInfo": { "ipAddress": "...", "userAgent": "..." },
    "productDetails": [
      {
        "product": { "id": "SKU-12345" },
        "attributionToken": "tok_xyz789"
      }
    ]
  }'

Without this, your “revenue from search” / “revenue from each widget” metrics will show as unattributed.

What’s next#