Data requirements for Commerce
In this section, we describe our standard data requirements for Commerce regarding Objects and Fields.
If you want to see a simplified overview of our data model, please read our dedicated guides:
As a starting point (default limit by contract), Splio CDP allows you to integrate up to 12 files (or BigQuery tables). Each file will be dedicated to a given kind of object, with its content conforming to the documented data requirements for the object.
Standard objects
Standard objects managed by Splio CDP:
Object | Definition | Importance | Kind | Mutable? | Standard retention period |
---|---|---|---|---|---|
user | Individuals, customers or prospects | Mandatory | Dimension | Yes | No retention |
store | Physical and online stores | Mandatory | Dimension | Yes | No retention |
product | Product catalog | Mandatory | Dimension | Yes | No retention |
purchase | The purchase transactions history | Mandatory | Event | No | 4 years |
cart | The abandoned carts | Optional | Event | No | 6 months |
refund | The refund transactions history (occurs when the user returns one or more several products and gets a refund) | Optional | Event | No | 4 years |
About objects and their fields
Few common traits to the Objects. Whenever an exception to this will exist, it will be documented in the concerned object's description page.
2 kinds of Objects can be distinguished:
- The Dimension kind which consists in mutable objects (they can be updated)
- The Event kind which consist in immutable objects (they should not and can not be updated)
Each Object:
- Has a unique identifier (sometimes also called primary key)
- e.g.
product
object has aproduct_id
field
- e.g.
- Is documented with 3 kinds of attributes:
- Mandatory attributes are necessary for Splio CDP to operate
- Recommended attributes are the ones that you should provide for an optimal use of Splio solutions
- Optional attributes are the ones you should be providing if you can because they are of common use for Commerce CRM activities (for various purpose, targeting, messages personnalization, reporting or analysis) or because Splio might add new features using it in the future.
- Can be extended with Custom Attributes you wish to be available in Splio CDP in order to better fit your specific business model and activity and take the most out of Splio CDP features.
- Has a pair of
created_at
andupdated_at
fields that allow:- To secure the data rules to be implemented on our side and give you more visibility on the data ingestion status
- Note that by default
updated_at
will be based on the file ingestion date if it is not provided in the source
Objects are linked together (e.g. the purchase object has a set of user_id
, product_id
, store_id
fields)
- So you are to provide consistent identifiers allowing for making necessary relations between objects
Custom dimensions and Custom events
In addition to standard objects, custom objects can be integrated if your use cases requires it. Those can be the Custom dimension or Custom event kind.
Whenever you think you have interesting data to push into Splio CDP that does not fit into the available standard objects, get in touch with your Project or Customer Success Manager to discuss the data specifications and associated use cases. It is most important to not only specify the custom data content, but also discuss associated marketing use cases as to ensure optimal integration of the data and operation experience of it.
Data types
Data types used as to express the requirements:
String
- Used for various kinds of information.
- Note that some fields (like identifiers for instance) while documented as
string
can contain any kind of alphanumeric values, including integer values.
Datetime
- Used when time information is generally available or relevant for using the information.
- To be transmitted with a timezone, in the form of
2022-02-29T18:34:26+01:00
. Whithout any timezone information (e.g.2022-02-29T18:34:26
), Splio assumes the information to be in UTC time.
Date
- Used when time information is generally not available or not relevant for using the information (e.g.
date_of_birth
). - To be transmitted in the form of
2023-06-15
(YYYY-mm-DD
).
- Used when time information is generally not available or not relevant for using the information (e.g.
Boolean
- To be transmitted in the form of
0
or1
values.
- To be transmitted in the form of
Decimal
- To be used for all monetary data. To be formatted with a dot separator, e.g.
12.90
.
- To be used for all monetary data. To be formatted with a dot separator, e.g.
Integer
- No occurrence in Splio standard data requirements, but
Integer
type is also available when required for custom fields.
- No occurrence in Splio standard data requirements, but
Returns and refunds
In most e-commerce solutions refunds are recorded in a dedicated object separate from the purchases, whereas most of the time in POS systems returns are recorded as purchase transactions which can also contain new purchased items at the same time.
So two situations can occur:
- If your source system records refunds and returns in dedicated objects, you need to implement the Refund event.
- If your source system records refunds and returns in the same objects as the purchases, with return lines eventually mixed with newly purchased items, then you are to implement the Purchase event only.
- Having returns managed through an update of the original purchase object (adding or modifying lines) is not supported. Whenever the source system manages it this way, get back to your Project or Customer Success Manager in order to discuss and specify custom data integration specifics.
Note that in both situations, for returns (or refunds) lines, amounts, and quantities are to be signed negatively (opposite sign from the initial purchase line) while the unit price remains positive.
Multi-currency setup
Currency Management
If you are operating in multiple currencies, the amount charged to your customer will be in the
presentment_currency
(used in Splio for example for personalization) and the one received in your bank account will be in thebase_currency
(used in Splio for example in your dashboards or RFM).Splio systems need to have one
base_currency
per tenant in order to function properly.
As currencies conversion rates are very volatile and maybe quite different depending on your Payment Service Provider, Splio systems do not convert amounts between currencies.
- Currencies need to be codified according to ISO-4217 (for example EUR, USD…).
- We need to have a
base_currency
that is the same for a single tenant, whatever the currency used to charge your customer. - In case you are operating in more than one currency, data can be enriched with a
presentment_currency
and product prices in many currencies that will be usable for message personalization.- Example of a brand operating sales in a single currency, for example, EUR:
In a purchase file, is included:currency=EUR
,total_amount=53.00
In a product file, is included:currency=EUR
,price=10.00
- Example of a brand operating sales in many currencies, but consolidating sales in EUR:
In a purchase file, for a sale that was operated in USD:
Is included:currency=EUR
,total_amount=53.00
,presentment_currency=USD
,presentment_total_amount=59.33
In a product file, is includedcurrency=EUR
,price=10.00
,price_EUR=10.00
,price_USD=11.20
- For more details, see Product dimension, Purchase event, Cart event and Refund event documentation
- Example of a brand operating sales in a single currency, for example, EUR:
Updated 3 months ago