Emarsys User Guide
Emarsys is a web marketing tool and Aurora's Emarsys feed permits you to export your products to the Emarsys system using a single product feed. For more information on what Emarsys is and how it can help your business, please see their website.
This article details how to make use of Aurora's Emarsys product feed.
Introduction
Aurora's Emarsys feed permits you to export your products to the Emarsys system using a single product feed. This feed is provided in a CSV format, as required by Emarsys, and once enabled can be accessed at the following location on your own website (i.e. replace the www.aurorademo.com section with your own domain name).
https://demo.auroracommerce.com/datafeeds/emarsys/products.csv
Product Feed
Format
The product feed is provided as a Comma Separated File (CSV) and includes the “Last-Modified” HTTP Header which allows clients to tell when the file was last updated (which is usually once every 24 hours).
The first row in this file always includes the names of the fields that are found within the feed itself (even when there are no products to list). One line is included for each product and so variations are not detailed in this feed separately.
Field Specification
All of the following fields will are included in the feed, in this order.
| Field name | Example value | Description |
|---|---|---|
| item | SKU1234567 | The Aurora Product Reference. |
| available | true | This will be “true” if the product is in stock. |
| title | Oversized Panel Shirt Dress | The name of the product in Aurora. |
| link | https://demo.auroracommerce.com/clothing/ s043-0406-008_black.html | The URL of the item’s product page. |
| image | https://demo.auroracommerce.com/images/ap/ resizeandpad:200:200/91263.jpg | The main/first image will be used here and presented at a maximum size of 200x200 pixels. |
| category | Clothing > Shirts | Sale > Men’s | A string representation of all the published/live product categories to which the product belongs. Parent categories are separated from their children with the “ > ” string. If there are multiple Category trees to be listed, they are separated using a pipe (“|”) character. |
| price | 9.00 | The Price saved in Aurora for the product. The two decimal places are always included, e.g. even when the price is 1.00. |
| msrp | 12.99 | The RRP saved in Aurora for the product. If the RRP is not set, then the normal Price will be used instead. The two decimal places are always included, e.g. even when the price is 1.00. |
| c_colour | Black | This is the colour specified in Aurora under the product’s “Colour” Additional Field. |
| c_product_reference | LF_EXAMPLE_REF1 | The Product's Reference field. |
Languages
The feed supports multiple languages. You can access the feed with French translations for the products it features by simply accessing the feed in the French URL, as show below.
https://demo.auroracommerce.com/fr/datafeeds/emarsys/products.csv
This assumes you have enabled and fully configured alternate languages. This is not an automatic process and will only work if you already have a French (for example) transaction in place for your Store.
Currencies
The feed supports multiple currencies. You can access the feed with prices in an alternate currency for the products it features by simply accessing the feed as show below.
https://demo.auroracommerce.com/datafeeds/emarsys/products.csv?currency=USD
This assumes you have alternate currencies configured in Aurora already. If you do not, then this will not work and will only work for the ones you have configured in the Aurora Back-end under Store > Configure > Currencies.
How to include Products in the Emarsys feed
To include a product in the Emarsys feed, first create an Additional Field called “Send to Emarsys”. (Please note that this field may have been automatically created for you if the feed is already enabled.) For each product to then be included in the feed, set the value of the field to “1”, or, if the field is of the check box type, tick the checkbox.
Products are not included in the feed if they are not Live.
Caching
The product feed is cached for a 24 hour period. The product details listed in the file will not change between these cache refresh periods unless you manually force the cache to be regenerated, which you can do as described below.
You can manually regenerate the feed using the Aurora Back-end under Store > Settings > Feeds > Emarsys. Here you will see a button allowing you to "Clear Product Feed Cache". Doing this will schedule a task in the background to regenerate the feeds.
This has been implemented to prevent the cache generation process causing your browser to hang in the event the feed takes a long time to generate, likely due to a large product database.
This process can take a long time and so you should allow an hour or so to pass before checking the feed for its new content (though with smaller product databases, this should only take a few minutes).
Backend Settings
This section will explain some of the options when configuring Emarsys.
Enabled?
When the Enabled? tick-box is not checked, the integration will be disabled throughout Aurora. This will disable all associated CLI processes, preventing them from uploading or downloading changes of any sort.
Order Types to send to Emarsys
The Sales Data and Contact Data sent to Emarsys will only include data associated to Orders with the Payment Types you configure here:
If you select the All Orders option, then this filter will not be applied and so all eligible records will be sent to Emarsys.
Changing this setting takes affect the moment you save the Store settings page and can result in data immediately being delivered to Emarsys. Should this occur, any data sent cannot be 'un-sent', i.e. if you un-select a Payment Type added in error that you did not want Emarsys to receive, Aurora cannot (and does not) 'remove' the data already sent from Emarsys, it will simply no longer send it going forwards.
Live?
This will switch the integrations processes between using the Live and Test credentials.
Date to export Transactions from
Accept a date to control how far back the Transactional Export will go when sending the transactional data.
Date to export Contacts from
Accept a date to control how far back the Contacts Export will go when sending the contact data.
Live Merchant ID
Merchant ID provided by Emarsys, when the Emarsys integration is Live.
Live Username
Username provided by Emarsys, when the Emarsys integration is Live.
Live Secret
Security token, which can be obtained by clicking the Show API upload details button on the Sales Data page in Emarsys when Emarsys integration is Live.
Live Upload Token
Security token, which can be obtained by clicking the Show API upload details button on the Sales Data page in Emarsys when Emarsys integration is Live.
Test Merchant ID
Merchant ID provided by Emarsys, when the Emarsys integration is in Test mode.
Test Username
Username provided by Emarsys, when the Emarsys integration is in Test mode.
Test Secret
Security token, which can be obtained by clicking the Show API upload details button on the Sales Data page in Emarsys when Emarsys integration is in Test mode.
Test Upload Token
Security token, which can be obtained by clicking the Show API upload details button on the Sales Data page in Emarsys when Emarsys integration is in Test mode.
Log Requests?
When this is ticked, all requests sent to and responses received from the Emarsys API will be logged
Import Countries/Languages
Emarsys maintains internal lists of Countries and Languages that must then be used by Aurora when sending the Sales and Contact Data.
For example, when the Customer Address is sent to Emarsys, the country provided with said address, must match a country from the Emarsys Database (which Aurora does not maintain).
This means that the countries and languages configured in Aurora, must be 'matched up' to countries and language in Emarsys, otherwise Aurora cannot give Emarsys the correct values. Furthermore, any country configured for use in Aurora, must also be configured in Emarsys if a Customer Address is going to be using it, e.g. Aurora cannot send a Customer Address in Spain to Emarsys if Spain is not first configured in Emarsys itself.
To solve this problem, some import processes have been created and made accessible via the Aurora Back-end under Store > Settings > Feeds > Emarsys > Import Countries/Languages.
These buttons will allow you to tell Aurora to attempt to contact Emarsys and 'map' it's own Countries and Languages with those configured in Emarsys. On doing so, Aurora will immediately attempt to do this and report back on any issues encountered.
If there are any problems, they will likely be that Aurora could not match a country or language between itself and Emarsys due to it either not existing in Emarsys or not being named correctly in either Emarsys or Aurora. If this occurs, Aurora will inform you of the affected countries and languages and you will then be required to configure (or have Emarsys configure) the correct countries or languages to allow the system to work.
Import Countries
Import Languages
Contact Feed
This feed is used to register contacts in Emarsys.
This feed will be sent to Emarsys on bulk once every minute to ensure as close to ‘real-time’ delivery of this data as possible without running the risk of delaying the checkout process for the customer when processing orders.
Contacts include:
- Visitors which create an account
- Customers with an order
- Newsletter sign-ups
Customers from Amazon, Debenhams, Intu are not included. Guest Contacts, if they already have an account with this email in Aurora and have been registered to Emarsys, will be matched. Accounts from newsletters will be matched if they opt in.
Historic Contacts
A historic contact feed to create existing contacts in Emarsys can be requested from AC.
Format
The contact feed will be in json format which will be sent to the Emarsys REST API to create or update the contacts.
Field Specification
All of the following fields are included in the feed.
| Field name | Example value | Description |
|---|---|---|
| First name | Sarah | Contact's first name |
| Last name | Green | Contact's last name |
| [email protected] | Contact's email | |
| Date of birth | 1987-02-28 | Contact's date of birth |
| Gender | Female | Gender of the Contact |
| Contact title | Ms | Concat's title depends on Store configurations This is custom field in Emarsys |
| Address | Street Hamilton 32 | Contact's address |
| Town | London | Contact's town |
| County | London | Contact's county |
| Country | 184 | Contact's country Value is the key which corresponds to the Emarsys country, i.e. United Kingdom |
| Phone number | 0982130219 | Contacts's phone number |
| Mobile phone number | 9304701384 | Contact's mobile phone number |
| Opt-in | 1 | Contact's opt in choice |
| Language | 1 | Contact's language Value is the key which corresponds to the Emarsys Language, i.e. English |
| id | 1000 | Emarsys ID |
| Post code | IP326EZ | Contact's post code |
| User type | Customer | Contacts's user type |
| User group | Group1|Group2 | Contact's groups |
| User Additional fields | User: field | Contacts's additional fields if the contact is registered user |
| Newsletter Additional fields | Newsletter: field | Contacts's additional fields if the contact is from newsletter |
| SUBREF Identifier | Yes | User product subscription status (Yes or No) where SUBREF is the subscription product reference. |
| SUBREF Start Date | 2019-01-01 | User product subscription start date of the first subscription to the SUBREF product. |
| SUBREF Expiry Date | 2020-10-01 | User product subscription expiry date of the last subscription to the SUBREF product. |
| SUBREF Count | 2 | The total number of active and inactive subscriptions to the SUBREF product. |
Order/Transactional Feed
This feed will be sent to Emarsys on bulk once every 15 minutes to ensure as close to ‘real-time’ delivery of this data as possible without running the risk of delaying the checkout process for the customer when processing orders. Only transactions with received customer id from Emarsys will be exported.
Historic Order/Transactions
The historic transactions could be requested from AC.
Format
The Order/Transaction feed is provided as a Comma Separated File (CSV).
The first row in this file always includes the names of the fields that are found within the feed itself. One line is included for each transaction.
Field Specification
All of the following fields are included in the feed.
| Field name | Example value | Description |
|---|---|---|
| item | V59B924CE4D80E | The product or variation reference of the item where the variation reference takes precedence. |
| price | 19.98 | This is the total amount of the transaction (product price * product quantity). |
| order | 716238 | This is the order id in the aurora system of which the item belongs to. |
| timestamp | 2016-06-06T14:02:00Z | The time when the ordered item was created. |
| customer | 72054 | The Emarsys id for the corresponding contact. |
| quantity | 1 | The item quantity. |
| s_product_size | Size: 10 | The item size. |
| s_product_colour | Black | The item colour. |
| s_product_category | Clothes > Dresses | The product category and sub-category that the item belongs to. |
| s_order_source | app | The source of the order. Will return "app" if the Payment type or Orders source contains "app". If not, "online" will be returned. |
| s_order_payment_type | card | The payment type of the item. |
| s_product_style_code | 90000000793 | The product retailer code. |
| s_order_shipping_type | Next Day – United Kingdom | The shipping type of the item. |
| s_order_carrier | Hermes Courier Service Next Day | The courier name. |
| s_order_tracking_number | 987965444 | Tracking number of the order. |
| s_order_tracking_link | http://tracking-url.com/tracking\_number=987965444 | The tracking url fs_location of the order. |
| f_unit_price | 9.99 | The product price. |
| f_price_paid | 18.98 | The amount paid for the transaction. |
| f_buy_in_price | 2.99 | The product buy in price. |
| f_discount | 1.00 | The discount applied for the item. |
| s_ean | 5053028903155 | Variation or product ean where the variation ean takes precedence. |
| s_return_reason_code | Faulty product. | The return reason, only filled for refunds. |
| s_location | aurorademo.com | The domain name from which the request is made. |
| s_promotion | Buy 1 get 2 | The promotion applied to the item. |
The order shipping type, carrier, tracking number and tracking link are all sourced from the top level order unless the item is part of a part despatch and the part despatch has been assigned a shipping method.
Alternate Supported Services
CommunicatorCorp Guide
DotMailer Guide
Updated over 2 years ago