Building a Custom Integration: Push API & Event Tracking

While Cavaco AI offers native integrations for platforms like Shopify and BigCommerce, brands using custom storefronts, headless commerce architectures, or other platforms can fully integrate with Cavaco using our robust developer APIs. A complete custom integration involves two core components: The Cavaco Push API (for catalog and user data) and Event Tracking (for behavioral data).

1. The Cavaco Push API (Server-Side)

The Cavaco Push API is a server-to-server integration method used to sync your foundational data into Cavaco. This ensures that your product catalog, customer profiles, and historical order data are always up-to-date and available for use in campaigns, segments, and AI recommendations.

What to Sync via Push API:

• Product Catalog: Sync your products, variants, pricing, inventory status, and categories. Cavaco's AI relies on this data to generate personalized product recommendations and populate dynamic email blocks.
• Customer Profiles: Push user data including email addresses, phone numbers, names, and custom attributes. This builds the foundation for your audience segments.
• Historical Orders: Sync past purchase data to establish baseline customer lifetime value (LTV), purchase frequency, and product affinities before you even send your first campaign.

How to Authenticate:

To use the Push API, you must generate an API Key. Navigate to Settings > API Keys in your Cavaco dashboard and click Create API Key. Include this key in the Authorization: Bearer header of all your server-side requests.

2. Event Tracking (Client-Side)

While the Push API handles your static and historical data, Event Tracking captures real-time user behavior on your website. This behavioral data is the fuel that powers Cavaco's dynamic segments, triggered automations (like abandoned cart emails), and the AI recommendation engine.

Implementing the Cavaco Tracking Pixel

Before you can track specific events, you must install the base Cavaco Tracking Pixel on every page of your site. This script initializes the Cavaco tracker and automatically handles user session identification and pageview tracking.

Core Ecommerce Events to Track:

To get the most out of Cavaco's ecommerce features, you should implement tracking for the following core events using the cavaco.track() method:

• view_item: Triggered when a user views a specific Product Detail Page (PDP). Required for "Browse Abandonment" campaigns and "Recently Viewed" recommendations.
• add_to_cart: Triggered when a user adds an item to their shopping cart. Required for "Cart Abandonment" campaigns.
• checkout_started: Triggered when a user begins the checkout process. Required for "Checkout Abandonment" campaigns.
• purchase: Triggered when an order is successfully completed. This is critical for revenue attribution, ROI reporting, and removing users from active abandonment flows.

Connecting the Two Systems

For a seamless integration, your client-side events must reference the exact same identifiers used in your server-side Push API syncs. For example, when tracking an add_to_cart event, the product_id passed in the event payload must perfectly match the id of the product synced via the Push API. This allows Cavaco to instantly pull in the product's image, title, and price when generating an abandoned cart email.

Testing Your Integration

Once both the Push API and Event Tracking are implemented, use the Preview API Client in the Cavaco dashboard to verify that your catalog data is syncing correctly. Then, navigate to the Audience > Profiles section, perform test actions on your site, and verify that the events are appearing in real-time on your test user profile.