Data Feeds

In order to run properly, Samba requires integration with the following data feeds:

• Products
• Customers
• Orders
• Categories (optional)

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.

Properities of the data feeds

• XML format
• UTF-8LE coding
• do NOT use unicode control characters (except the CR and LF characters)
• make sure, that product ID is the same in the feed of products and orders. The same applies to the customer ID in orders and customers feed.

Feeds are usually updated once a day.

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	Optional?	Description
PRODUCT_ID	String	no	product ID
TITLE	String	no	product name
PRICE	Float, >0	no	price (tax included)
URL	String	no	product URL
IMAGE	String	yes	product picture URL (approx 300x300 px)
DESCRIPTION	String	yes	detail description of the product (without HTML tags)
BRAND	String	yes	product brand
STOCK	Integer, >=0, default:1	yes	number of pieces in stock
PRICE_BEFORE_DISCOUNT	Float, >0	yes	price before discount (tax included)
PRICE_BUY	Float, >0	yes	actual price displayed on e-shop
CATEGORYTEXT	String	yes	categories that include the product, seperated by "|"
PRODUCT_LINE	String	yes	product line
VARIANT	Products list	yes	see product variants below
SHOW	Boolean, default: TRUE	yes	can we show this product?
PARAMETER	[par1,par2]	yes	other parameters of the product, see the example below

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>42.1</PRICE>
                     <PRICE_BEFORE_DISCOUNT>40.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</NAME>
                                         </PARAMETER>
                                         <PARAMETER>
                                                   <NAME>EAN</NAME>
                                                   <VALUE>467891186861118</VALUE>
                                         </PARAMETER>
                               <PARAMETERS>
                               <PRICE>42.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>
           </PRODUCT>
 </PRODUCTS>

Customer feed

Customer 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

Supported parameters

Name	Type	Optional?	Description
CUSTOMER_ID	String	no	Customer ID
NEWSLETTER_FREQUENCY	Enum: Every day | Special occasions | Never	no	Subscription frequency
EMAIL	String	yes	A valid email address
REGISTRATION	Date & time (as a String)	yes	Date and time of registration in the following format: YYYY-MM-DDThh:mm:ss.sTZD (more info)
FIRST_NAME	String	yes	First name
LAST_NAME	String	yes	Last name
ZIP_CODE	String	yes	ZIP code
PHONE	String	yes	Phone number with the Incl. plus sign and country code (e.g. "+420xxxxxxxxx" for Czech Republic)
SMS_FREQUENCY	Enum: Every day | Special occasions | Never	yes	SMS subscription frequency
DATA_PERMISSION	Enum	no	full | do_not_personalize | anonymized_only 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]	yes	Other parameters (please see example below)

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). 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.

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 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 there is a customer (in customer feed) with specific EMAIL and unknown CUSTOMER_ID is presented (or is not there at all), the order is then assigned to the customer based on their  EMAIL element. In the opposite case, the value in EMAIL is going to be used to create a new Customer_ID. Orders without valid EMAIL and/or CUSTOMER_ID will not be proccessed.

Based on your customer terms and conditions you can select the following option in the Connection settings for these customers:

Supported parameters

ITEMS

Name	Type	Optional?	Description
PRODUCT_ID	String	no	ID of the product or its variant
AMOUNT	Number (integer, >0)	yes	Quantity of the product (default: 1)
PRICE	Number (>0)	yes	Subtotal of all of the pieces of the product, tax included. (default: PRICE from product feed)

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</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>

 </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>

This post is also available in: Čeština (Czech)