SAP Commerce Cloud Integration with Emarsys:: SAP Commerce Cloud - Integration manual – Emarsys

In case you are interested in adopting SAP Commerce Cloud Integration with Emarsys, please contact your Success, Account, Partner or Sales Manager.

Before looking into integration, make sure you are familiar with the prerequisites and requirements of this solution: SAP Commerce Cloud Integration with Emarsys - Getting started.

We strongly suggest activating Web Extend before performing product sync with SAP Commerce Cloud.

Setting up the Emarsys for SAP Commerce Cloud plugin

Before integrating

Consider the following important points before beginning your integration process:

The product catalogue will become available on Predict a couple of hours after the product sync is performed. Please be patient.
Products cannot be deleted. Emarsys needs historical products too, the only way to make your product disappear is to set it to unavailable.
In case there is no stock information for a product on the parental level, each child product level is examined to determine available status.
Adding new products can take up to 5 hours due to processing on SAP Commerce Cloud and Emarsys end.
Product descriptions, brands and so on should not include new line character as Predict does not accept them. Any such product is ignored in sync.
Set up events in Interactions in a way that each change in the order management flow corresponds to one single order lifecycle status. For instance, "created" is followed immediately by "processing".
In general, well-thought-out order flow management is especially crucial for transactional tactics and use cases - such as order confirmation and shipment update.
Filters (participation for once par day / week for post-purchase-up-sell) can be managed on the program level for marketing Tactics and automation in general.

IP filtering

In case IP filtering is enabled in your SAP Commerce Cloud environment, make sure that the following IP Filter Set is allowed:

34.89.173.3/32
35.246.249.205/32
34.89.137.140/32

User creation

Open the Emarsys Marketing Platform and the SAP Commerce Cloud Backoffice on two separate tabs in your browser.

Important: the backoffice URL is needed in this setup step not the frontend one.
Emarsys: Go to Add-ons → SAP Commerce Cloud Integration.
- Check the provided credentials: there is an auto-generated username and a password.
  These credentials are not static, they are regenerated on each page load for security reasons.
SAP Commerce Cloud: Create an administrator user with the credentials provided by Emarsys.
- User → Employees → + (Use the plus sign under the search box.)
  - In the Create New Employee pop-up, paste the username copied over from Emarsys into the ID field and click Done.
  - A green notification comes up about ID creation. Click the ID link in the notification.
  - Copy over the password from Emarsys and, in the PASSWORD tab of the newly created ID, paste it twice into the Change Password fields. Click the yellow SAVE.
- In Groups in GENERAL - PROPERTIES in Commerce Cloud, remove employeegroup membership and assign the new user to admingroup.
Emarsys: Finish user creation.
- Enter the created user's URL copied from Commerce Cloud to the URL field
  The service works over HTTPS only for security reasons.
- Delete /backoffice/ from the end of the URL.
- Click the Test and Connect button.

Data sync

Perform all of these tasks in Emarsys. In general, the direction of the data flow is from SAP Commerce Cloud to Emarsys.

If you use your own solution for managing consent and maintain the consent in SAP Commerce Cloud, make sure that you do not turn on the sync consents switch in the Contacts tab when setting up.

Customer sync

Turn on Enable contact sync to use your SAP Commerce Cloud Customer entities in Emarsys.

Show mapping:
- Preview of all mapped fields in Emarsys, connecting to their equivalent ones in SAP Commerce Cloud.
- The mapping cannot be changed, it is a preview only.
Resync B2B Customers:
- When changing the Business Unit in SAP Commerce Cloud (name, address etc), it will assure the right data on Emarsys' end.
- It is visible and relevant only along with the B2B Add-on on SAP Commerce Cloud's end.
Try matching contacts also by email:
- Contacts' email addresses will be considered as well in the syncing process, not just the SAP Commerce Cloud Customer ID.
- The feature logic will check whether the email exists already, and create the new contact only if there is neither a SAP Commerce Cloud Customer ID, nor an email address of the contact.
- Email address is considered only once in the synchronization process; namely by the initial creation. For updates and deletes, the SAP Commerce Cloud Customer ID is used.

Regarding this feature, please note that:

You must ensure good data quality; if two or more contacts with the same email exist in your Emarsys account at the point when the Plugin is trying to synchronize; it will not update them and skip them.
To avoid duplication, we recommend to use this feature only to synchronize registered customers. Guest customers are only relevant when using Emarsys for transactional messages (such as order confirmation, delivery update).
- If you synchronize guest contacts, an email address can be created multiple times and the later guest or registered one will overwrite the previous. This might affect delivery of transactional messages such as order update and delivery confirmation.

Among others, you can use this feature for Lead Acquisition, and avoid the duplication of contacts. For more information, see Lead acquisition.

Sync registered customers only:
- By ticking this box, you will synchronize only registered customers (and exclude guests).
- Guest customers are only needed for transactional messages (e.g. order confirmation, delivery update).
- If you use Emarsys for marketing use cases only, we recommend to use this option.
Sync consents:
- If you want to use the Emarsys integration for managing customer consent, tick this box and provide the following:
  1. Base site
  2. Consent Template
  3. Consent Template Version
Once you are done with the settings, click Save.

The customerID (SAP Commerce Cloud CustomerID on Emarsys' end) is by default a unique identifier to create, update or delete customers in Emarsys.
The unique identifier cannot be changed to any other field (e.g. email), except the match for initial creation as described above.

Real-time events sync

Make sure that the initial contact sync has already finished, so the system is not busy syncing.
Turn on the Enable real time event sync. Syncable events are:
- cart
- customer review
- order update
- customer registration (requires contact sync)
- opt-in status (requires consent sync)
Click Save.

You can only sync events of logged-in users.

If you decide not to perform contact sync, you can use only the following events:

All Order Update
Order Created
Order Completed
Order Canceled
Order Shipped
Cart
Customer review

By using these events without contact sync, make sure that:

Contacts are created in Emarsys first (only existing contacts can be treated).
Contacts are created with the SAP Commerce Cloud User ID, which is used as the default identifier for the integration.

You can customize the order, customer review and cart events in SAP Commerce Cloud by adding additional attributes. For more information, see SAP Commerce Cloud Integration with Emarsys - Real Time Events customization.

Product sync

Start the product sync process only after Web Extend is activated.

In case you already have product data locally on the Emarsys side, it is erased during the sync.

Product sync is performed via Flexible Product Catalog Onboarding. Once done, Predict and WebExtend can use the imported product data. A product CSV sample is also available in this tab, which can be used as a structural example for product mapping in the Smart Insight setup. You can see the CSV sample pop-up below.

Turn on the Enable product sync.
Choose the product catalogue(s) to sync to Emarsys from SAP Commerce Cloud. Select catalogues individually or use Select all.
Enter the domain of your product images. For example, https://my-cool-shop.com/.
Enter the product URL template.
An example:
https://my- cool-shop.com/products/{{ code }}
The bracketed code is a unique identifier of a specific product in your catalogue.
Specify the one currency which the price is in. We only support single currency at the moment.
Click Save.

Supported fields:

title
item
link
image
category
description
price
msrp
available
brand
zoom_image

Product stock availability

You need to link StockLevel to the Product to get the right product stock information. Each Product needs to have its StockLevel directly attached otherwise the availability information will not be up-to-date.

Below is a product item with the appropriate fields populated on its ADMINISTRATION tab.

For further important technical details on availability and other product properties, see Attribute inheritance for products.

Product sync transformations

This section describes the transformations that the SAP Commerce Cloud product data goes through to become product data in Emarsys.

item

The product’s code, in case of parent products, is prefixed with g/.

group_id

The top level product’s code, inherited by all of its variants.

Example

In the example, both bbb-222 and ccc-333 inherit the group ID aaa-111:

{
  “code”: “aaa-111”,
  “variants": [
    {
      "code": "bbb-222",
      "variants": [
        {
          "code": "ccc-333"
			} 
       ]
      } 
     ]
}

title

The product’s name.

brand

The product’s manufacturerName.

description

The product’s summary.

The summary field in SAP Commerce Cloud better corresponds to the description field in Emarsys and it supports the possible use cases.

price

To find the product’s default price, we filter the product’s europe1Prices based on the following criteria:

^–has no user assigned to it
^–has no ug (usergroup) assigned to it
^–has no pg (pricegroup) assigned to it
^–the assigned currency’s isocode matches the one selected on the plugin UI

The price attribute is fetched from this entry.

Example:

Assuming the currency configured on the UI is EUR, the price used by the plugin will be 555. In case the product has no europe1Prices, it inherits the price of its immediate parent.

{
  "code": "aaa-111",
  "europe1Prices": [
    {
      "user": { ... },
      "price": 111
    },
    {
      "ug": { ... },
      "price": 222
    },
    {
      "pg": { ... },
      "price": 333
    },
    {
      "currency": {
        "isocode": "USD"
      },
      "price": 444
    },
    {
      "currency": {
        "isocode": "EUR"
      },
      "price": 555
    }
  ]
}

In the following example, the variant aaa-111-variant-1 inherits the price 555 from its parent as it does not have any europe1Prices attached. Please note that if there are europe1Prices present on the product but none of them can be considered default, then the price will be empty.

{
  "code": "aaa-111",
  "europe1Prices": [
    {
      "user": { ... },
      "price": 111
    },
    {
      "ug": { ... },
      "price": 222
    },
    {
      "pg": { ... },
      "price": 333
    },
    {
      "currency": {
        "isocode": "USD"
      },
      "price": 444
    },
    {
      "currency": {
        "isocode": "EUR"
      },
      "price": 555
    }
  ],
  "variants": [
    {
      "code": "aaa-111-variant-1"
    }
  ]
}

image

image is the URL attribute of the product's thumbnail, prefixed with the configured image domain.

Example:

In case the user has configured https://my-cool-shop.com as image domain, we will have https://my-cool-webshop.com/media/images/some-product-thumbnail.jpg as image.

{
  "thumbnail": {
    "URL": "/media/images/some-product-thumbnail.jpg"
  }
}

zoom_image

zoom_image is the URL attribute of the product's picture, prefixed with the configured image domain.

In case the user has configured https://my-cool-shop.com as image domain, we will have https://my-cool-webshop.com/media/images/some-product-picture.jpg as image.

{
  "picture": {
    "URL": "/media/images/some-product-picture.jpg"
  }
}

available

To determine a product’s availability, we check the attached stockLevels.

The product is flagged as available if one of the following criteria is met:

there is at least one entry where the in StockStatus code is forceInStock
there is at least one entry where the in StockStatus code is not forceOutOfStock and the available (quantity) is greater than zero

Example:

aaa-111 is available despite the available amount being zero, because the forceInStock flag is applied.

{
  "code": "aaa-111",
  "stockLevels": [
    {
      "available": 0,
      "inStockStatus": {
        "code": "forceInStock"
      }
} ]
}

bbb-222 is NOT available despite the available amount being greater than zero, because the forceOutOfStock flag is applied.

{
  "code": "bbb-222",
  "stockLevels": [
    {
      "available": 5,
      "inStockStatus": {
        "code": "forceOutOfStock"
      }
} ]
}

ccc-333 is available because the available amount is greater than zero.

{
  "code": "ccc-333",
  "stockLevels": [
    {
      "available": 5
} ]
}

ddd-444 is NOT available because the available amount is zero.

{
  "code": "ddd-444",
  "stockLevels": [{
      "available": 0
} ]
}

link

The plugin replaces the {{ code }} placeholder in the configured product URL template with the product's code.

Example:

In case the user has configured the product URL template https://my-cool-shop.com/products/{{ code }}, we will have https://my-cool-shop.com/products/aaa-111 as link.

{
  code: "aaa-111"
}

SAP Commerce Cloud integration is an on-going effort.

Order and refund sync for Smart Insight and Strategic Dashboard have an ETA of 2022.
Sales Data Sync (Order, Refund, Cancelation) is scoped and planned with the ETA of 2022.

Walk-through video

You can watch a brief video of the complete set up process:

Need assistance with your Emarsys product? We'll get you the help you need!

SAP

Setting up the Emarsys for SAP Commerce Cloud plugin

Before integrating

IP filtering

User creation

Data sync

Customer sync

Real-time events sync

Product sync

Product stock availability

item

group_id

title

brand

description

category

price

image

zoom_image

available

link

Walk-through video

Need assistance with your Emarsys product?
We'll get you the help you need!