This post is also available in:
In order to run properly, Samba requires integration with the following data feeds:
If you created your e-shop via one of the supported e-commerce platforms, you don’t have to bother with data integration. Just follow the step-by-step guide here. If you use a different, unsupported platform, do not despair, we’re working on integration of other popular platforms. Until then, please, follow the step-by-step guide, which you can find below.
Links (publicly accessible, or containing access data in the format https: // username: password@youreshop.com/feedname.xml) to these feeds can be provided in the section Settings – Integrations – Data integration – Connection settings in Samba.
To save the changes, press Save configuration.
Once you have filled in all the data, press Refresh. Samba will download the feeds immediately according to your settings. You’ll usually see the output from our validation in minutes, so you can fix the errors.
Feeds are usually updated once a day.
Properities of the data feeds
- XML format
- UTF-8LE coding
- do NOT use unicode control characters (except the CR and LF characters)
Special characters &, >, <, \, ", ' must be escaped according to the official XML format specification or the so-called CDATA section must be used. I.e. for example instead of
- <VALUE>A&B <> C&D</Value>
use escaping
- <VALUE>A&B <> C&D</Value>
or use CDATA section as follows
- <VALUE><![CDATA[A&B <> C&D]]></Value>
It is important to maintain referential integrity between feeds, i.e. ID consistency across feeds. Make sure the product ID is the same in the product and order feed. The same goes for the customer ID in the orders and customers feed.
Products feed
This feed contains the database of all your products, that you offer on your e-shop. For the best results, we recommend to include as many optional parameters as possible. Thanks to this data feed, Samba is able to recognize the parameters of the products (type, brand, category, price category, color, size,….) and then offer this product to the right customer. Samba works with the stock informations and special offers as well, so it doesnt offer a product, that you dont have in stock and on the other hand, offers a product, that is on sale, more.
Supported parameters
| Name | Type | Required | Description |
|---|---|---|---|
| PRODUCT_ID | String | yes | product ID |
| TITLE | String | yes | product name |
| PRICE | Float, >=0 | yes | selling price (tax included, without shipping and handling) |
| URL | String | yes | product URL |
| IMAGE | String | no | product picture URL (approx 300x300 px) |
| DESCRIPTION | String | no | detail description of the product (without HTML tags) |
| BRAND | String | no | product brand |
| STOCK | Integer, >=0, default:1 | no | number of pieces in stock |
| PRICE_BEFORE_DISCOUNT | Float, >0, PRICE_BEFORE_DISCOUNT > PRICE | no | price before discount (tax included) |
| PRICE_BUY | Float, >0 | no | cost price of the product (for calculating profit margin) |
| CATEGORYTEXT | String | no | categories that include the product, seperated by "|" |
| PRODUCT_LINE | String | no | product line |
| VARIANT | Products list | no | see product variants below |
| SHOW | Boolean, default: TRUE | no | can we show this product? |
| PARAMETER | [par1,par2] | no | Other parameters (NAME does not have to be unique, please see example below) |
In case of multiple occurrence of a parameter with the same NAME, all relevant VALUEs are processed. As part of the filtering, it is possible to search among all values.
Example of the products feed
<?xml version="1.0" encoding="utf-8"?>
<PRODUCTS>
<PRODUCT>
<PRODUCT_ID>D45S8741545SD</PRODUCT_ID>
<BRAND>Značka</BRAND>
<TITLE>Name of the product</TITLE>
<DESCRIPTION>Detail description</DESCRIPTION>
<PRICE>40.1</PRICE>
<PRICE_BEFORE_DISCOUNT>42.1</PRICE_BEFORE_DISCOUNT>
<STOCK>60</STOCK>
<URL>http://www.mujeshop.cz/way/to/product</URL>
<IMAGE>http://www.mujeshop.cz/way/to/image.jpg</IMAGE>
<CATEGORYTEXT>Clothes | Women | T-Shirts</CATEGORYTEXT>
<PARAMETERS>
<PARAMETER>
<NAME>Color</NAME>
<VALUE>White</VALUE>
</PARAMETER>
</PARAMETERS>
<VARIANT>
<PRODUCT_ID>D45S8741545SD-XXL</PRODUCT_ID>
<TITLE>Name of the product</TITLE>
<DESCRIPTION>Detail description</DESCRIPTION>
<PARAMETERS>
<PARAMETER>
<NAME>Size</NAME>
<VALUE>XXL</VALUE>
</PARAMETER>
<PARAMETER>
<NAME>EAN</NAME>
<VALUE>467891186861118</VALUE>
</PARAMETER>
</PARAMETERS>
<PRICE>40.1</PRICE>
<STOCK>10</STOCK>
<IMAGE>http://www.mujeshop.cz/way/to/productXXL.jpg</IMAGE>
<URL>http://www.mujeshop.cz/way/to/product?variant=xxl</URL>
</VARIANT>
<VARIANT>
<PRODUCT_ID>D45S8741545SD-L</PRODUCT_ID>
<TITLE>Name of the product</TITLE>
<DESCRIPTION>Detail description</DESCRIPTION>
<PARAMETERS>
<PARAMETER>
<NAME>Size</NAME>
<VALUE>L</VALUE>
</PARAMETER>
<PARAMETER>
<NAME>EAN</NAME>
<VALUE>467891186861118</VALUE>
</PARAMETER>
</PARAMETERS>
<PRICE>40.1</PRICE>
<STOCK>10</STOCK>
<IMAGE>http://www.mujeshop.cz/way/to/productL.jpg</IMAGE>
<URL>http://www.mujeshop.cz/way/to/product?variant=l</URL>
</VARIANT>
</PRODUCT>
</PRODUCTS>
Customers feed
Customers feed should contain the whole database of your customers. Samba can adjust its personalization based on other metaparameters, such as gender or the date of registration.
Samba is able to distinguish 3 levels of newsletter subscription.
- every day
- special occasions
- never
The total limit on the number of customers (number of IDs) of your payment plan includes all that you can see in Samba in the “Audience and filters” section, ie.
- customers from the customers feed
- generated customers from the order feed (see below)
- imported customers through the Contact Management section
- collected customers using welcome popups
Deleted customers through the Contact Management are not included in the limit.
Supported parameters
| Name | Type | Required | Description |
|---|---|---|---|
| CUSTOMER_ID | String | yes | Customer ID |
| NEWSLETTER_FREQUENCY | Enum: every day | special occasions | never | yes | Subscription frequency (never = unsubscribed) |
| String | no | A valid email address | |
| REGISTRATION | Date & time (as a String) | no | Date and time of registration in the following format: YYYY-MM-DDThh:mm:ss.sTZD (more info), default: "1970-01-01" |
| FIRST_NAME | String | no | First name |
| LAST_NAME | String | no | Last name |
| ZIP_CODE | String | no | ZIP code |
| PHONE | String | no | Phone number with the Incl. plus sign and country code (e.g. "+420xxxxxxxxx" for Czech Republic, or +11234567890 for USA) |
| SMS_FREQUENCY | Enum: every day | special occasions | never | no | SMS subscription frequency (never = unsubscribed), default: "never" |
| DATA_PERMISSION | Enum: full | do_not_personalize | anonymized_only | no | default: "full" |
| NLF_TIME | Datetime (as string) | no | Datetime in the YYYY-MM-DDThh:mm:ss.sTZD format (more info) Time of the customer's subscription change |
| PARAMETERS | [par1,par2] | no | Other parameters (NAME does not have to be unique, please see example below) |
In case of multiple occurrence of a parameter with the same NAME, all relevant VALUEs are processed. As part of the filtering, it is possible to search among all values. When used in a template by inserting a dynamic variable, one of the values is used randomly.
This attribute gives Samba the information about the exact time, when customer changed their subscription status. If the unsubscribed customer resubscribes, Samba will know, which action should be prioritized. If the attribute is not present, information from Samba is prioritized – unsubscribing via the footer link, and/or through the Database Administration.
Customers provided with the value DATA_PERMISSION = anonymized_only will not be targeted by any channel. The system only uses their anonymized data (behavior patterns) in order to train our algorithms. You can find more information here.
Example of customers feed
<?xml version="1.0" encoding="utf-8"?> <CUSTOMERS> <CUSTOMER> <CUSTOMER_ID>D45S8741545SD</CUSTOMER_ID> <EMAIL>jan.novak@email.cz</EMAIL> <REGISTRATION>2014-12-31T03:53:43.962Z</REGISTRATION> <FIRST_NAME>Jan</FIRST_NAME> <LAST_NAME>Novák</LAST_NAME> <NEWSLETTER_FREQUENCY>every day</NEWSLETTER_FREQUENCY> <ZIP_CODE>15000</ZIP_CODE> <PARAMETERS> <PARAMETER> <NAME>Bonus points</NAME> <VALUE>100</VALUE> </PARAMETER> <PARAMETER> <NAME>Gender</NAME> <VALUE>female</VALUE> </PARAMETER> </PARAMETERS> </CUSTOMER> </CUSTOMERS>
Orders feed
Orders feed should ideally contain history of your orders, that happened on your eshop (we recommend the history to be at least 2 years old, but whole history is preffered or you can also use increments, as explained below). Samba uses this feed to analyse purchase patterns of your customers, which is then being used to personalise. All products in this data feed must be present in the product feed, or they will be marked as “Invalid orders” and ignored by the system.
If you don’t fill in the price of the product in the order, the price of the product (from the product feed) is used instead.
Samba currently supports 3 order states:
- finished – finished order, customer has paid or received the goods. This is the only state Samba is actually working with.
- created – order has been created and is waiting for finishing (payment, delviery, etc.).
- canceled – cancelled or deleted order (by the customer or the eshop).
If you do not fill the order state, Samba will see the order as finished. If the order is in finished state and the attribute FINISHED_ON is not present, the date value in CREATED_ON element is assumed as the date/time of finishing the order.
If you allow customers to create orders without registration, use the EMAIL element instead of CUSTOMER_ID and, if you can, PHONE and ZIP_CODE aswell. Samba will create audiences, which you can then use for targetting purposes during campaign creation.
If an unknown CUSTOMER_ID is specified (or is not specified at all) in the specific order and there is a customer (in customer feed) with the same EMAIL as used in this order, the order is then automatically assigned to the customer based on the EMAIL element. However, if there is no such EMAIL in the customer feed, then the value in EMAIL will be temporarily used as a new CUSTOMER_ID so that the order can be processed. Orders without valid EMAIL and CUSTOMER_ID will not be proccessed at all.
Based on your customer terms and conditions you can select the following option in the Connection settings for these customers:
Incremental order feed
After the first one-time load of the whole order data feed (based on the information above), it is possible to use increments for further order feed data loading, as you can see in the picture below:
If an unknown CUSTOMER_ID is specified (or is not specified at all) in the specific order and there is a customer (in customer feed) with the same EMAIL as used in this order, the order is then automatically assigned to the customer based on the EMAIL element. However, if there is no such EMAIL in the customer feed, then the value in EMAIL will be temporarily used as a new CUSTOMER_ID only as long as the order is part of the increment. At any time later, the customer is no longer generated and therefore the order is not processed, until a customer with a CUSTOMER_ID equal to EMAIL appears in the customer feed. Orders without valid EMAIL and CUSTOMER_ID will not be proccessed at all.
While using the increments, generally speaking only those items with their respective products in the product data feed will be processed. If you choose to use incremental data feeds, the loading will work as shown below in the following example:
- Samba has succesfully loaded the complete order data feed once and now we are using one-day increments.
- In ther example, we have order “Ord1” in the increment (from January 1st), which contains product called “Prod1”:
- On the january 1st, an increment of the order feed will be downloaded, which contains order “Ord1” and in the same time there is a “Prod1” in the product data feed. The order will be processed in this case.
- A day later (January 2nd) the order “Ord1” is no longer in the increment and the product “Prod1” is no longer in the product data feed. The order will not be processed in this case.
- The following day (January 3rd) the order “Ord1” is still not in the increment, but the product “Prod1” is again shown in the product data feed. The order will be processed again in this case.
As we can see, the determining moment for Samba is, whether the product is contained in the product data feed within the time of the last process of the increment – only in this case the data history is correctly saved. In the following days, the order will be processed again only in case the product is currently residing in the product data feed.
Supported parameters
ITEMS
| Name | Type | Required | Description |
|---|---|---|---|
| PRODUCT_ID | String | yes | ID of the product or its variant |
| AMOUNT | Number (integer, >0) | no | Quantity of the product (default: 1) |
| PRICE | Number (>=0) | no | Subtotal of all of the pieces of the product, tax included, without shipping and handling. |
If an ITEM in the order
- does not include PRICE, or
- has included PRICE with an error (e.g., it is empty, it is not a number, its a negative number),
then Samba will try to find its current price based on the PRODUCT_ID in the product feed. If the product does not exist in the product feed, the order item will not be processed.
If an item has a PRICE defined more than once in the order, the item will not be processed at all.
An order without valid items will not be processed.
In Samba analytical methods, only completed orders and items with positive prices are taken into consideration.
Example of orders feed
<?xml version="1.0" encoding="utf-8"?> <ORDERS> <ORDER> <ORDER_ID>5ds465d</ORDER_ID> <CUSTOMER_ID>d4s5a6sd6as</CUSTOMER_ID> <CREATED_ON>2014-12-31T03:53:43.962Z</CREATED_ON> <FINISHED_ON>2015-01-05T03:53:43.962Z</FINISHED_ON> <STATUS>finished</STATUS> <ZIP_CODE>15500</ZIP_CODE> <COUNTRY_CODE>CZ</COUNTRY_CODE> <ITEMS> <ITEM> <PRODUCT_ID>DAS656</PRODUCT_ID> <AMOUNT>6</AMOUNT> <PRICE>36</PRICE> </ITEM> </ITEMS> </ORDER> <ORDER> <ORDER_ID>35DS45</ORDER_ID> <EMAIL>jan.novak@email.cz</EMAIL> <CREATED_ON>2014-12-31T03:53:43.962Z</CREATED_ON> <FINISHED_ON>2015-01-05T03:53:43.962Z</FINISHED_ON> <STATUS>finished</STATUS> <ZIP_CODE>15500</ZIP_CODE> <COUNTRY_CODE>CZ</COUNTRY_CODE> <ITEMS> <ITEM> <PRODUCT_ID>DAS656</PRODUCT_ID> <AMOUNT>6</AMOUNT> <PRICE>36</PRICE> </ITEM> </ITEMS> </ORDER> </ORDERS>
Category feed
The category feed should include the tree of categories used in products feed. TITLE in this feed must correspond to CATEGORYTEXT in product feed.
Supported parameters
Example of category feed
<?xml version="1.0" encoding="utf-8"?>
<CATEGORY>
<ITEM>
<TITLE>Category</Title>
<URL>http://www.myeshop.cz/way/to/category</URL>
<ITEM>
<TITLE>Subcategory</Title>
<URL>http://www.myeshop.cz/way/to/Subcategory</URL>
</ITEM>
</ITEM>
<ITEM>
<TITLE>Category A</Title>
<URL>http://www.myeshop.cz/way/to/categorya</URL>
<ITEM>
<TITLE>Subcategory A</Title>
<URL>http://www.myeshop.cz/way/to/Subcategorya</URL>
<ITEM>
<TITLE>Subcategory B</Title>
<URL>http://www.myeshop.cz/way/to/Subcategoryb</URL>
</ITEM>
</ITEM>
</ITEM>
</CATEGORY>
GDPR states that you do have rights to do this, but you will have to make sure that you are eligible to do so (this is called “Legitimate Interest“). Also, be sure to have properly working “Unsubscribe” link in the footer of your newsletter.
This post is also available in: