You must format your store data file according to the specifications and guidelines described below.
Before you start
What is store data?
Store data contains all the information related to your stores, including store identifiers, store names, open dates, country or region codes, addresses, etc.
Store data allows you to connect your store and sales data and it provides you with a new segment creation capability (e.g. you can create segments to reach your contacts who make purchases only in offline stores.)
Important
If you upload store data files that contain updates compared to your original data set, then existing data will be overwritten.
How shall I update the store data file?
You need to upload your store data file to the Smart Insight SFTP if you would like to use the following features:
You need to configure your store data during Smart Insight onboarding. For more information, see Smart Insight Self-Service tool - Configuring your store data.
How often do I need to upload store data?
After making the initial upload of your historical store data, we recommend that you upload new store data when any of the data fields change (e.g. when a new store is opened or an old one is closed).
- From time to time, we recommend uploading your entire store data for maintenance purposes.
- Smart Insight will process these store data files in an aggregated manner only once a day.
General rules for your data file
The process of importing your store data file will fail if it does not pass all our validation checks. You must make sure that the file is correctly formatted as described below.
The columns in the header of your store data file must be in the order that was agreed during the Smart Insight onboarding implementation.
- Your store data file should be a simple .csv table, with each row describing the attributes of a single line item.
- Your file must start with a header row (e.g. the field names).
- The file name must follow the convention
store*.csv. In other words, the file name must begin with the stringstoreand its extension must be .csv, while you can replace the asterisk with a number of characters of your choice (e.g. a timestamp). - Use a CSV export library that is compatible with the standard CSV format.
- Use a comma to separate fields in a row.
- When a field does not have any value, leave it empty. For example:
value1,,value3,value4. - Do not use newline characters, either unquoted or quoted, in the fields.
- Use UTF-8 encoding.
- Include the field names in the first row (header) and make sure that all the subsequent rows contain the values corresponding to the fields listed in the header. If you are not sure how to do this, contact Emarsys Support.
- Do not use more than 255 columns.
- Do not use field values longer than 64 KB.
Required fields
Standard field set
These fields are required for the standard feature set in Emarsys.
- Although only
store_idandnameare required fields, the store data .csv file must include all the other fields listed in the following table even if they only have empty values, otherwise the store data file upload will fail. - Fields of the type Float cannot contain empty strings. For example, single
''or double quotes""with empty values are not accepted. If the store data file you would like to upload contains a Float field with aNULLvalue, then please leave it empty. For example:value1,,value3,value4.
| Field | Required | Type | Example | Description |
|---|---|---|---|---|
store_id |
Yes |
String | "87" | ID of the store’s location used by the client. |
name |
Yes | String | “Tokyo" | The name of the store. |
open_date |
Optional | Timestamp | "2019-01-31" |
The date when the store was opened (the date format is YYYY-MM-DD). |
country_code |
Optional | String | “DE” |
The store’s country or region code (the format is ISO 3166). |
city |
Optional | String | “Munich” |
The city where the store is located (in English). |
address |
Optional | String | "21 Caledonian Road" | The address of the store. |
postal_code |
Optional | String | "80339" | The postal code (zip) of the store. |
latitude |
Optional | Float | "-47.5075" | Latitude of the store’s GPS coordinates. Important: The value of the latitude field must be between -90 and 90. |
longitude |
Optional | Float | "19.0237" | Longitude of the store’s GPS coordinates. Important: The value of the longitude field must be between -90 and 90. |
size |
Optional | Float | "60" | The floor area of the store (in square meters). |
category |
Optional | String | "outlet", “luxury”, “general" | The store's custom type. |
Custom fields
Besides the mandatory store data fields, you can also add other information to your store data file for filtering purposes by using custom fields. The names of custom fields must begin with a prefix specifying the data type. The prefix then must be followed by an underscore (_) and the name of the custom column. If the name of a field consists of multiple words, then each word must start with a lowercase letter and each word should be separated by an underscore. For example, s_original_currency.
Available custom field prefixes:
- Custom fields are validated for data type and if the submitted values are not consistent with the expected data type, the store data file will be rejected.
- Custom fields can be empty.
- Fields of the type Float cannot contain empty strings. For example, single
''or double quotes""with empty values are not accepted. If the store data file you would like to upload contains a Float field with aNULLvalue, then please leave it empty. For example:value1,,value3,value4.
| Prefix | Type | Example |
|---|---|---|
i_* |
Integer | i_customer_age |
f_* |
Float | f_customer_height |
t_* |
Timestamp | t_date_of_manufacture |
s_* |
String | s_book_author |
Store data example
The following example shows how a store data file might look:
"store_id","name","category","open_date","country_code","city","address","postal_code","latitude","longitude","size"
"NWYRK","New York","Luxury","2015-03-29","USA","New York",,,,,
"SDNY","Sidney","General","2016-03-29","AUS","Sidney",,,,,
"NWDLH","New Delhi","Outlet","2017-03-29","IND","New Delhi",,,,,
"TKY","Tokyo","General","2018-04-12","JPN","Tokyo",,,,,
"VNN","Vienna","General","2016-01-17","AUT","Vienna",,,,,
"MLN","Milano","Luxury","2019-06-06","ITA","Milano",,,,,
"SHNGH","Shanghai","Luxury","2018-12-01","CHN","Shanghai",,,,,
"BSTN","Boston","General","2017-10-03","USA","Boston",,,,,
"SNTPTRSBRG","Saint Petersburg","General","2017-02-15","RUS","Saint Petersburg",,,,,The commas at the end of the rows stand for the values that are NULL. In this specific example it is the last five for each store.