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 |
| 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 |
| 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
This data feed should contain the history of orders made on your e-shop (we recommend the history of last 2 years). All the products must be containt in the products feed.
If you dont specify the price of the order, Samba will automatically take the current price of the product.
Samba is able to distinguish 3 states of order:
- finished
- created
- canceled
If you dont specify state of the order, Samba automatically takes the order as finished.
If your customers can finish an order without registration, use the element EMAIL instead of CUSTOMER_ID.
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>
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)