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

NameTypeOptional? Description
PRODUCT_IDStringnoproduct ID
TITLEStringnoproduct name
PRICEFloat, >0noprice (tax included)
URLStringnoproduct URL
IMAGEStringyesproduct picture URL (approx 300x300 px)
DESCRIPTIONStringyesdetail description of the product (without HTML tags)
BRANDStringyesproduct brand
STOCKInteger, >=0, default:1yesnumber of pieces in stock
PRICE_BEFORE_DISCOUNTFloat, >0yesprice before discount (tax included)
PRICE_BUYFloat, >0yesactual price displayed on e-shop
CATEGORYTEXTStringyescategories that include the product, seperated by "|"
PRODUCT_LINEStringyesproduct line
VARIANTProducts listyessee product variants below
SHOWBoolean, default: TRUEyescan we show this product?
PARAMETER[par1,par2]yesother 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

NameTypeOptional?Description
CUSTOMER_IDStringnoCustomer ID
NEWSLETTER_FREQUENCYEnum: Every day | Special occasions | NevernoSubscription frequency
EMAILStringyesA valid email address
REGISTRATIONDate & time (as a String)yesDate and time of registration in the following format: YYYY-MM-DDThh:mm:ss.sTZD (more info)
FIRST_NAMEStringyesFirst name
LAST_NAMEStringyesLast name
ZIP_CODEStringyesZIP code
PHONEStringyesPhone number with the Incl. plus sign and country code (e.g. "+420xxxxxxxxx" for Czech Republic)
SMS_FREQUENCYEnum: Every day | Special occasions | NeveryesSMS subscription frequency
DATA_PERMISSIONEnumnofull | do_not_personalize | anonymized_only
default: full
NLF_TIMEDatetime (as string)noDatetime in the YYYY-MM-DDThh:mm:ss.sTZD format (more info)
Time of the customer's subscription change
PARAMETERS[par1,par2]yesOther parameters (please see example below)
<NLF_TIME> attribute

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.

<DATA_PERMISSION> attribute

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.

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.

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

NameTypeOptional?Description
PRODUCT_IDStringnoID of the product or its variant
AMOUNTNumber (integer, >0)yesQuantity of the product (default: 1)
PRICENumber (>0)yesSubtotal 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>
Do I have the rights to subscribe unregistered customers who made an order?

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: Čeština (Czech)

Updated on September 15, 2020

Was this article helpful?

Related Articles