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.
NoteTo 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:
-
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
-
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
NoteTo 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
- Register a domain.
- Receive and install the Yespo web tracking script (skip this step if it is already installed for widgets).
- Configure the product feed (via UI or API).
- 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
, andPurchasedItems
events from the back end and the rest from the front end.
NoteIf 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
- Add a domain for Web Push notifications.
- Receive the Yespo Web Push script and service worker content.
- Generate
sw.js
with the service worker content and upload it along with the script to the site.
NoteThe 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.
NoteHaving 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.
Updated about 8 hours ago