Setup

Introduction

The purpose of this article is to share the Actito e-commerce data model, explaining which entities and attributes compose it, and how the data is fetched from the CMS.

Actito provides a simple way to collect data without any IT involvement from major e-commerce CMS platforms such as Shopify, Magento, or PrestaShop.
However, if you have developed your own e-commerce CMS, modified a standard integration, or use a non-compatible feature of one of the CMS above, you will need to manage the data synchronization yourself.
By following the recommendations below, you will still be able to benefit from all the features included in the e-commerce add-on.

danger

Forbidden actions on the e-commerce database

• Do not modify the structure of the orders, order lines, abandoned cart, or abandoned cart lines tables (e.g., adding, removing, or renaming fields).
• Do not change any table parameters, such as table names, field names, table links, triggers, or cleanup rules.
• Do not delete the customers, orders, order lines, abandoned cart, or abandoned cart lines tables.
• Do not synchronize these tables through another channel (ETL, API, or manual import) if they are already synchronized via the Actito connector.

info

Allowed actions on the e-commerce database

• Add new tables to store additional data types based on your use case.
• Add new fields to the profile table.
• Synchronize any newly created tables.
• Add new subscriptions.
• Add new segments.
• Synchronize the profile table with multiple data sources (be cautious when a field is updated by more than one source).

Features of the e-commerce solution

The e-commerce solution is a bundle of features designed to help marketers manage their business efficiently, without IT constraints.

The bundle includes:

• A data model tailored for e-commerce

  • A multi-table model that stores key customer information (accounts, orders, abandoned carts, etc.)

• A connector to import data from your e-commerce CMS

  • Supported CMS platforms: Magento, PrestaShop, Shopify

• Marketing insights

  • Prebuilt segments to classify your customers (e.g., New Buyers, Potential Purchasers, New Subscribers, Engaged 3 Months, etc.)
  • An RFM matrix to identify your most and least valuable customers and define strategic actions.
  • A dashboard providing e-commerce insights related to your marketing activity (optional paid feature).

• Activation strategies

  • Prebuilt customer journeys to easily launch your first campaigns and quickly increase your turnover.

• Content management

  • Automatically prefill your email campaigns with product information retrieved from your CMS, saving time and reducing the risk of errors.

Actito Environment

Overview of the solution

When the e-commerce solution is deployed, a new database named Customers is created by default.

This database is synchronized with your e-commerce CMS via an Actito-owned connector.

The e-commerce solution provides marketers with all relevant data related to customer accounts, orders, and abandoned carts.
Newsletter subscriptions are also synchronized bidirectionally: from the CMS to Actito and from Actito back to the CMS.

info

The e-commerce solution can also be deployed on an existing profile table.
In this case, no new database is created, and all the features described above will be available from the existing table.

You may also use the e-commerce solution without the Actito connector.
In that case, you must handle data exchanges yourself via the Actito Integration Framework.
For more details, refer to the section “Data synchronization without the Actito connector.”
Finally, several e-commerce solutions can coexist under the same Actito license.

Database

Overview

info

Actito’s data model is a multi-table data model centered on the profile concept.

A profile represents an identified person targeted by a marketing campaign.
All imported data must be directly or indirectly linked to a profile.

E-commerce data model schema

PK = Primary key
FK = Foreign key

Profile definition

This section defines the profile concept for the e-commerce solution.

note

This information applies only if the profile table is created during the e-commerce solution setup.
If an existing profile table is used, its definition prevails.

danger

• Deploying the e-commerce solution on an existing profile table does not automatically add new attributes, except for predefined segmentations.
  If you wish to synchronize additional attributes with the Actito connector, you must create them before deploying the e-commerce solution.
  See this article for details.
• Ensure that the existing profile table configuration is compatible with the e-commerce solution (profile uniqueness and mandatory fields must be respected).

Unicity of a Profile

Profile uniqueness is defined by either the email address or the customer account ID from your e-commerce CMS.

Profile creation or update operations are based on this key.
This data is mandatory for:

• Creating or updating a profile in the database
• Linking business information such as orders or abandoned carts

It is also possible to define both as keys.
In this configuration, the email address is set as the main unique and mandatory key, while the account ID is unique but optional.
In this case, business data such as orders or abandoned carts are linked to the profile using the email address.

How to choose the right key

Key	Inject new profiles from other data sources	Update email address from customer account	Guest checkout*
accountId	Only from data sources that provide the customer Account ID from the e-commerce CMS	Possible	Not possible
emailAddress	Only from data sources that provide the email address	Not possible	Possible
emailAddress & accountId**	From data sources that provide either the email address or the customer Account ID	Possible	Possible

* Many e-commerce CMSs require shoppers to create an account before purchasing. If this setting is disabled, shoppers can complete a guest checkout without creating an account.
** Using both keys can cause synchronization issues. If profile data refers to two different profiles (e.g., Account ID → Profile A and Email Address → Profile B), the operation (create or update) cannot be completed and will be rejected.

Email Subscription

The e-commerce solution includes management of a single email subscription.
By default, the subscription name in the data model is Newsletter.

When deploying the e-commerce solution on an existing data model, you can select which Actito subscription to synchronize with the standard email subscription field in your e-commerce customer account.

Mandatory Fields

info

A field defined as mandatory must be provided when creating a new profile.
Otherwise, the profile will be rejected during the import process.
This rule applies to all data injection methods (e-commerce connector, API, automatic file import, manual import, web form, or user interface).

By default, no field in the profile table is mandatory except the defined profile key.

If the e-commerce solution is deployed on an existing profile table, ensure that all mandatory fields in the target table can be populated from the customer account data in your e-commerce CMS.

Unicity of the Email Address

info

In Actito, a profile can own only one email address.
Warning: If the email address field is not set as unique, multiple profiles with the same email may receive the same campaign multiple times.
To prevent this, Actito offers an option to send only one communication per email address (randomly selecting one profile).

If profile uniqueness is defined by	Email address set as unique
accountId	NO
emailAddress	YES
emailAddress + accountId	YES

Unicity of the Mobile Phone Number

info

In Actito, a profile can own only one mobile phone number.
Warning: If the mobile phone number field is not unique, multiple profiles sharing the same number may receive the same SMS campaign multiple times.
To prevent this, Actito provides an option to send only one message per phone number (randomly selecting one profile).

The mobile phone number is set as not unique by default.

Unicity of the Account ID

If profile uniqueness is defined by	Account ID set as unique
accountId	YES
emailAddress	NO
emailAddress + accountId*	YES

* Warning: Using double keys can lead to synchronization issues.
If the imported profile data refers to two different profiles (e.g., Account ID → Profile A and Email Address → Profile B), the operation (create or update) cannot be performed and will be rejected.

Segmentations

The e-commerce solution provides 8 predefined segments.

Purchase-behavior-based segmentations

Segmentation name	Type	Rule definition
Client churn risks	Simple	Email address is known (reachable) AND Newsletter subscription is true AND Number of orders ≥ 1 AND Last order (by creation date) is less than 180 days old AND No orders in the last 6 months AND Actito engagement score is “Bad” or “Low” (last activity is old)
Potential purchasers	Simple	Engagement score is “Fair”, “Good”, or “Very good” AND No orders (Order ID unknown) AND Email address is known AND Newsletter subscription is true
New buyers	Simple	Number of orders = 1 AND Last order is less than 30 days old AND Email address is known AND Newsletter subscription is true
VIP customers	Simple	Number of orders ≥ 5 AND Last order is less than 120 days old AND Email address is known AND Newsletter subscription is true

Email-behavior-based segmentations

Segmentation name	Type	Rule definition
Unengaged	Simple	Profile created more than 90 days ago AND No email opens in the last 90 days
New subscribers	Simple	Profile created less than 14 days ago AND Newsletter subscription is true
Engaged 3 months	Simple	Profile created more than 90 days ago AND (Email open or click in the last 90 days)
Unengaged 1 year	Simple	Profile created more than 365 days ago AND (Email open or click in the last 365 days)

Table Definition

Technical name	Customers
Display name	Customers
Type of table	Profile

Attributes

#	Technical name	Display name	Type	Constraints	Actito standard attribute
1	accountId	accountId	STRING	Max 255 chars; can be unique/mandatory depending on settings	-
2	firstName	firstName	STRING	Max 64 chars	firstName
3	lastName	lastName	STRING	Max 64 chars	lastName
4	emailAddress	emailAddress	STRING	Max 255 chars; can be unique/mandatory depending on settings	emailAddress
5	sex	sex	STRING	Values: M (male), F (female)	sex
6	birthDate	birthDate	DATE	Format: yyyy-mm-dd	birthDate
7	addressCompany	addressCompany	STRING	Max 255 chars	-
8	VATNumber	VATNumber	STRING	Max 255 chars	-
9	addressStreet	addressStreet	STRING	Max 255 chars	addressStreet
10	addressLocality	addressLocality	STRING	Max 50 chars	addressLocality
11	addressCountry	addressCountry	STRING	2 chars, ISO 3166-1 format (e.g., FR, BE, DE)	addressCountry
12	addressRegion	addressRegion	STRING	Max 255 chars	-
13	addressPostalCode	addressPostalCode	STRING	Max 10 chars	addressPostalCode
14	mobilePhoneNumber	mobilePhoneNumber	STRING	Include international prefix; allowed chars: + ( ) . - / 0–9	gsmNumber
15	customerGroup	customerGroup	STRING	Max 255 chars	-
16	source	source	STRING	Max 255 chars	-
17	motherLanguage	motherLanguage	STRING	ISO 639-1, 2 chars	motherLanguage

Subscriptions

#	Technical name	Display name	Type	Constraints	Actito standard attribute
1	Newsletter	Newsletter	BOOLEAN	true/false	subscription

Segmentations

#	Technical name	Display name	Type	Constraints	Actito standard attribute
1	Client churn risks	Client churn risks	STRING	member / null	simple segmentation
2	Potential purchasers	Potential purchasers	STRING	member / null	simple segmentation
3	New buyers	New buyers	STRING	member / null	simple segmentation
4	VIP customers	VIP customers	STRING	member / null	simple segmentation
5	Unengaged	Unengaged	STRING	member / null	simple segmentation
6	New subscribers	New subscribers	STRING	member / null	simple segmentation
7	Engaged 3 months	Engaged 3 months	STRING	member / null	simple segmentation
8	Unengaged 1 year	Unengaged 1 year	STRING	member / null	simple segmentation

Definition of the Business Tables of the E-commerce Solution

This section describes the configuration of the business tables used in the e-commerce solution.

Orders Table

This table stores all orders associated with a customer account.

Table definition

Parameter	Value
Technical name	orders
Display name	Orders
Type of table	Interactions
Profile table linked	Refer to the profile table name
Creation time column (mandatory)	creationMoment
Primary key	orderId
Auto-incremental key	No
Composite key	No
Integrity check	No

Attributes

#	Technical name	Display name	Type	Constraints	Foreign key
1	orderId	orderId	STRING	Mandatory, unique, max 255 characters	-
2	reference	reference	STRING	Max 255 characters	-
3	currency	currency	STRING	Max 255 characters	-
4	date	date	TIMESTAMP	Format: YYYY-MM-DD hh:mm:ss	-
5	total	total	NUMBER	Integers or long; positive numbers without +; negative numbers with -; decimal separator .	-
6	totalExclTax	totalExclTax	NUMBER	Same as total	-
7	totalInclTax	totalInclTax	NUMBER	Same as total	-
8	shipping	shipping	NUMBER	Same as total	-
9	shippingOption	shippingOption	STRING	Max 255 characters	-
10	paymentMethod	paymentMethod	STRING	Max 255 characters	-
11	couponCode	couponCode	STRING	Max 255 characters	-
12	status	status	STRING	Max 255 characters	-
13	shopId	shopId	STRING	Max 255 characters	-
14	shopName	shopName	STRING	Max 255 characters	-
15	emailAddress or accountId*	emailAddress or accountId	STRING	Mandatory, max 255 characters	Profile table

* Depends on the profile key defined during setup.

Limit and Cleaning Rules

Parameter	Value
Amount of data	10 million rows
Behavior when a profile is deleted	No action
Cleaning rule	Not set

Events

Event name	Trigger	Rules definition
New order	CREATE ROW	-

Order Lines Table

This table stores individual order lines associated with a customer account and an order.

Table definition

Parameter	Value
Technical name	orderLines
Display name	Order Lines
Type of table	Interactions
Profile table linked	Refer to the profile table name
Creation time column (mandatory)	creationMoment
Primary key	orderDetailId
Auto-incremental key	No
Composite key	No
Integrity check	Profile known, order known

Attributes

#	Technical name	Display name	Type	Constraints	Foreign key
1	orderId	orderId	STRING	Mandatory, max 255 characters	Orders table
2	orderDetailId	orderDetailId	STRING	Mandatory, unique, max 255 characters	-
3	orderReference	orderReference	STRING	Max 255 characters	-
4	sku	sku	STRING	Max 255 characters	-
5	description	description	STRING	Max 255 characters	-
6	name	name	STRING	Max 255 characters	-
7	quantity	quantity	NUMBER	Integers or long; positive numbers without +; negative numbers with -; decimal separator .	-
8	unitPrice	unitPrice	NUMBER	Same as quantity	-
9	unitPriceExclTax	unitPriceExclTax	NUMBER	Same as quantity	-
10	unitPriceInclTax	unitPriceInclTax	NUMBER	Same as quantity	-
11	productUrl	productUrl	STRING	Max 255 characters	-
12	pictureUrl	pictureUrl	STRING	Max 255 characters	-
13	shopId	shopId	STRING	Max 255 characters	-
14	shopName	shopName	STRING	Max 255 characters	-
15	emailAddress or accountId*	emailAddress or accountId	STRING	Mandatory, max 255 characters	Profile table

* Depends on the profile key defined during setup.

Limit and Cleaning Rules

Parameter	Value
Amount of data	10 million rows
Behavior when a profile is deleted	No action
Behavior when an order is deleted	No action
Cleaning rule	Not set

Events

Event name	Trigger	Rules definition
New order line	CREATE ROW	-

Abandoned Carts Table

This table stores abandoned carts associated with a customer account.

Table definition

Parameter	Value
Technical name	abandonedCarts
Display name	Abandoned Carts
Type of table	Interactions
Profile table linked	Refer to the profile table name
Creation time column (mandatory)	creationMoment
Primary key	abandonedCartId
Auto-incremental key	No
Composite key	No
Integrity check	Profile known

Attributes

#	Technical name	Display name	Type	Constraints	Foreign key
1	orderId	orderId	STRING	Mandatory, max 255 characters	-
2	reference	reference	STRING	Max 255 characters	-
3	currency	currency	STRING	Max 255 characters	-
4	total	total	NUMBER	Integers or long; positive numbers without +; negative numbers with -; decimal separator .	-
5	totalExclTax	totalExclTax	NUMBER	Same as total	-
6	totalInclTax	totalInclTax	NUMBER	Same as total	-
7	status	status	STRING	Max 255 characters	-
8	abandonedSinceMoment	abandonedSinceMoment	TIMESTAMP	Format: YYYY-MM-DD hh:mm:ss	-
9	shopId	shopId	STRING	Max 255 characters	-
10	shopName	shopName	STRING	Max 255 characters	-
11	emailAddress or accountId*	emailAddress or accountId	STRING	Mandatory, max 255 characters	Profile table

* Depends on the profile key defined during setup.

Limit and Cleaning Rules

Parameter	Value
Amount of data	10 million rows
Behavior when a profile is deleted	No action
Cleaning rule	Not set

Events

Event name	Trigger	Rules definition
New abandoned cart	CREATE ROW	-

Abandoned Cart Lines Table

This table stores individual abandoned cart lines associated with a customer account.

Table definition

Parameter	Value
Technical name	abandonedCartLines
Display name	Abandoned Cart Lines
Type of table	Interactions
Profile table linked	Refer to the profile table name
Creation time column (mandatory)	creationMoment
Primary key	abandonedCartDetailId
Auto-incremental key	No
Composite key	No
Integrity check	Profile known, abandoned cart known

Attributes

#	Technical name	Display name	Type	Constraints	Foreign key
1	abandonedCartId	abandonedCartId	STRING	Max 255 characters	Abandoned Carts table
2	abandonedCartDetailId	abandonedCartDetailId	STRING	Mandatory, unique, max 255 characters	-
3	abandonedCartReference	abandonedCartReference	STRING	Max 255 characters	-
4	sku	sku	STRING	Max 255 characters	-
5	description	description	STRING	Max 255 characters	-
6	name	name	STRING	Max 255 characters	-
7	quantity	quantity	NUMBER	Integers or long; positive numbers without +; negative numbers with -; decimal separator .	-
8	unitPrice	unitPrice	NUMBER	Same as quantity	-
9	unitPriceExclTax	unitPriceExclTax	NUMBER	Same as quantity	-
10	unitPriceInclTax	unitPriceInclTax	NUMBER	Same as quantity	-
11	productUrl	productUrl	STRING	Max 255 characters	-
12	pictureUrl	pictureUrl	STRING	Max 255 characters	-
13	shopId	shopId	STRING	Max 255 characters	-
14	shopName	shopName	STRING	Max 255 characters	-
15	emailAddress or accountId*	emailAddress or accountId	STRING	Mandatory, max 255 characters	Profile table

* Depends on the profile key defined during setup.

Limit and Cleaning Rules

Parameter	Value
Amount of data	10 million rows
Behavior when a profile is deleted	No action
Cleaning rule	Not set

Events

Event name	Trigger	Rules definition
New abandoned cart line	CREATE ROW	-

Data Synchronization

Through the Connector Designed by Actito

Synchronization Mode

The connector is available for the following e-commerce CMS versions:

• Magento Open Source v2.0 to v2.4.5
• PrestaShop v1.6 to v1.7
• Shopify

Data is synchronized through API to inject information into Actito in real time.

Profile Table

Main Information

Parameter	Value
Technical name of the linked table	Refer to the profile table linked to the e-commerce solution set in the setup kit
Entity	Refer to the entity set in the setup kit
Import mode	Create and Update

Important Notes

• Every minute, Actito polls for new or updated customers since the last synchronization.
• When a new order is synchronized, the system also checks for updates in the related profile.
• Profiles missing mandatory fields on the Actito side are rejected during import.
• Invalid values in any field result in rejection of the profile during import.

Newsletter Subscription

When using the connector to fetch data from the e-commerce CMS, Actito follows the CMS as the authoritative source. The connector manages the following data flows:

• Updates the email subscription from the e-commerce CMS to Actito.
• Updates the email subscription from Actito to the e-commerce CMS.

The subscription is linked to the standard email subscription field in the e-commerce customer account.

CMS	Attribute
Magento 2.X	extension_attributes[is_subscribed] from table customers
PrestaShop	newsletter from table customers
Shopify	accepts_marketing from table customers

Rules and Mapping Between E-commerce CMS and the Data Model

• If the connector is linked to an existing profile table, it is possible to map the data exported from the connector to the profile table. This mapping must be documented in the SET_KIT document. Without mapping, fields will not be synchronized.
• If the default profile table named Customers provided by the e-commerce solution is used, refer to the Mapping and Rules documents below.
  Note: All fields are available in the data model, even if they cannot be retrieved from the e-commerce CMS.

CMS	Mapping and Rules
Magento 2.X	This document
PrestaShop	This document
Shopify	This document

Other Information

• It is possible not to synchronize the customer account. Even if a table is not synchronized, it will still be deployed if the e-commerce solution is not using an existing profile table.
• Some attributes may be unavailable or unsynchronized depending on the e-commerce CMS. These fields are still created in the table but remain empty. This applies only when the profile table is created by the e-commerce solution.
• Subscription updates from Actito to the e-commerce CMS:
  • Can be activated or deactivated*
  • Available for all new connectors deployed from 16 February 2022. Existing connectors created before this date do not have this synchronization activated.

Orders Table

Main Information

Parameter	Value
Technical name of the linked table	Orders
Entity	Refer to the entity set in the setup kit
Import mode	Create and Update

Rules and Mapping Between E-commerce CMS and the Data Model

• Every two minutes, Actito polls for new or updated customers since the last synchronization.
• Orders that do not link to a known profile will be rejected.
• Orders missing mandatory fields will be rejected during the import process.
• Invalid values in any field will result in rejection of the order.
• When an order is updated, only new rows are added; deleted rows are not supported.

CMS	Mapping and Rules
Magento 2.X	This document
PrestaShop	This document
Shopify	This document

note

All fields are available in the data model, even if they cannot be retrieved from the e-commerce CMS.

Other Information

• It is possible not to synchronize orders (including order lines). Even if the table is not synchronized, it will still be deployed.

Order Lines Table

Main Information

Parameter	Value
Technical name of the linked table	orderLines
Entity	Refer to the entity set in the setup kit
Import mode	Create and Update

Rules and Mapping Between E-commerce CMS and the Data Model

• Every two minutes, Actito polls for new or updated customers since the last synchronization.
• Order lines that do not link to a known profile will be rejected.
• Orders missing mandatory fields will be rejected during the import process.
• Invalid values in any field will result in rejection of the order line.
• When an order is updated, only new rows are added; deleted rows are not supported.

CMS	Mapping and Rules
Magento 2.X	This document
PrestaShop	This document
Shopify	This document

Other Information

• It is possible not to synchronize order lines. Even if the table is not synchronized, it will still be deployed.

Abandoned Carts Table

Main Information

Parameter	Value
Technical name of the linked table	abandonedCarts
Entity	Refer to the entity set in the setup kit
Import mode	Create Only

Rules and Mapping Between E-commerce CMS and the Data Model

• Every 5 minutes, Actito polls for new abandoned carts since the last synchronization.
• A cart is considered abandoned if there is no update after 180 minutes by default. This value can be modified; refer to the SET_KIT document for the correct setting.
• Abandoned carts that do not link to a known profile will be rejected.
• Abandoned carts missing mandatory fields will be rejected during the import process.
• Invalid values in any field will result in rejection of the abandoned cart.
• Only one abandoned cart per day is managed by the connector.

CMS	Mapping and Rules
Magento 2.X	This document
PrestaShop	This document
Shopify	This document

Other Information

• It is possible not to synchronize abandoned carts. Even if the table is not synchronized, it will still be deployed.

Abandoned Cart Lines Table

Main Information

Parameter	Value
Technical name of the linked table	abandonedCartLines
Entity	Refer to the entity set in the setup kit
Import mode	Create and Update

Rules and Mapping Between E-commerce CMS and the Data Model

• Every 5 minutes, Actito polls for new abandoned cart lines since the last synchronization.
• A cart line is considered abandoned if there is no update after 180 minutes by default. This value can be modified; refer to the SET_KIT document for the correct setting.
• Abandoned cart lines that do not link to a known profile will be rejected.
• Abandoned cart lines that do not link to a known abandoned cart will be rejected.
• Abandoned cart lines missing mandatory fields will be rejected during the import process.
• Invalid values in any field will result in rejection of the abandoned cart line.
• Only one abandoned cart per day is managed by the connector.

CMS	Mapping and Rules
Magento 2.X	This document
PrestaShop	This document
Shopify	This document

Other Information

• It is possible not to synchronize abandoned cart lines. Even if the table is not synchronized, it will still be deployed.

Without the connector designed by Actito

Synchronization mode

If you have developed your own e-commerce CMS, modified the standard behavior of Shopify, Magento, or PrestaShop, or if you use a non-compatible feature of one of these platforms, you can still benefit from the Actito e-commerce data model without using the connector.
In this case, you must manage the data exchange yourself through the Actito Integration Framework.

To synchronize data from the e-commerce model, you can choose between three approaches:

• File exchange via FTPS/SFTP – once per day
• One-by-one API calls – real time (recommended by Actito)
• Bulk mode – up to twelve times per day per table

Regardless of the chosen method, injected data must respect the following order to ensure data integrity:

1. Customers
2. Abandoned carts
3. Abandoned cart lines
4. Orders
5. Order lines

Useful resources to integrate with Actito APIs:

• Authentication
• API domains
• Manage API users
• Limitations

Warning

Actito has three production environments. Always use the correct API domain when building your final URLs.

Synchronization through one-by-one calls

Profile table

Main information	Value
Technical name of the linked table	Refer to the profile table name chosen in the setup kit
Entity	Refer to the entity chosen in the setup kit
Import mode	Create and Update

Before creating or updating profiles, you must retrieve the ID of the target profile table using this API:

GET <API Domain>/v5/entities/{entity}/profile-tables
Where:

• {entity} = the entity in which the profile table is deployed

API reference:
https://developers.actito.com/api-reference/data-structure/profile-table-structure/#tag/Profile-Tables/operation/get-profiletables-list

To create or update a profile, use the following API:

PUT <API Domain>/profiles/v5/entities/{entity}/profile-tables/{tableId}
Where:

• {entity} = the entity of your database
• {tableId} = the ID of the profile table where the profile must be created or updated

API reference:
https://developers.actito.com/api-reference/data-exchange/profiles#tag/Profiles/operation/create-or-update-one-profile

Example JSON payload (for a profile table deployed via the e-commerce solution)

{
  "attributes": [
    {"name": "lastName", "value": "Smith"},
    {"name": "firstName", "value": "John"},
    {"name": "birthDate", "value": "26/05/1977"},
    {"name": "sex", "value": "M"},
    {"name": "motherLanguage", "value": "FR"},
    {"name": "emailAddress", "value": "john.smith@actito.com"},
    {"name": "addressLocality", "value": "Bruxelles"},
    {"name": "addressCountry", "value": "BE"},
    {"name": "gsmNumber", "value": "+32477777777"},
    {"name": "accountId", "value": 34567}
  ],
  "dataCollectionInformation": {
    "date": "2019-05-18",
    "source": "E-commerce CMS Shopify",
    "way": "API"
  },
  "subscriptions": [
    {
      "name": "Newsletter",
      "subscribe": "true"
    }
  ]
}

info

It is possible to get the profile table structure targeted through this API.

Important information:

• Profiles missing mandatory fields will be rejected during import.
• Invalid attribute values will also result in rejection.

Recommended synchronization strategy

• Check every minute for new or updated customers.
• When an order is synchronized, verify whether the associated profile also requires updating.

Managing Newsletter Subscription

By default, Actito behaves as a slave for the subscription status: Actito overwrites the subscription value with the value you provide. If no value is provided, the profile is considered not subscribed.

To change this behavior, you must implement a business rule in your synchronization logic.

Possible approaches:

• Option #1: Store the profileId received after each creation. Then send subscription data only for new profiles.
• Option #2: Call this API
  • If the profile exists → do not overwrite subscription
  • If it does not exist → provide the subscription in the create call
• Option #3: Inject your customers in two times. First import, it’s a update only import where the subscription data is not provided then second import, it’s a create only import where the subscription data is provided.

Rules and Mapping Between the E-commerce CMS and the Data Model

• If the e-commerce solution is linked to an existing profile table, refer to your setup documentation. It specifies:
  • which data must be injected,
  • the key fields,
  • the expected formats,
  • any attributes with restricted values,
  • mandatory fields to comply with.
    You can also retrieve the exact table definition through the API mentioned earlier.
• If you use the default Customers profile table deployed by the e-commerce module, refer to the data model definition described in the Data Model section. This section details:
  • the attributes to inject,
  • the required formats and key fields,
  • any value restrictions or mandatory constraints.
    You may also retrieve the table definition using the same API once the data model has been deployed.

If you need assistance with attribute mapping, you can rely on the mapping and rules provided with our connector.

CMS	Mapping and Rules
Magento 2.X	This document
PrestaShop	This document
Shopify	This document

Abandoned Cart and Abandoned Cart Lines

Main information	Value
Id of the tables linked	Get IDs via API
Entity	Refer to the entity chosen in the setup kit
Import mode	Create and Update

First, retrieve the IDs of the Abandoned Cart and Abandoned Cart Lines tables using this API:

GET <Domain API>/v5/entities/{entity}/custom-tables
Where:

• {entity} = entity where the custom tables are deployed (usually the same as the profile table)

To create or update an abandoned cart, push:

• General cart information to the Abandoned Cart table
• Product details to the Abandoned Cart Lines table

POST <Domain API>/v4/entity/{e}/customTable/{t}/record
Where:

• {e} = entity where the custom table is deployed
• {t} = ID of the custom table (Abandoned Cart or Abandoned Cart Lines)

Example JSON payload to inject a row into the Abandoned Cart table

{
  "properties": [
    { "name": "abandonedCartId", "value": "1223" },
    { "name": "abandonedSinceMoment", "value": "2022-09-22" },
    { "name": "total", "value": "200.65" },
    { "name": "emailAddress", "value": "john.smith@actito.com" }
  ]
}

Example JSON payload to inject a row into the Abandoned Cart Lines table

{
  "properties": [
    { "name": "abandonedCartId", "value": "1223" },
    { "name": "abandonedCartDetailId", "value": "1223-1" },
    { "name": "sku", "value": "123" },
    { "name": "emailAddress", "value": "john.smith@actito.com" }
  ]
}

tip

Actito also provides an API to delete rows in a custom table when an abandoned cart is updated.

Important

• An abandoned cart that is not linked to a known profile will be rejected.
• An abandoned cart line that is not linked to a known profile will be rejected.
• An abandoned cart line that is not linked to an existing abandoned cart will be rejected.
• An abandoned cart with missing mandatory fields will be rejected during the import process.
• An abandoned cart line with missing mandatory fields will be rejected during the import process.
• Any invalid value will result in the rejection of the row during the import process.

Recommendations for synchronization

• Check for new abandoned carts every 5 minutes since the last poll.
• By default, a cart is considered abandoned if there is no update after 180 minutes.

Rules and mapping between the e-commerce CMS and the data model

If you need assistance with attribute mapping, you can rely on the mapping and rules provided with our connector.

CMS	Mapping and Rules
Magento 2.X	This document
PrestaShop	This document
Shopify	This document

Orders and Order Lines

Main information	Value
Id of the tables linked	Get IDs via API
Entity	Refer to the entity chosen in the setup kit
Import mode	Create and Update

Start by retrieving the IDs of the Orders and Order Lines tables.
To do so, use the following API:

GET <Domain API>/v5/entities/{entity}/custom-table
Where:

• {entity} = the entity where the custom table is deployed

To create or update an order and its details, you must provide:

• general information about the purchase to the Orders table
• product details to the Order Lines table

Use the same API for both tables but adjust the table ID and attributes according to each structure:

POST <Domain API>/v4/entity/{entity}/customTable/{table}/record
Where:

• {entity} = entity where the custom table is deployed
• {table} = ID of the target custom table (Orders or Order Lines)

Example JSON payload to insert a row into the Orders table

{
  "properties": [
    { "name": "orderId", "value": "1226373" },
    { "name": "date", "value": "2022-09-23" },
    { "name": "total", "value": "50.00" },
    { "name": "emailAddress", "value": "john.smith@actito.com" }
  ]
}

Example JSON payload to inject a row into the Order Lines table

{
  "properties": [
    { "name": "orderId", "value": "1226373" },
    { "name": "orderDetailId", "value": "1226373-1" },
    { "name": "sku", "value": "123" },
    { "name": "emailAddress", "value": "john.smith@actito.com" }
  ]
}

tip

Actito also provides an API to delete a row in a custom table, for example when a customer returns a product.

Important

• An order not linked to a known profile will be rejected.
• An order line not linked to a known profile will be rejected.
• An order line not linked to an existing order will be rejected.
• Any order missing mandatory fields will be rejected during the import process.
• Any order line missing mandatory fields will be rejected during the import process.
• Any invalid value will cause the row to be rejected during the import process.

Recommendations for synchronization

• Check for new or updated orders every 2 minutes since the last poll.

CMS	Mapping and Rules
Magento 2.X	This document
PrestaShop	This document
Shopify	This document

To exchange data in bulk mode, you must run an ETL by uploading synchronization files via multipart/form-data.
ETL executions can be fully managed with the available API collection.

Using the ETL mechanism, each table can be synchronized up to twelve times per day.

For additional details and steps, refer to:

• Principles
• Format

1. Configure file synchronization
   a. First, generate the files using the following specifications:

   File name	customers.csv orders.csv orderlines.csv abandonedcarts.csv abandonedcartlines.csv
   Extension	.csv
   Compression	Yes
   Compressed filename	customers.csv.zip orders.csv.zip orderlines.csv.zip abandonedcarts.csv.zip abandonedcartlines.csv.zip
   Header	Yes
   Column separator	Semicolon
   Enclosing	"
   Escaping	"
   Encoding	UTF-8 without BOM
   Column names and values	Refer to the table definitions in the database section

   tip

   If you cannot produce the expected format, you may use a data transformation during synchronization.
   See the dataTransformations property in the ETL execution API.

   b. Retrieve the destination table IDs

   These IDs are required to configure the ETL.

   Profile table
   GET <Domain API>/v5/entities/{entity}/profile-tables
   Where:

   • {entity} = entity where the profile table is deployed

   Orders, OrderLines, AbandonedCart, AbandonedCartLines tables
   GET <Domain API>/v5/entities/{entity}/custom-tables
   Where:

   • {entity} = entity where each custom table is deployed

   c. Deploy an ETL execution

   Each ETL execution handles one file only, so you must repeat the procedure for each data file.

   POST <Domain API>/v5/entities/{entity}/etl-executions
   Where:

   • {entity} = entity where the profile table is deployed

   The request must include two multipart/form-data components:

   • inputFile: the file to be synchronized
   • oneshotEtl: the ETL execution definition

   ETL definitions to download:

   • Customers
   • Orders
   • OrderLines
   • AbandonedCarts
   • AbandonedCartLines

   Each ETL JSON definition must include:

   • an email address to receive the execution report,
   • the destination table ID,
   • attribute mapping aligned with the defined profile key attribute.
   tip

   After each execution, you can retrieve the result file or the error file using the following APIs:

   • Get output files

   • Get integration results

   You may also upload both the result file and the error file to a remote FTPS/SFTP location.
   To enable this, you must configure a remote file server.
   For more details about setting it up, refer to the next section.

Synchronization by file exchange through an FTPS/SFTP

To exchange data using files, you must use our ETL. The ETL process is fully manageable through our API collection.

By using our ETL, the data model can be synchronized only once per day.

To complement this document and the steps described above, please refer to our documentation:

• Principle
• Format

1. Setup a remote file server connection

Using the File Transfer API, you can configure a secure remote file server for file exchanges. The remote server may be SFTP or FTPS.

If you choose SFTP, note that Actito also supports authentication via private key. You can generate a public key using a dedicated API.

To associate a remote file server with your Actito license, use the following API:
File Transfer Configuration API

POST <Domain API>/v5/entities/{entity}/filetransfer-configs Where:

• {entity} = entity where the profile table is deployed

{
  "name": "yourBrand_ftp",
  "displayName": "Your brand FTP",
  "connection": {
    "serverType": "FTP",
    "parameters": {
      "host": "ftp.yourDomain.com",
      "port": 21,
      "passiveMode": true,
      "encryption": "EXPLICIT_OVER_TLS"
    },
    "authentication": {
      "type": "LOGINPASSWORD",
      "login": "yourLogin",
      "password": "dummypassword"
    }
  }
}

Then, you must specify the folder where files will be downloaded by using the following API:

POST <Domain API>/entities/{entity}/filetransfer-configs/{configId}/locations
Where:

• {entity} = the entity where the profile table is deployed
• {configId} = the ID of the previously configured file transfer server

{ 
  "name": "input_folder", 
  "displayName": "Input folder", 
  "path": "/IN" 
}

You must create two folders:

• One folder where the file to synchronize will be downloaded
• One folder where Actito will place the result file and the rejected rows after each synchronization

2. Whitelist the IP address of

To whitelist your IP, you must send an email to our support team including:

• Your license name
• Your environment with the API domain (you can identify it on this page)
• Your IP address

The remote file server will only become operational once Actito has whitelisted your IP.

caution

Make sure that your file server access has both read and write permissions.

3. Set a files synchronization
   a. First generate files with the following settings

Please note with this documentation, we provide a common setting. Some items are options to be more align with the export setting of your e-commerce solution. Refer to our API documentation to view all capabilities of our ETL.

File name	customers_$YYYYMMDD.csv orderss_$YYYYMMDD.csv orderliness_$YYYYMMDD.csv abandonedcartss_$YYYYMMDD.csv abandonedcartliness_$YYYYMMDD.csv
Extension	.csv
Compression	Yes
Compressed filename	customerss_$YYYYMMDD.csv.zip orderss_$YYYYMMDD.csv.zip orderliness_$YYYYMMDD.csv.zip abandonedcartss_$YYYYMMDD.csv.zip abandonedcartliness_$YYYYMMDD.csv.zip
Header	Yes
Column separator	Semicolon
Enclosing	"
Escaping	"
Encoding	UTF-8 without BOM
Column names and values	Refer to the table definitions in the profile table section

tip

If you cannot provide the expected format, you can apply a data transformation during synchronization.
More details about the "dataTransformations" property are available in the API definition.

b. Retrieve the destination table IDs

These IDs are required to configure the ETL.

Profile table

GET <Domain API>/v5/entities/{entity}/profile-tables
Where:

• {entity} = entity where the profile table is deployed

Orders, OrderLines, AbandonedCart, AbandonedCartLines tables

GET <Domain API>/v5/entities/{entity}/custom-tables
Where:

• {entity} = entity where each custom table is deployed

c. Deploy an ETL execution

Each ETL execution handles one file only, so you must repeat the procedure for each data file.

POST <Domain API>/v5/entities/{entity}/etl-executions
Where:

• {entity} = entity where the profile table is deployed

Download the ETL definition. Ensure the ETL definition is fully completed with:

• Email address to receive the execution report
• Table destination ID
• Attribute mapping according to the profile key attribute; the mapping must be adjusted as needed

Synchronization of subscription update from Actito to e-commerce CMS

Synchronizing the newsletter subscription status from Actito to your e-commerce CMS is highly recommended. It helps ensure the correct value is always applied and gives your customers confidence by showing an accurate subscription status in their customer portal.

Subscription updates from Actito can be obtained in two ways:

• Using a webhook for real-time updates
• Using an export file for daily updates

Through a webhook

To set a webhook to Actito, you must use our dedicated API.

You will also find general information about webhooks provided by Actito on our technical documentation.

POST <Domain API>/v4/entity/{e}/webhookSubscription Where:

• {e} = the entity name where the profile table is deployed

Example of bulk notification

{ 
"on": "PROFILE_TABLE", 
"onElementId": "5", 
"eventType": "UPDATED_SUBSCRIPTION", 
"onFields":["newsletter"], //Name of the subscription to listen 
"targetUrl": "YOUR_URL_OF_YOUR SERVER_TO_CAPTURE_THE_WEBHOOK", 
"headers": { 
  "X-Authorization": "XXXXXXXXX" //Not mandatory but recommended to secure the connection 
  }, 
"webhookPushType": "BULK", 
"maxBlockSize": 1000, 
"isActive": true 
}

When you subscribe to a webhook, Actito responds with the webhook ID. This ID is required if you want to stop or update the webhook subscription later.

{
  "id": 13
}

Technical information about Actito webhooks:

• A webhook can be triggered for each profile (webhook Push type is “ONE_BY_ONE”) or for multiple profiles at the same time (“BULK”). For bulk mode, you must define the number of events sent in a single POST call (between 10 and 1000).
• For bulk webhooks, the webhook is triggered either when the defined number of events is reached or after 5 seconds if the threshold is not met.
• An API is available to retrieve errors if necessary (e.g., if your URL fails): Webhook Errors API
• There is only one concurrent HTTPS call for all webhooks.
• By default, each subscription update triggers the webhook to notify the target URL, even if the e-commerce CMS is the origin of the update. You can filter events when creating the webhook subscription to receive only events generated by Actito (email sending, preference center, Actito portal, etc.).

Example of the body pushed by the webhook

{
  "id": 71,
  "tableType": "PROFILE_TABLE",
  "tableId": "20",
  "fields": [],
  "eventType": "DATA",
  "operation": "UPDATED_SUBSCRIPTION",
  "data": [
    {
      "newsletter": false,
      "dataCollectionMoment": "2022-10-04T15:33:57+02:00",
      "profileId": 1187917,
      "dataCollectionWay": {"OPERATION":"UPDATE","ADDITIONAL_INFO":null,"USER":"hamed","REMOTE_ADDRESS":"88.168.187.168","USER_AGENT":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/106.0.0.0 Safari/537.36"},
      "dataCollectionSource": "ActitoWeb3 GUI",
      "businessKey": "john.smith@actito.com"
    },
    {
      "newsletter": true,
      "dataCollectionMoment": "2022-10-04T15:33:57+02:00",
      "profileId": 1283047,
      "dataCollectionWay": {"OPERATION":"UPDATE","ADDITIONAL_INFO":null,"USER":"hamed","REMOTE_ADDRESS":"88.168.187.168","USER_AGENT":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/106.0.0.0 Safari/537.36"},
      "dataCollectionSource": "ActitoWeb3 GUI",
      "businessKey": "mike@actito.com"
    }
  ]
}

Through an export file

To receive an export file with subscription updates, two steps are required:

• First, set up a remote file server where the export file can be uploaded.
• Then, configure the export file within the Actito portal.

General information about export files can be found in our technical documentation: Actito Export Files

1. Set up a remote file server connection

Using the File Transfer API, you can configure a secure remote file server to exchange files. Supported servers include SFTP and FTPS.

If you choose SFTP, Actito also allows authentication via private key. You can generate the corresponding public key using a dedicated API. More information here: File Transfer API – Actito

To associate a remote file server with your Actito license, use the following API:

POST <Domain API>/v5/entities/{entity}/filetransfer-configs Where

• • {entity} = the entity name where the profile table is deployed

{
  "name": "yourBrand_ftp",
  "displayName": "Your brand FTP",
  "connection": {
    "serverType": "FTP",
    "parameters": {
      "host": "ftp.yourDomain.com",
      "port": 21,
      "passiveMode": true,
      "encryption": "EXPLICIT_OVER_TLS"
    },
    "authentication": {
      "type": "LOGINPASSWORD",
      "login": "yourLogin",
      "password": "dummypassword"
    }
  }
}

Then, you must specify the folder where files will be downloaded by using the following API:

POST <Domain API>/v5/entities/{entity}/filetransfer-configs/{configId}/locations Where:

• {entity} = the entity where the profile table is deployed
• {configId} = the ID of the previously configured file transfer server

{
  "name": "output_folder",
  "displayName": "Output",
  "path": "/OUT"
}

You must create a folder where Actito will place the export files.

2. Whitelist your IP of your file server

To whitelist your IP, send an email to support@actito.com with the following information:

• Your license name
• Your environment and API domain (identify your environment here: Authentication documentation)
• Your IP address

The remote file server will be operational only once Actito has whitelisted your IP.

caution

Ensure your file server access has both read and write permissions.

3. Set an export file from the Actito portal

An easy way to define the export file is directly through the Actito portal. For instructions on creating a subscription update export, please refer to the portal documentation.

By default, each update of the subscription is exported, even if the e-commerce CMS is the origin of the update. If needed, you can filter events to export only those generated first by Actito (such as email sending, preference center, Actito portal…).

More information about the export file:

• Format of export file
• Information exported

First data upload

Whether the synchronization is done with the connector designed by Actito or not, the import history of data remains your responsibility.

To complete this task, you must export files from your e-commerce CMS and upload them manually into Actito by following the instructions below.

We recommend injecting your data while your live synchronization is already running. This approach makes it easier to verify the consistency between your e-commerce platform and Actito and ensures that no data is missed.

Import customers in the profile table

File name	free to choose
Extension	.csv
Column separator	Semicolon
Header	Yes
Compression	Yes
Encoding	UTF-8 without BOM
Key to deduplicate	Attribute defined in the "Unicity of a profile" section If the e-commerce solution is deployed on an existing profile table, you must use the key of the profile table
Attributes to import	Refer to the profile table definition

To know how to import a file in to the profile table, please refer to the documentation.

Import orders in the Orders custom table

File name	free to choose
Extension	.csv
Column separator	Semicolon
Header	Yes
Compression	.zip mandatory
Encoding	UTF-8 without BOM
Key to deduplicate	orderId
Attributes to import	Refer to the Orders table definition and the mapping

To know how to import a file in to the orders table, please refer to the documentation.

Import order lines in the Order Lines custom table

File name	free to choose
Extension	.csv
Column separator	Semicolon
Header	Yes
Compression	.zip mandatory
Encoding	UTF-8 without BOM
Key to deduplicate	orderDetailId
Attributes to import	Refer to the Order Lines table definition and the mapping

To know how to import a file in to the order lines table, please refer to the documentation.