1. Introduction
1.1. Overall functioning
The Splio Sync extension for Magento 2 allows the synchronization of the customers, the newsletters subscribers, the abandoned carts and the orders between Magento 2 and Splio.
It synchronizes the following data of these antities :
- customers and newsletter subscribers: ID, email, names, gender, date of birth, phone number, VAT number, creation, last update, last connection and last synchronization date
- billing address of customers: address lines, city, zip code, country, company
- abandoned carts and orders: ID, store, status, totals in base and locale currency, creation and last update date
- abandoned carts or orders items: SKU, price, ordered quantity, totals in base and locale currency
- products linked to the items: names and descriptions in every locale used in your Magento instance, prices in every currency used in your Magento instance, brand, image, URL, stock level, categories, creation, last update and last synchronization date
The synchronization is done in almost real-time (less than a minute of delay), by adding non invasive synchronization tasks in a dedicated queue, and processed by a cron task.
The Splio Sync extension for Magento 2 also allows the synchronization of customers and newsletter subscribers as requested by GDPR.
1.2. Limitations
1.2.1. Magento 2 / Adobe Commerce version compatibility
The extension is only compatible with Magento 2.4.2 version and above. It is compatible with every edition of Magento 2, Adobe Commerce included.
1.2.2. Splio contacts optout
To date, the synchronization of optouts from Splio to Magento is not included in the extension. If you want to sync your contacts optout in your Magento 2 / Adobe Commerce website, you may need to discuss it further with your Splio contact.
2. Installation guide
2.1. Extension installation
Before the extension install, it must be ensured that the Magento environment is properly configured.
Please feel free to check among other topics:
- the cron tasks configuration, required for the proper functioning of the extension.
- the user rights configuration, required for the proper installation of the extension.
2.2. Through composer
You can follow the procedure written here: https://experienceleague.adobe.com/docs/commerce-operations/installation-guide/tutorials/extensions.html?lang=en
- Place an order for the extension through the Magento marketplace.
- Make sure that the repo.magento.com repository exists in your composer.json file:
"repositories": [ { "type": "composer", "url": "https://repo.magento.com/" } ]
- Update your Magento composer.json with the following lines in require and repositories sections:
"require": { "home-made-io/splio-sync-m2": "^2.0.0" }
- Enter your authentication keys. Your public key is your username; your private key is your password.
- Wait for Composer to finish updating your project dependencies and make sure that there aren’t any errors:
Updating dependencies (including require-dev) Package operations: 1 install, 0 updates, 0 removals - Installing home-made-io/splio-sync-m2 (2.1.0): Downloading (100%) Writing lock file Generating autoload files
- To verify that the extension installed properly, run the following command:
$ bin/magento module:status HMio_SplioSync
- Enable the extension and clear static view files:
$ bin/magento module:enable HMio_SplioSync --clear-static-content
You should see the following output:
The following modules have been enabled: - HMio_SplioSync To make sure that the enabled modules are properly registered, run 'setup:upgrade'. Cache cleared successfully. Generated classes cleared successfully. Please run the 'setup:di:compile' command to generate classes. Generated static view files cleared successfully.
- Register the extension:
$ bin/magento module:status HMio_SplioSync
- Recompile your project: In Production mode, you may receive a message to “Please rerun Magento compile command”. The application does not prompt you to run the compile command in Developer mode.
$ bin/magento setup:di:compile
- Verify that the extension is enabled:
$ bin/magento module:status HMio_SplioSync
You should see output verifying that the extension is no longer disabled:
Module is enabled
- Clean the cache:
$ bin/magento cache:clean
- Disable maintenance mode:
$ bin/magento maintenance:disable
2.2.1. Through the Magento admin panel
- Place an order for the extension through the Magento marketplace.
- Go in Magento admin, menu
System
>Tools
>Web Setup Wizard
. - Click the Extension Manager icon.
- Within the Magento Marketplace Account section, click on New Purchases, and follow the instructions to install the extension.
ℹ️ The extension installation must be relatively quick (under 5 minutes). If this delay is exceeded, please check the log files.
2.3. Extension uninstallation
Open a terminal and run the following commands in your Magento directory:
$ composer remove home-made-io/splio-sync-m2
$ composer remove simonlx/newsletter-api
$ bin/magento setup:upgrade
$ bin/magento setup:di:compile
$ bin/magento setup:static-content:deploy
$ bin/magento cache:clean
3. User guide
3.1. Extension configuration
3.1.1. API configuration
First, you need to set the API key of your Splio universe.
To find it or create one, please go to your Splio backoffice, go to the menu Users
below your username at the top-right of your screen, and go to the API users
tab. More info here: Splio admin interface.
💡 For security reason, it’s recommanded to create a new API user for the synchronization with Magento 2 / Adobe Commerce, even if you have some users already defined.
Fill a meaningful login (for example « splio_sync_m2 »), and copy the new key in the extension configuration in Magento 2 / Adobe Commerce, in the menu Stores
> Configuration
> Splio Sync
> API
> API key
.
After setting the API key, please save the configuration, and test it with the button visible in same configuration section.
For more information on the API keys generation on Splio, please look at the dedicated documentation.
3.1.2. Splio multiple universes management
It’s possible to configure the extension to synchronize the abandoned carts of different websites on different universes in Splio.
To do so, go in Magento admin, menu Stores
> Configuration
, then in the tab Splio Sync
> API
. Then, change the scope to choose the website that must be synchronized in another Splio universe.
💡 It’s a pretty advanced configuration, which has impacts on the synchronization process. Please feel free to talk about it at your contact within Splio in the first place.
3.1.3. Custom fields installation
When you are done defining the Splio universes API keys in the extension configuration, you can install the custom fields defined by the extension. These custom fields will store in Splio various informations about your contacts, their orders, carts and credit memos, and your catalog.
⚠️ In case of multi-universes configuration, the custom fields will be created automatically on each of the universe configured. If an universe is added in the configuration during the lifetime of the website, it’s necessary to rerun the custom fields installation the same way.
ℹ️ The installation through the button does not delete the custom fields already existing, nor does it create duplicates. You can click again on the button without fear of impacts in the data existing in Splio.
The complete list of these custom fields can be found in the « Reference manual » part of this documentation.
The 2.0.0 version of the extension comes now with the integration and the support of more custom fields for your specific needs. It will require nonetheless the installation of a custom extension, of which an example will be provided by us when buying the extension.
ℹ️ Feel free to contact us to obtain information about the development of the modification system of customs fields
3.1.4. Contacts lists
You can choose from the configuration panel in which Splio lists your contacts will be synchronized:
- Email optins: You can choose the list gathering all you customers who are also newsletter subscribers in Magento
- Text message optins: You can choose the list gathering all you customers who accepted text message communication
- All contacts: You can choose to synchronize all your Magento 2 customers in a specific lists in Splio
⚠️ Warning: if you have several Splio universes configured for a you Magento 2 websites, please be sure to configure the lists accordingly.
3.1.5. Choice of product identifier attribute
The extension allows users to choose which will be the attribute identifying the products in Splio, among the list of attributes existing in the Magento 2 website.
The favored choices are the SKU and the Magento ID. Nonetheless, any other attribute can be used. Here is the important points to take into account for choosing the identifier attribute:
- it must be filled for all products or customers
- it must be unique for each product or customer
- it must be defined globally, so no overridden at website / store scope
- it must be saved as a text or as an option of a list
💡 Feel free to consult your contact within Splio to define what is the best choice for you.
Once the synchronization is launched, it’s strongly discouraged to change the identifier attribute. The configuration fields are disabled once the synchronization is launched.
3.1.6. Stores configuration
Before configuring the extension to synchronize the abandoned carts, you must create the store which will receive the carts within Splio.
Go in Splio, in the menu Data
> Sales data
, then in the tab Stores
, and create one or more stores matching the stores in the Magento website.
ℹ️ The Splio Sync extension allows synchronizing the data in a Splio store depending on the website or the store view on which it has been made. So you can create as many stores in Splio as there are store views in Magento, or only one store containing all abandoned carts existing in your Magento instance.
Once the stores are created in Splio, you can fill out their external ID in the configuration field of the Splio Sync extension.
Go in Magento admin, menu Stores
> Configuration
, then in the tab Splio Sync
> Orders
.
In the configuration field called Splio store external ID, fill out the external ID of the Splio store newly created.
💡 By modifying the scope of the configuration, you can change the external ID of the Splio by website or store view.
3.1.7. Order states synchronization
Orders in states after processing
are automaticaly synced:
processing
: orders which are paidcomplete
: orders which are shippedclosed
: orders which are completly refunded
You can choose to sync also orders in states before receiving their payment: new
, pending payment
, payment review
and canceled
. And you can choose to sync orders in these states as an abandoned cart, or as a paid order.
ℹ️ If you choose to sync orders before receiving their payment, a cancelation will be handle as a deletion of the order in Splio, to keep the totals amounts of your contacts right.
3.2. Launching of the synchronization
After the configuration step, you can launch the synchronization.
To do so, go into Magento admin, menu Stores
> Configuration
, then in the tab Splio Sync
> Job Queue
, and change the value of the configuration field called Enable sync between Splio and Magento.
After that, for each entity synchronizable, go in the matching tab, and change the value of the configuration field called Enable export.
3.2.1. Existing entities synchronization
Go into Magento admin, menu Stores
> Configuration
, then in the tab Splio Sync
> Job queue
.
In the fieldset « Initialization » you’ll find 3 buttons to synchronize all existing data in Splio.
⚠️ Warning: This operation can slow down the speed of the others entities during several hours, please use these buttons with caution.
3.2.2. Closed order synchronization
You can choose to synchronize or not passed closed orders in this initialization step.
In Magento 2 / Adobe Commerce, closed orders are orders which have been completly refunded.
It can be useful if you want to have a more accurate vision of your orders on Splio. But it slows down your initialization, as the extension needs to create a ticket for the order and a ticket for each credit memo linked to it.
Also, if you use Splio Loyalty program, you may want to know that the loyalty program of Splio doesn’t use orders older than its beginning date to calculate the points assigned to each customer. So it may be useless to synchronize all your history of closed orders.
ℹ️ Obviously, after this initilization step, when a new order is refunded and closed in Magento 2 / Adobe Commerce, the order and the credit memo will be synchronized in Splio. The previous paragraph only applies to the initialization step.
3.3. Synchronization tracking
Into the menu System
> Splio
, several pages display information on the smooth running of the synchronization of the different entities.
3.3.1. Jobs tracking
Into the menu System
> Splio
> To Splio Job Queue
, a grid displays the list of the jobs to be done to Splio, with their status, creation date and a potential error message.
The jobs can be in one of the following statuses:
pending
running
in error
skipped
: the entity’s data indicates that it must not be synchronizedfinished
The jobs finished or skipped are automatically deleted after their processing.
In case of error, the synchronization process try to rerun the job 4 times, before giving up. The jobs definitively in error stay visible in the grid, with the error message matching.
3.3.2. Contacts matching (customers and subscribers)
Into the menu System
> Splio
> Synced contacts
, a grid displays the list of the contacts synchronized with Splio, a contact being either a customer or a NL subscriber, or both obviously. It includes the customers / subscribers deleted in Magento 2.
⚠️ In case of an update of the email address by the customer in Magento 2 / Adobe Commerce, a specific error occured, as Splio does not allow this update of the identifier field for a specific contact. To handle it manually, you can choose to remove the matching of this specific contact, and relaunch the synchronization job, for syncinc the customer in a new contact in Splio.
3.3.3. Abandoned carts matching
Into the menu System
> Splio
> Synced abandoned carts
, a grid displays the list of the abandoned carts already synchronized with Splio, including those which have been deleted since (because they were converted as orders, or deleted by the customer).
3.3.4. Orders matching
Into the menu System
> Splio
> Synced orders
, a grid displays the list of the orders already synchronized with Splio.
3.3.5. Credit memos matching
Into the menu System
> Splio
> Synced credit memos
, a grid displays the list of the credit memos already synchronized with Splio.
3.3.6. Products matching
Into the menu System
> Splio
> Synced products
, a grid displays the list of the products synchronized with Splio.
In Magento, products can be affected to several websites, thus synchronized with several universes in Splio. The column Scope allows to determine with which it has been synchronized, and with which identifier.
3.4. Logs tracking
The extension offers two pages for tracking the smooth running of the synchronization into the menu System
> Splio
, Logs
and API calls logs
.
The first page displays information of the running of the synchronization of the different entities. The second one displays the calls made to the Splio API during the synchronization.
ℹ️ Authentication calls to the Splio API are never logged, for security purposes.
Those are primarily technical data, but which are very useful during errors resolution.
Nonetheless, you can choose to disable a part of logs (the least critical) in order to avoid populating the matching table in your database needlessly.
By default, logs are deleted after 7 days, and duplicated in a dedicated log file. The configuration allows modification of these behaviors nonetheless.
ℹ️ In case of error, feel free to send us the information contained in the matching tables, to ease the resolution of the issue.
3.5. Synchronization specificities
3.5.1. Delay before abandoned carts synchronization
The extension allows defining a delay before considering a cart as abandoned.
By default, this delay is valued at 36 hours.
3.5.2. Base and locale currency
The module send in Splio the totals in base currency in Splio. Meaning that the locale currency totals are send as custom fields, for the cart and its items.
As for now, custom fields of carts or orders items are not displayed in Splio admin UX, but rest assured that the totals are also sent in locale currency for carts items.
3.5.3. Orders matching carts deletion
When an order is synchronized with Splio, if the matching cart in M2 was already synchronized with Splio, it will be deleted first, as the order ID is different of the previous cart ID.
3.5.4. Shipping fees exclusion
A configuration field allows you to remove shipping fees from grand total, allowing you to not assign loyalty points on shipping fees.
3.5.5. Products synchronization
The extension synchronizes all types of products, but only synchronizes children items for abandoned carts and orders.
3.5.6. Subscribers unsubscription
In compliance with GDPR, when a subscriber unsubscribe from your newsletter, if the contact list are correctly configured, the extension synchronizes its removal from the email optin contacts in Splio.
ℹ️ If the then-subscriber was only in the list configured in Magento 2 as the list gathering all email optin contacts, it will be removed from this list nonetheless, leaving it in no list in Splio.
ℹ️ If the then-subscriber was not linked to a customer, its unsubscription will be synced as a deletion in Splio.
3.5.7. Customers deletion
In compliance with GDPR, when a customer deletes its account, the extension synchronizes its deletion from the email optin contacts in Splio.
ℹ️ As for now, the deletion will only be effective if the customer was created by the module in the first place. This restriction will be removed in the next release of the module.
3.5.8. Subscribers synchronization
If the module is configured to use a identifier attribute other than the email, if a newsletter subscriber is saved, it only ill be synchronized if it’s linked to a customer with the identifier attribute filled.
4. Splio Loyalty
The Splio Loyalty extension allows to integrate your Splio loyalty program in your Magento 2 / Adobe Commerce website.
To know more about this extension, please refer to the specific documentation available here.
5. Reference manual
5.1. Synchronized data mapping
The extension use the API given by Splio. The names of the fields below refers to fields expected by the API. See here for more information.
5.1.1. Contacts – Standard fields
Splio field name | Magento 2 data | Comment |
---|---|---|
lastname | lastname | |
firstname | firstname | |
creation_date | created_at | |
language | language code from the value of the configuration field « general/locale/code » in the store of the abandoned cart | « fr », « en », « es »… |
cellphone | phone number of the customer’s default billing address | |
lists | « 0 » and the value of the configuration field « splio_sync_contacts/newsletter/list_id » for the website of the abandoned cart | [0] or [0, x] |
5.1.2. Contacts – Custom fields
Here is the list of the custom fields used by the addon for customers / contacts
Splio field name | Magento 2 data | Data type | Comment |
---|---|---|---|
m2_customer_id | entity_id | int | |
m2_prefix | prefix | text | M, Mme… |
m2_gender | gender | text | « F », « M » or « N/A » |
m2_taxvat | tax_vat | text | VAT number |
m2_dob | dob | date | Date of birth |
m2_store | Value of the configuration field « splio_sync_carts/export/store_id » in the store of the abandoned cart | text | |
m2_default_address_zipcode | postcode of the default billing address | text | |
m2_default_address_city | city of the default billing address | text | |
m2_default_address_country_code | country_id of the default billing address | text | In the ISO 3166-2 standard |
m2_default_address_company | company of the default billing address | text | |
m2_last_sync_at | Current date | date | |
m2_created_at | created_at | date | |
m2_updated_at | updated_at | date | |
m2_last_login | last_login_at | date |
5.1.3. Products – Standard fields
Splio field name | Magento 2 data | Comment |
---|---|---|
external_id | Value of the configuration field « splio_sync_products/general/identifier » in the store of the abandoned cart | Default value: entity_id |
name | name | |
description | short_description | Free of any HTML code |
brand | brand | |
price | price_incl_tax of the parent product if configurable, of the product otherwise | |
sku | sku | |
img_url | product_small_image URL in the store of the abandoned cart | |
category | Concatenation of the categories names | « Man, Shoes, Sales » |
5.1.4. Products – Custom fields
Here is the list of the custom fields used by the addon for products
Splio field name | Magento 2 data | Data type | Comment |
---|---|---|---|
m2_parent_id | entity_id of the parent product, if it exists | text | |
m2_name_* | Name of the product for each locale used in API-defined scope | text | Ex: m2_name_fr_fr, m2_name_en_us |
m2_description_* | Short description of the product for each locale used in API-defined scope | text | Ex: m2_description_fr_fr, m2_description_en_us… Free of any HTML code |
m2_url_path | url_path | text | |
m2_inventory_level | Inventory level | double | Works with or without MSI |
m2_created_at | created_at | date | |
m2_updated_at | updated_at | date | |
m2_last_sync_at | Current date | date |
5.1.5. Abandoned carts, orders and credit memos
ℹ️ In Splio, abandoned cards, orders and credit memos are the same entity, distinct only by the « completed » flag, or the sign of the totals.
5.1.6. Orders – Standard fields
Splio field name | Magento 2 data | Comment |
---|---|---|
external_id | « m2_cart_ » followed by the entity_id of the cart, « m2_order_ » or « m2_creditmemo_ » followed by the increment_id of the order or the credit memo | m2_cart_2547, m2_order_10047154 or m2_creditmemo_20000547 |
contact_id | Splio ID of the contact, given the value of the configuration field « splio_sync_contacts/general/identifier » in the store of the abandoned cart | The customer ID, email address, or any other attribute defined in the configuration |
store_external_id | Value of the configuration field « splio_sync_carts/export/store_id » in the store of the abandoned cart | |
ordered_at | created_at | |
discount_amount | base_discount_amount | In base currency |
shipping_amount | base_shipping_amount | In base currency |
total_price | base_grand_total + base_tax_amount | In base currency, with or without shipping amount |
tax_amount | base_tax_amount | In base currency. Shipping amount can be excluded from total amount in the extension configuration |
completed | true or false | True if it’s an order, false if it’s an abandoned cart |
currency | base_currency_code | Base currency, ISO 4217 format |
5.1.7. Orders – Custom fields
Here is the list of the custom fields used by the addon for abandoned carts / orders / credit memos.
Splio field name | Magento 2 data | Data type | Comment |
---|---|---|---|
m2_status | For quote: “Abandoned cart”, for order: the status label, and for credit memo, the state name | text | |
m2_locale_currency | quote_currency_code | text | ISO 4217 format |
m2_locale_discount_amount | CartTotalRepository discount amount | double | In locale currency |
m2_locale_tax_amount | CartTotalRepository tax amount | double | In locale currency |
m2_locale_shipping_amount | CartTotalRepository shipping amount | double | In locale currency |
m2_locale_grand_total | CartTotalRepository grand total + tax amount | double | In locale currency, with or without shipping amount |
m2_updated_at | updated_at | date |
5.1.8. Items – Standard fields
Splio field name | Magento 2 data | Comment |
---|---|---|
unit_price | base_price_incl_tax of the parent product if configurable, of the product otherwise | In base currency |
quantity | qty of the parent product if configurable, of the product otherwise | |
discount_amount | base_discount_amount of the parent product if configurable, of the product otherwise | In base currency |
tax_amount | base_tax_amount of the parent product if configurable, of the product otherwise | |
total_line_amount | base_row_total_incl_tax minus base_discount_amount of the parent product if configurable, of the product otherwise | In base currency |
product_id | Product Splio ID, given the value of the configuration field « splio_sync_products/general/identifier » in the store of the abandoned cart |
5.1.9. Items – Custom fields
Here is the list of the custom fields used by the addon for abandoned carts items.
Splio field name | Magento 2 data | Data type | Comment |
---|---|---|---|
m2_locale_currency | Quote locale_currency_code | text | ISO 4217 format |
m2_locale_unit_price | price_incl_tax of the parent product if configurable, of the product otherwise | double | In locale currency |
m2_locale_discount_amount | discount_amount of the parent product if configurable, of the product otherwise | double | In locale currency |
m2_locale_tax_amount | tax_amount of the parent product if configurable, of the product otherwise | double | In locale currency |
m2_locale_total_line_amount | row_total_incl_tax minus discount_amount of the parent product if configurable, of the product otherwise | double | In locale currency |
6. Troubleshot
6.1. Error « The contact … has changed its email address… »
Description: on your job queue list page in admin menu System > To Splio Job Queue, a job is displayed in error, with the following message:
The contact « old.address@mail.com » has changed its email address (new address: « new.address@mail.com »), but the email address can’t be changed in Splio, as its the identifier field for contacts. Please review this issue with your contact in Splio.
Issue: when you choose to identify your contacts with their email address, you also indicate at Splio that this value can not be modified. But the email address modification by the customer is a basic feature of Magento 2 / Adobe Commerce. So when a customer is synchronized after the update of its email address, a specific error is returned by Splio API, saying that the unique key (email address) can’t be updated.
Solution: first, refer to your Splio contact to know the alternative solutions. You can also choose to handle it manually, by following this procedure:
- Go to the menu System > Synced Contacts
- Filter your contacts matching with the old email address of the customer (displayed in the error message
- Click on the link « Delete the matching »
- Go to the menu System > To Splio Job Queue
- Select the synchronization job in error, and choose the action « Replay »
It will create a new contact in Splio with the new email address.
ℹ️ If you use Splio Loyalty program, you may want to know that the new contact will not have the loyalty data of the old contact. Please refer with your Splio contact to know what to do in this situation.