The Emarsys Salesforce Commerce Cloud plug-in was certified by Salesforce in August 2021. The integration and documentation are available on Salesforce Marketplace.
Further reading:
The Emarsys integration can be enabled or disabled from Business Manager using the toggle on/off feature. In order to turn on/off the integration, navigate to Merchant Tools > Site Preferences > Custom Preferences > Emarsys > Enable Emarsys Services.

When the integration is disabled and the end user tries to subscribe to a newsletter using the global footer or my account subscription method, they will be redirected to a custom page which will show the message that says the subscriptions are not active.
Even if the integration is disabled, as long as the cartridge is still installed, the end user has the option to unsubscribe from newsletters, from their Salesforce Commerce Cloud account (only registered users) or by clicking the un-subscription link present in the emails received through the Emarsys Platform.
Business Manager
A new Business Manager extension has been created in order to allow the merchant to configure the behavior for newsletter subscriptions and to define the Salesforce Commerce Cloud fields that will be added to transactional emails (order and shipping confirmation emails) that will be sent through the Emarsys Platform. The extension will also allow the merchant to map Salesforce Commerce Cloud with Emarsys fields for the initial database load feature.
If the Emarsys Integration screen is not displayed, then please compare the Salesforce Commerce Cloud code with the Emarsys code and make sure that they are implemented at the appropriate level.
Newsletter subscription - checkout process
1. Login in to Business Manager.
2. Go to Merchant Tools > Emarsys Integration.
3. Select the Newsletter subscriptions item.
4. Click the Checkout page tab.
5. The merchant needs to select the Opt-in strategy. There are two options available:
-
Single Opt-In (the recipient gets
opt-
in system field set totrue
immediately in the Emarsys Platform). Optionally, the merchant can select an external event that gets fired after the user record was transmitted to Emarsys.
-
Double Opt-In (the recipient needs to click a confirmation link in an email in order to get the system field opt-in in Emarsys Platform set to
true
). If double opt-in is selected, then the merchant must select the external event that should be triggered in Emarsys Suite to send out the confirmation email. Optionally the merchant can set a second event that will be triggered as soon an end user clicks the confirmation link (e.g. to send a welcome email).
6. Hit the Apply button to save the configuration.
Newsletter subscription - My account page
1. Login in to Business Manager.
2. Go to Merchant Tools > Emarsys Integration.
3. Select the Newsletter subscriptions item.
4. Click the Account page tab.
5. The merchant needs to select the Opt-in strategy. There are two options available:
-
Single Opt-In (the recipient gets
opt-in
system field set totrue
immediately in the Emarsys Platform). Optionally, the merchant can select an external event that gets fired after the user record was transmitted to Emarsys.
-
Double Opt-In (the recipient needs to click a confirmation link in an email in order to get the system field
opt-in
in Emarsys Platform set totrue
). If double opt-in is selected, then the merchant must select the external event that should be triggered in Emarsys Suite to send out the confirmation email. Optionally, the merchant can set a second event that will be triggered as soon an end user clicks the confirmation link (e.g. to send a welcome email).
6. Click the Apply button to save the configuration.
Transactional emails - order confirmation
As soon as an end user finishes a transaction, the order data should be transmitted to the Emarsys Platform and the corresponding external event must be triggered. The external event will trigger an order confirmation email. Salesforce Commerce Cloud will check in the Emarsys Platform if the user record already exists and based on the result it will update the record or create a new one. Also, the merchant has the option to choose what fields will be included in the order confirmation email.
To configure and map the Salesforce Commerce Cloud fields, that will be added to the order confirmation email, with the defined Emarsys placeholders, a custom configuration screen has been created. Please find below the steps you need to follow to make the necessary configurations for order confirmation emails:
1. Navigate to Business Manager > Merchant Tools > Emarsys Integration > Order Confirmation configuration.
2. Click the Add fields button.
3. From the dropdown, select the Salesforce Commerce Cloud available field and then define the placeholder name in the right column.
4. Select the external event that will be triggered after the order is placed and the record is created or updated in the Emarsys Platform.
5. To remove some of the defined Salesforce Commerce Cloud field and Emarsys placeholder name pairs, select the corresponding Remove checkbox and click the Apply button.
Transactional emails - shipping confirmation
As soon as a shipment was finished, an email should be sent to the end user and the corresponding external event must be triggered. The external event will trigger a shipping confirmation email.
To configure and map the Salesforce Commerce Cloud fields, that will be added to the shipping confirmation email, with the defined Emarsys placeholders, a custom configuration screen has been created. Please find below the steps you need to follow to make the necessary configurations for shipping confirmation emails:
- Navigate to Business Manager > Merchant Tools > Emarsys Integration > Shipping Confirmation configuration.
2. Click the Add fields button.
3. From the dropdown, select the Salesforce Commerce Cloud available field and then define the placeholder name in the right column.
4. Select the external event that will be triggered after the shipment is finished.
5. To remove some of the defined Salesforce Commerce Cloud field and Emarsys placeholder name pairs, select the corresponding Remove checkbox and hit the Apply button.
Transactional emails - order cancelled
As soon as a shipment was finished, an email should be sent to the end user and the corresponding external event must be triggered. The external event will trigger an order cancelled email.
To configure and map the Salesforce Commerce Cloud fields, that will be added to the shipping confirmation email, with the defined Emarsys placeholders, a custom configuration screen has been created. Please find below the steps you need to follow to make the necessary configurations for an order cancelled email:
- Navigate to Business Manager > Merchant Tools > Emarsys Integration > Order Cancelled Configuration Email.
2. Click the Add fields button.
3. From the dropdown, select the Salesforce Commerce Cloud available field and then define the placeholder name in the right column.
4. Select the external event that will be triggered after the shipment is finished.
5. To remove some of the defined Salesforce Commerce Cloud field and Emarsys placeholder name pairs, select the corresponding Remove checkbox and hit the Apply button.
Initial Database Load - configuration screen
The initial database load feature will upload the existing Salesforce Commerce Cloud customers to the Emarsys Platform. Please find below the steps required to accomplish this:
- Create the mapping between Salesforce Commerce Cloud and Emarsys fields using the initial database load configuration screen. The mapping will be used to generate an auto-import profile on the Emarsys side and to create a CSV file with the Salesforce Commerce Cloud customers
In order to generate the mapping, a new configuration screen has been created.
1. Go to Merchant Tools > Emarsys Integration > Database Load Configuration.
2. Click on Add fields.
3. Use the dropdown to map Emarsys fields with Salesforce Commerce Cloud available attributes.
4. Click on the Apply button to save the configuration.

Once the settings for the initial database load feature has been made, the Initialize Emarsys Database job schedule needs to be configured and run. The customers will be exported to the Emarsys Platform in bulks of configurable sizes. The default size of a bulk is set to 10000 customers, but the merchant has the option of updating this value inside Business Manager, by navigating to Administration > Operations > Jobs > Emarsys-InitDatabase > ExportCustomerInfo and setting the value for the Profiles export threshold field.
Important:
- Please keep in mind that setting a high value for the bulk size might affect the performance. Also, the bulk size should never be set to a value higher than 20000 customers in order to avoid Salesforce Commerce Cloud quota violations.
- The recommendation is to schedule the job to run during low traffic periods.
- Set the recurrence according to the number of exported customers per iteration.
When the job schedule is finished, the merchant will have to manually disable it. The Export Status field is used to prevent customers exporting data after the initial database load was done, so that even if the job is not disabled, the export will be skipped. The value of Export Status field is automatically set once all the customers from Salesforce Commerce Cloud were loaded into the Emarsys Platform.
Send Order Confirmation Email - send email
You can manually send order confirmation emails to customers at the order number via the Emarsys service.


After sending the message, the order changes the status of (sendEmarsysShippingEmail)
.
External events page
After successful execution of the Emarsys-Setup job all initial event configuration is already set. External events page is developed to change the event configuration easily. In order to get there, you should:
- Login in to Business Manager.
- Select your site in the left top corner of the page.
- Go to Merchant Tools > Emarsys Integration > External Events.
All external events are separated by their type into two tables: Newsletter Subscription Events and Other Events. Events mapping are taken from the appropriate fields of the EmarsysExternalEvents custom object.
Each table has an Add event button over the top right corner. You should use this button to map new SFCC events. Depending on the type of the event, a new SFCC event should be listed in one of the EmarsysExternalEvents source fields (newsletterSubscriptionSource or otherSource) but should not be on the page (should not yet be mapped). If you want to change the configuration of a mapped SFCC event, you should click the Change button in appropriate row.
After clicking the Add event button, the Create event dialog appears. Use the upper selector to choose the SFCC event you want to map. Events from the newsletterSubscriptionSource field you can map with any allowed Emarsys event (of the same type), while events from the otherSource field are allowed to be mapped only with an appropriate Emarsys event. Click the Add button to apply mapping for a selected SFCC event.
If the appropriate Emarsys event is chosen for mapping, this Event will be created using the Emarsys API. If there are any issues during the request, an error notification will be shown at the top of the events page.


The interface of the page allows to map SFCC Newsletter Subscription Events with any of Emarsys Newsletter Subscription Events. Events of other type may be mapped only with the appropriate Emarsys events or to be disabled. In order to disable any SFCC event, choose the none option of mapping select. To apply mapping changes, click Apply button.
Do not run the Emarsys-Setup job after making some custom events mapping configuration because the job will rewrite the mapping. It means that all SFCC events will be mapped to the appropriate Emarsys events even if they were not mapped or disabled before running
Storefront functionality
By installing the Emarsys cartridge, the retailers will provide their end user with the option of subscribing to newsletters from their website storefront. There are 3 ways for an end user to accomplish this:
- using the newsletter subscription box displayed on the global footer
- during the checkout process, by selecting the Please add me to Salesforce Commerce Cloud's email list. Salesforce Commerce Cloud does not share or sell personal info checkbox on the Billing page
- from Salesforce Commerce Cloud My Account page
All these options are detailed in sections below.
Newsletter subscription during checkout process
The end user also has the option to subscribe to a newsletter during the checkout process, as described below but you need to add this option to the default subscription is false.
1. As a guest or registered user add a product to cart.
2. Proceed to checkout.
3. At the checkout step, type in your email address in the e-mail field.
4. Select Please add me to Salesforce Commerce Cloud's email list. Salesforce Commerce Cloud does not share or sell personal info and I have read the Privacy Policy and I agree checkboxes.


5. Complete all the mandatory fields and proceed to the next step, so that the end user data is sent to the Emarsys Platform.
Newsletter subscription or unsubscription - My Account
Registered user has the option to subscribe/unsubscribe from newsletter from the Profile but this functionality needs to be added on Storefront.
1. Open the storefront and log in.
2. In the left navigation bar, click the Email Settings link.
3. Clicking the Subscribe button will open an email sign-up form. Complete the fields and click the Sign me up for email button to subscribe to newsletters.
4. Clicking the Unsubscribe button will unsubscribe the end user from newsletters.
Salesforce Commerce Cloud landing pages
Depending on which opt-in strategy has been configured for the subscription methods and on the unsubscription strategy (direct or indirect), the end user can be redirected to several landing pages as follows:
- Thank you page - Single Opt-in strategy
- Data submitted page - Double Opt-in strategy
- Thank you page - Double Opt-in strategy
- Thank you page - Unsubscribe
Emarsys SmartInsight
Introduction
SmartInsight is an integrated solution for marketers that utilizes customer data from various touchpoints in order to provide actionable intelligence focused on customer engagement. This data can be uploaded from external sources as well as collected by the Web Extend scripts directly from your website.
Purpose
Emarsys needs a daily sales item CSV feed with new orders (new order items) of the last 24 hours. This feed must be delivered to an FTPS server on a daily basis. For this it is required to set logon credentials for this server in the Salesforce Commerce Cloud backend (hostname, username, password, destination folder).
Settings for the Emarsys SmartInsight attribute configuration for export
Log in to Business Manager where the Emarsys integration is enabled.
Emarsys SmartInsight Extension Configuration
Navigate to Merchant Tools > Emarsys Integration. Here you should see the SmartInsight Configuration link:
On the SmartInsight configuration page, users can add and remove mapped fields. These fields will be used to create the CSV file with this data. These fields will be displayed as columns in the exported files.
The salesitems CSV has to contain at least these columns:
- order - order number
- date - date of the order (YYYY-MM-DD)
If you use the date format YYYY-MM-DD, then you will not be able to use Smart Insight as the data source for Revenue Attribution and you cannot use Emarsys Loyalty at all. If you would like to use these features, change the date to timestamp in your sales date file. For more information, see timestamp in Standard field set.
- customer - unique customer ID (this ID must be available in the Emarsys Platform as well)
If you are using a unique customer ID other than email, then you need to ensure that the setCustomerId Web Extend command is used.
- item - ProductId of the sold item (this ID must be in the products CSV as well!)
- quantity - quantity of the ordered item
- price - price of the sold items (this value must be negative if an order was cancelled!)
The customer is able to add additional order attributes to the data feed. For this, they should click the Add fields link and fill the Attribute name and name that will we displayed in the file. For more information on how to format custom fields in your sales data file, see Custom fields.

Elements that were added on the Site Preferences > Custom Site Preferences > Emarsys SmartInsight Configuration page are displayed in the Available elements drop-down list.

Job for SmartInsight that exports all orders in CSV format and uploads them to the FTPS server
Navigate to Administration > Job Schedules and click Edit for the Emarsys Export Orders job.
On this page, the user can set up Emarsys Export Order Job configurations:
- Enabled - Checkbox which enabled or disabled Emarsys Export Orders job on the site.
- Name - The job’s Name.
- Description - Description of this Job.
- Runtime - The user can set up the time and period when the job will be run automatically.
To run the job, the user should click the Run button.
After finishing the successful ‘Job’, go to the SFTP server and check the folder that was set up on the Emarsys SmartInsight Configuration page. The new exported file with orders should be in this folder.
The file name should be in such format: sales_items_<YYYYMMDDHHiiss>_< shopinfo >.csv
Please make sure that your sales data file follows the naming convention above.
Open the new exported file with orders. All the orders that fit the set timeframe are displayed in the file with certain columns that were added on the Merchant Tools > Emarsys Integration > SmartInsight Configuration page:
Emarsys export catalog
Introduction
Emarsys Catalog is a predictive recommendation engine which uses machine learning algorithms to offer your customers the best products wherever they interact with your business. The data used by the Catalog to make these recommendations is collected by the Web Extend scripts.
Purpose
Emarsys Catalog is being used to recommend products based on a self-learning algorithm. Recommended products can be rendered within shop pages and emails. To get this working, Catalog requires a CSV product data feed which will be fetched from a remote location (HTTP / FTP / SFTP).
BM settings for Emarsys Catalog
Log in to BM where the Emarsys integration is enabled.
BM Settings for Emarsys Catalog Configuration
Navigate to Merchant Tools > Emarsys Integration > Export Catalog Configuration:

On the SmartInsight Catalog configuration page user can add and remove mapped fields. These fields will be used to create the CSV file with this data. These fields will be displayed as columns in the exported files.
The salesitems CSV has to contain at least these columns:
- Item - unique product ID
- Available - Is the product available (and can be recommended)?: true or false
- Title - Product title
- Link - Deep link to the product
- Image - URL of the product image
- Category - Category path to the product separated by “
>
“, e.g. books > scifi > startrek - Price - Product price (float value 1234.99)

In order to send multi language values, in case if there are several locales configured, a value from the Placeholder field must be adjusted with the ‘_multilang
’ prefix.

The customer is able to add additional order attributes to the data feed. For this, they should click the Add fields link and fill the Attribute name and name that will we displayed in the file. The column name of these additional columns must start with "c_
".
Elements that were added on the Site Preferences > Custom Site Preferences > Emarsys Catalog Configuration page are displayed in the Available elements dropdown list.

You can choose the Export type:
1. Export only the main product (no product version) - the default setting
2. Export each product version or each combination of product versions
If you need to export child products, then select the Export each product version or each combination of product versions option. This setting cannot be changed after saving the configuration.

You can create a new instance of the custom object in BM for individual configurations.

You can choose them as individual configurations.


You should click Add fields to add a new field.

For more information on how to set up the step for the job, see section Emarsys-ExportCatalog.
BM Settings for Emarsys Catalog custom object
Navigate to Merchant Tools > Custom Objects > Custom Objects > catalogConfig General and verify the Mapped fields text box. In this field, all selected fields from Merchant Tools > Emarsys Integration > Catalog Configuration are displayed.
Job for Emarsys ExportCatalog that exports all orders in CSV format and uploads them to the FTP
Navigate to Administration > Job Schedules and click Edit for the Emarsys ExportCatalog job.
On this page, the user can set up the Emarsys ExportCatalog job configurations:
- Enabled - Checkbox which enabled or disabled the Emarsys Export Orders job on the site.
- Name - The job’s Name.
- Description - Description of this Job.
- Runtime - The user can set up the time and period when the job will run automatically.
To run the job, the user should click the Run button.
After finishing the Job successfully, go to the SFTP server and check the folder that was set up on the Merchant Tools > Site Preferences > Custom Site Preferences > Emarsys Catalog Configuration page. The new exported file with products is in this folder.
The file name should be in such format: products_<siteName>.csv
Open the new exported file with orders. All the orders that fit the set timeframe are displayed in the file with certain columns that were added into Merchant Tools > Emarsys Integration > Catalog Configuration:
JavaScript tracking code and JavaScript recommendations
Introduction
The Web Extend JavaScript API is a data collection system that captures the activity and behavior of website visitors. This information is used to enrich your Emarsys contact database with Web Extend fields and to generate personalized product recommendations for the Predict solutions.
JavaScript recommendation code
Log in to BM where the Emarsys integration is enabled.
Settings for JavaScript recommendation code
Navigate to the Merchant Tools > Site Preferences > Custom Site Preferences > Emarsys Catalog Configuration link:

On this page, the user can set up the Emarsys JS Configuration:
- Predict: Enable tracking code - Checkbox which enabled or disabled JavaScript tracking code on the site.

- User can select the widget type that will be shown on the storefront for different pages:
- Thank You For Your Order Page
- Product Detail Page
- Home Page
- Cart Page
- Search Page
- Category Page
- Widget types:
- Personal - the Personal widget offers targeted recommendations which match a visitor’s known characteristics and interests, based on their own browse history and the wisdom of the crowd. It helps them to find products they are interested in before they even know they want them.
- Topical - this is a special widget. Each visiting customer will see a different selection of products based on what they are most likely to be interested in and displayed in sections designed to catch their interest and optimize conversion.
- Related - the Related widget suggests alternative products to the items currently being viewed. It does this by looking at the browse behavior for the whole web shop and identifying product-to-product relationships.
- Also Bought - the classic ‘people who bought x, also bought y‘ widget ,Also Bought offers recommendations based on items that have frequently been bought with the item currently being viewed. This is a more targeted version of the Related widget and can be used well in combination with it.
- Cart - similar to Also_Bought, the Cart widget offers recommendations based on the current selection of items in the customer’s shopping cart. It looks for relationships between these items and then makes additional cross- and up-sell recommendations (e.g. a spare power cord for cars, an extra SD card, etc.).
- Category - similar to the Personal widget, the Category widget directs customers to the right products, but within a particular category, depending on the specific category page they are on.
Open the Storefront and visit pages where recommendation widgets must be shown.
Settings for the JavaScript tracking code
Navigate to the Merchant Tools > Site Preferences > Custom Site Preferences > Emarsys Catalog Configuration link:

On this page, the user can set up the Emarsys JS Configuration:
- Predict: Enable tracking code - Checkbox which enabled or disabled the JavaScript tracking code on the site.

Navigate to the storefront and visit pages where the tracking code is supposed to run (category page, search page, pdp, etc.). Check the Emarsys Predict dashboard, here you should see a real-time chart that shows what action you've performed.