CMS Integration Guide

Integrating your CMS platform with Yespo allows online store owners to quickly start using advanced marketing tools without relying on in-house developers. This integration covers the following steps:

• Syncing CMS contact and order data with Yespo
• Tracking user behavior via events
• How to configure Web Push subscriptions
• (Optional) How to set up a product feed for generating product recommendations on the site and in messages

Once integration is complete, CMS users can connect their store to Yespo, set up additional media channels, and launch omnichannel campaigns directly from the Yespo interface — no extra development needed.

📘

Note

To simplify configuration, you can use a real-world example of a full-featured integration in our
Yespo-Shopify GitHub Repository

1. Contact Data Synchronization

1.1 Syncing New Contacts

Purpose: After the integration is enabled, all new contacts created in the CMS are automatically synced to Yespo in real time.

Using contact identifiers such as externalCustomerId, email, and phone helps avoid duplicates, even if the contact already exists in Yespo.

Implementation: Use the Add/update a contact API.

1.2 Importing Existing Contacts

Purpose: Historical contacts that existed in the CMS before the integration can be imported into Yespo as part of the initial setup. As mentioned above, Yespo identifies and merges existing contacts using externalCustomerId, email, and phone, so no duplicates are created.

Implementation: Use the Add/update contacts API.

• Contacts that fail to import are flagged with an error, with its description
• Monitor import status via the Get contact import status API

1.3 Updating Contacts

Purpose: When a contact's email, phone number, or other details change in the CMS, Yespo updates the corresponding profile — or creates it if it doesn't exist.

Implementation: Use the Add/update a contact API.

1.4 Deleting Contacts

Purpose: Contacts deleted in the CMS are also removed from Yespo (1st deletion type) or deactivated (2nd deletion type).

Implementation: Handle both deletion types:

1. GDPR-compliant deletion: Use Delete contact by externalCustomerId API with erase=true.

   • This deletion removes all contact data from the Yespo database and anonymizes orders

2. Regular/manual deletion: Use the same API with erase=false.

   • Manually deleted contacts are marked as deleted, but profiles still exist at a separate tab and are still linked to orders; they can be restored in Yespo

Additional Contact Data Sources

Newsletter Subscriptions via Widgets

Purpose: Contacts subscribing via the Yespo widget are added directly to Yespo, bypassing the CMS.

Implementation: Ensure support for all configurations:

• Both Yespo and CMS forms are enabled
• Yespo form only
• CMS form only

📘

Note

To use Yespo widgets, register a domain, and receive and install the web tracking script

Web Push Subscriptions

Purpose: When a user subscribes to Web Push on the CMS site, Yespo creates a contact with a Web Push token, allowing notifications to be sent to this contact.

Implementation: Enable Web Push configuration in the CMS and ensure correct token transfer.

Contacts from Orders

Using Generate event API

Purpose: When receiving an order, Yespo identifies the contact via externalCustomerId and/or locator (phone/email). If the contact is not found, a new one will be created.

Implementation: Use the Generate event v3 API.

📘

Check out the guide on using Generate event to send orders

Using Add orders API

Purpose: Same as above.

Implementation: Use the Add orders API.

Contacts from PurchasedItems Web Tracking Event

Purpose: When a customer places an order on the CMS store, a contact is created in Yespo via the PurchasedItems event. Whether the contact is new or already exists, it will be mapped with the web tracking event via the CustomerData event.

Implementation: Send JavaScript-based web tracking events from the CMS store.

Account Creation and Login

Purpose: Yespo receives identification data when users sign up or log in.

Implementation: Send the CustomerData web tracking event when:

• A user creates a new account
• A user logs in

📘

Note

• The CustomerData event alone doesn’t create or update contacts. Use the same logic as in the Receiving Contacts and Updating Contacts sections
• If a contact is unknown, Yespo uses cookies to track anonymous behavior and links it upon login or registration

2. Order Data Synchronization

2.1 New Orders

Purpose: After the integration is enabled, all new orders created in the CMS are automatically synced to Yespo in real time.

Implementation:

• Use Add orders and/or Generate event v3 API
• Map order statuses between CMS and Yespo and make sure that up-to-date statuses are always synced to Yespo

2.2 Importing Existing Orders

Purpose: Historical orders data that existed in the CMS before the integration can be imported into Yespo as part of the initial setup.

Implementation: Use the Add orders or Generate past events V3 API.

2.3 Order Updates

Purpose: Yespo reflects updated order data and statuses. When an order’s details or status change in the CMS, Yespo updates the corresponding order, or creates it if it doesn't exist

Implementation:

• Use Add orders and/or Generate event v3 API
• Maintain consistent status mapping (synced to Yespo)

Additional Order Data Sources

Orders from Web Tracking

Purpose: Orders are created in Yespo when customers complete a purchase in the CMS store.

Implementation: Use the PurchasedItems web tracking event.

3. Website Visitor Behavior Tracking

Purpose

Track behavioral data to:

• Build audience segments
• Launch personalized omnichannel campaigns
• Trigger automations like abandoned cart or view
• Power product recommendations with AI

Implementation

1. Register a domain.
2. Receive and install the Yespo web tracking script (skip this step if it is already installed for widgets).
3. Configure the product feed (via UI or API).
4. Track events from the front end, the back end, or both — ensure flexibility regardless of the store’s UI configuration options. For example, you can track CustomerData, StatusCart, and PurchasedItems events from the back end and the rest from the front end.

📘

Note

If you transfer the StatusCart event via the back end, you cannot configure the recommendations display for the cart

Required Events

The Transferring Website Behavior Data via REST API article provides the full list of web tracking events; below are listed the necessary ones:

• PageView : Auto-triggered after script installation
• ProductPage
• StatusCart : Use variation ID as a product key if variations are handled on the website
• PurchasedItems : Use variation ID as a product key if variations are handled on the website; purchase triggers contact/order creation. Also, when using variation, make sure you pass the variation ID via orders and/or event API
• CustomerData
• CategoryPage
• 404
• MainPage

4. Web Push Subscription Configuration

Purpose

• Store owners can quickly set up Web Push with minimal effort
• Subscribers are added to Yespo with a token
• Rejected subscribers aren't added, but can be prompted again later
• Manual updates (e.g., icons, subscription types) are supported via configuration in the Yespo account
• Store owners can configure сustom push campaigns via Yespo
• CMS activity data powers reporting
• Conflicts with third-party push providers are handled gracefully

Implementation

1. Add a domain for Web Push notifications.
2. Receive the Yespo Web Push script and service worker content.
3. Generate sw.js with the service worker content and upload it along with the script to the site.

📘

Note

The API-based setup creates a one-click subscription by default. A user can change the subscription type in the Yespo account settings

5. Product Feed Configuration

Purpose

The product feed allows Yespo to access real-time catalog data from your CMS, enabling personalized product recommendations, dynamic content, and relevant campaign triggers.

📘

Note

Having a feed is necessary for tracking web events

Implementation

• Post product feed links (with language parameters) to Yespo from your CMS
• Detect missing or incorrect feeds and notify the user
• Provide a simple interface for fixing feed errors or updating links
• Allow users to manage feed settings like update frequency and supported languages

Need Help?

If any step seems unclear or technically challenging, contact us at [email protected]. We're happy to help you determine the best integration approach.