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:

• if you are using Splio CDP, with or without the Predictive AI add-on
• if you are using CRM Copilot

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:

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 a product_idfield
• 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 and updated_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).
• Boolean
  • To be transmitted in the form of 0 or 1values.
• Decimal
  • To be used for all monetary data. To be formatted with a dot separator, e.g. 12.90.
• Integer
  • No occurrence in Splio standard data requirements, but Integertype is also available when required for custom fields.

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 included currency=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