Data structure
Overview
Non-normalized data (Cities, Regions, Towns, Receipts statuses) - the platform itself normalizes them during processing.
It is important to adhere to the correct data uploading sequence, because there are dependencies between entities. For example, the Nomenclature directory depends on the Merchandise classifier. In turn, Receipts depend on the Nomenclature reference guide and the Customer directory.
Recommended order of data uploading:
Product categories (product classifier);
Products (goods/nomenclature directory);
Customers;
Receipts;
Receipts lines;
Events;
Bonus balance;
Promo codes.
Customers
Recommended format of customer data:
local_id: internal identifier of the customer in the master system, string;
full_name: full name, string (can be empty) or set of three fields;
first_name: first name, string (can be empty);
middle_name: middle name, string (can be empty);
last_name: last name, string (can be empty);
register_date: registration date, yyyyy-mm-dd hh:mm:ss, string;
sex: M/F, char (can be empty);
email: e-mail, string (can be empty);
phone: phone number, string (can be empty);
push_id: push identifier, string (can be empty);
birth_date: date of birth, yyyyy-mm-dd, string (can be empty);
country: country, string (can be empty);
city: populated area, string (can be empty);
zip: postal code, string (can be blank);
<any other useful fields in customer questionnaire>.
Most fields can be empty, but the more customer data is uploaded to the Platform, the more flexible you can segment and personalize it.
The register_date field cannot be empty and include dates earlier than 2010 and greater than the current year.
If there are additional customer attributes that you would like to use, you can upload them to the Platform.
Receipts
Recommended data format for the receipt:
local_id: Internal receipt identifier in the master system, string;
client_id: Internal identifier of the customer in the master system, string (reference to client.local_id);
number: Receipt number (displayed to the customer), string (can be empty);
date: Receipt date, yyyyy-mm-dd hh:mm:ss, string;
status: Status (for the orders; in case of the receipts, it usually is not necessary), string (can be empty);
items_cnt: Quantity of product in receipt, float;
items_sum: Receipt total, money.
<any other useful fields that are in the receipt>.
If there are additional attributes you would like to use, you can transfer them to the Platform.
Statuses in the receipts should be transferred (and then updated) if the receipt is used to transfer data about the order (for example, for online stores), and there is a need to use scenarios tied to the change of order status. For example, when a customer has placed an order but does not pay for it for a long time, we encourage him/her to move on to pay for it. Or vice versa: when the money is received from the customer, we send him/her a notification that the money has been credited, and the order began to move in its statuses.
The date field cannot be empty and include dates earlier than 2010 and greater than the current year.
Receipt strings
Recommended data format of the receipt line:
local_id: Internal identifier of the receipt line in the master system, string;
client_order_id: Internal receipt identifier in the master system, string (reference to order.local_id);
date: Receipt date, yyyyy-mm-dd hh:mm:ss, string;
product_id: Internal product identifier in the master system, string;
price: The price of the product unit, money (can be empty);
cnt: The number of product units, float (can be empty);
sum: The sum of the string, money (can be empty);
<any other useful fields that are present in the receipt line>.
If there are additional attributes you would like to use, you can transfer them to the Platform.
The date field cannot be empty and should not include date earlier than 2010 and greater than the current year.
The price and sum fields must not contain spaces (e.g., 1 137 is not allowed).
Events
Recommended data format for the event:
local_id: Internal event identifier in the master system, string;
client_id: Internal identifier of the customer in the master system, string (reference to client.local_id);
date: Event’s date, yyyyy-mm-dd hh:mm:ss, string;
name: Event’s name, string;
context: Event’s context (string in JSON format), string.
Product categories
Recommended data format for product category classifier:
local_id: Internal identifier of product category in the master system, string;
parent_id: Internal identifier of the parent product category in the master system, string;
name: Name of the product category, string;
<any other useful fields that are present in the classifier>.
Products
Recommended data format for the product:
local_id: Internal product identifier in the master system, string;
name: Product name, string;
category_id: Internal identifier of product category in the master system (category.local_id), string;
sku: Stock keeping unit code, string (can be empty);
supplier: Supplier, string (can be empty);
brand: Brand, string (can be empty);
producer: Manufacturer, string (may be empty);
<any other useful fields that are present in the product>
Bonus balance
Bonus balance (when integrated with loyalty platform) can be transferred as a part of Customer entity or separately.
Recommended format for bonus balance transfer:
client_id: internal customer identifier in the master system, string (reference to client.local_id);
bonus_active: active bonuses, money;
bonus_expect_activate: bonuses awaiting activation, money (can be empty);
bonus_expect_deactivate: bonuses awaiting deactivation, money (may be empty);
bonus_expect_deactivate_next_date: the nearest date of bonuses deactivation, yyyyy-mm-dd hh:mm:ss, string (can be empty);
bonus_expect_deactivate_next_value: the nearest number of deactivated bonuses, money (can be empty).
Promo codes
Recommended data format for transferring promo codes to the Platform:
code: Text representation of the promo code, string;
group: Promo code group name, string.
Last updated