SALESmanago is a perfect tool for E-commerce and B2B. In our system, your online marketing and sales activities are automated thanks to monitoring customers’ behaviour on the website, building their 360* profiles, personalization of communication as well as fully automated campaigns. Additionally, SALESmanago provides you with complex analytical panels that show data including: precise analysis of the sources of transactions, sum of transactions and products analytics.
IMPORTANT: This article has been written for people who want to integrate their shops with SALESmanago by themselves. The tips that you have here are very important. If you do not follow them, you cannot exploit SALESmanago potential fully. So as to exploit the full potential of SALESmanago, you need to integrate your platforms with our system.
E-commerce platforms for which we already have integrations. >>
GLOSSARY
- e-shop – online shop defined in SALESmanago
- product feed – all information about the products offered in the shop
- transaction / external event (transactional data) – information about the transaction or other event (e.g. adding a product to the cart) sent from e-shop to SALESmanago system (by API).
E-SHOP DEFINITION
E-shop means a single online shop (e.g. a website) that offers products. E-shop in SALESmanago means a set of information about the shop. In e-shop the following values are defined:
- name
- e-shop ID
- e-shop currency – that is the currency in which values of purchases in the external events are sent
- e-shop language – that is the language used to send information about products in the shop
- URL of the product feed – that means adding a file which contains information about products in the shop
So as to define such a shop in the SALESmanago system you need a unique shop identifier, e.g. the name of the shop domain and also complex and correct set of products (that is product feed – the source of information about the products) where there are all products available in the shop together with their identifiers and unique URL addresses. Such a product feed should be available to be downloaded in the XML file from the specified URL address in the SALESmanago system.
1 shop = 1 unique identifier (e-shop ID) = 1 product feed (source of data)
IMPORTANT: When you start your online shop, remember that each product needs to have a unique URL address. That is important in the analysis which is connected with identification of website traffic. It is also highly recommended for SEO purposes.
EXAMPLE: When you have 2 shops – www.shop.pl and www.shop.com and one SALESmanago account, you need to define 2 e-shops for each website as well as a separate e-shop.
E-SHOP ID – DEFINITION
This identifier is used to connect transactions reported in SALESmanago system with an e-shop and in consequence with products sent in the transaction with a particular product feed. The maximum number of characters that the identifier can contain is 36 without spaces (available characters: letters a-z, numbers 1-9,/_-.)
So as to transfer data by API, the identifier needs to be sent in the LOCATION field in the external events sent from the particular shop.
IMPORTANT: When you have only one product feed added, the system will connect the events with the product feed added to the system automatically. However, when you have many shops (multistore option) it is important to maintain the coherence in sending external events and the unique identifier. It means that each shop needs to have its unique e-shop identifier as well as its unique product feed.
PRODUCT FEED (URL ADDRESS OF DATA SOURCE)
It is a file that contains descriptions and attributes of products available in the online shop. In SALESmanago it is an XML file.
IMPORTANT: A complete, unique XML file needs to be defined for each e-shop. The file contains a unique ID for each product as well as a unique URL address.
Additional product sources are not taken into consideration in the analytics and reports. They can be used to create dynamic content only.
Detailed information about XML >>
Learn how to add an XML file to SALESmanago system >>
Product ID – must be unique for the e-shop and a digit sequence. Product ID cannot contain any other characters. There cannot be also any extra information, e.g. size.
Correct product ID: 4567
Incorrect product ID: 4567_M ; 4xb567 ; 4-5-677
WHY IS IT IMPORTANT TO HAVE THE SAME ID IN XML AND SENT EXTERNAL EVENTS?
When you send an external event that contains e.g. 3 product IDs – 2346, 7899, 1222 and it occurs that while sending at least one ID is not connected with the information included in the XML file, the whole event is not taken into consideration in the analytics and statistics in SALESmanago. That is why it is highly recommended to have an XML file with all products available in the shop.
WHY IS IT IMPORTANT THAT EACH PRODUCT HAS A UNIQUE URL ADDRESS ON THE WEBSITE AND THE SAME URL ADDRESS IN THE XML FILE?
One of SALESmanago features is monitoring customers’ behaviour on the website. The monitoring is possible thanks to e.g. saving URL addresses that are visited by the contact on the website. Having the URL address of the website that was visited, it is possible to connect it with the URL address of the product saved in the XML file. Thanks to that, it is possible to identify precisely what product was viewed by the contact and next, the information can be used to recommend products, e.g. in recommendation frames and dynamic emails. When the URL address of the product on the website differs from the URL address that you have in the XML file, connecting elements is not possible and the potential of SALESmanago cannot be exploited fully.
WAY OF SENDING TRANSACTIONAL DATA TO SALESmanago
External events are sent between e-shop platform and SALESmanago thanks to API (addContactExtEvent method).
There are 4 types of external events:
CART, PURCHASE, CANCELLATION, RETURN.
- CART – information about the cart
- each addition of the product to the cart should be sent as a separate external event, type CART
- for each event in the VALUE field there should be a value of all products in the cart in the event
- events should not be deleted and modified
- PURCHASE – information about the products bought
- each finalized transaction should be sent as an external event, type PURCHASE
- for each event in the VALUE field there should be a value of all products bought in the event
- events should not be deleted and modified
- CANCELLATION – information about the return / cancellation of the purchase
- when you want to report the change concerning cancellation of all transactions, the type of the external event should be CANCELLATION. In this event there should be exactly the same product IDs that were sent in the previous transaction that is to be reported as canceled.
- for each event in the VALUE field there should be a sum of all products canceled in the event
- events should not be deleted and modified
- RETURN – information about the return of product(s)
- when you want to report the return of one / a few products bought, the type of the external event should be RETURN. In this event there should be product IDs that were bought previously.
- for each event in the VALUE field there should be a value of all products returned in the event
- events should not be deleted and modified
Below there is an exemplary request sent by API that registers the external event.
{
"clientId":"your-client-id-123",
"apiKey":"your-api-key-123",
"requestTime":1356180568127,
"sha":"3e4ec39722326150aae60f41e038d1def4450f46",
"owner":"admin@vendor.pl",
"email":"konrad@benhauer.com",
"forceOptOut": true,
"contactEvent":{
"date":1356180568153,
"description":"Zakup z kartą \"Super Bonus\"",
"products":"123,478",
"location":"shop_123",
"value":1234.43,
"contactExtEventType":"PURCHASE",
"detail1":"C.ID: *** *** 234",
"detail2":"Płatość kartą",
"detail3":null,
"externalId":"A-123123123",
"shopDomain":"shop.salesmanago.pl"
}
}| Field | Maximum length | Description |
| cientId | required field – your unique SALESmanago account identifier. You can find it in Settings ->Others | |
| apiKey | required field – your unique SALESmanago account key. You can find it in Settings ->Others | |
| requestTime | timestamp | date of sending the request |
| owner | 255 | required field – contact owner / email address of acounts in SALESmanago system |
| email / contactID | 255 | contact’s email address or a unique contact ID (unique ID is available for some clients only) |
| email forceOptOut | true / false |
contact status – false – contact will have an opt-out status (no agreement to receive messages via email) or opt-in (agreement to receive messages via email) |
| date | timestamp | required field – date of the transaction that took place in the shop (real purchase date) |
| description | 255 | additional description of the transaction |
| products | 512 | required field – list of product IDs separated by a comma.
Example: When a client buys one product with the ID 234, the correct format of data sent is “234”. |
| location | 36 |
required field – unique e-shop ID which is used to connect information sent in the external event along with information found in the e-shop. IMPORTANT: the value can contain letters a-z, numbers 1-9, /_-. without spaces – letter size matters – only lower case available. |
| value | 19 (+ 2 after the dot) |
required field – the total sales of all products sent in the event. The value of the field should not be empty or “null”. Example: in PRODUCT field the value that is sent is: “345.678” IMPORTANT: In the VALUE field there is no information about the currency! The currency is defined when an XML file is added to your e-shop in SALESmanago system. Remember that 1 shop should have one currency only. It is important when you analyze the total sales of products sold. Let’s assume that the value of the first transaction in one shop is $200, the second transaction amounts to EUR300. The first event will have the value 200, the second event will have the value 300, which gives the value of 500. However, it is not the same as $200 + EUR300. |
| contact ExtEvent Type | 255 | required field – Type: CART, PURCHASE, CANCELLATION, RETURN |
| detail 1-20 |
possibility to send 20 different details about products that can be found in external events or other details concerning the transaction. If you want to send a few values concerning different products within one detail, the order of detail values should be the same as the order of product IDs sent, separated by a comma. Example: In the event there are 2 products sent: in the PRODUCT field the value is: “345,678” |
|
| ShopDomain | Field for the shop domain. Optional field. |
To make sure that the integration of transactional data between an external platform and SALESmanago is correct, follow the checklist and answer “yes” to all the questions.
1. VERIFICATION WITH ALL CLIENTS
Preparation of product feed (XML)
- Does the XML file contain all products available in the shop?
- Does every product have a unique product ID (numbers only)?
- Does every product have a unique URL address of the product?
- Is there a price for every product?
- Does the client make all necessary updates in a product feed what makes you sure that all information about the available products in the shop is up-to-date?
- Is there one currency in the XML file for all products?
Addition of the product feed in SALESmanago
- Does every shop have only one e-shop account with the product feed?
- Providing that one shop has more than one e-shop account with the product feed, is there an option “set this shop as default” checked?
- Is there a value in the e-shop ID (location) field in the e-shop with the product feed? That is the value sent in the external events in the location field
1. VERIFICATION WITH A CLIENT DEPENDING ON THE INTEGRATION TYPE
INTEGRATION OF THE EXTERNAL EVENTS BY API
- Are external events type CART, PURCHASE, CANCELATION, RETURN sent?
- Are there any changes / updates in the external events now?
- Is there a unique e-shop ID in the location field sent in the external events?
- Is the value in the date field sent in timestamp format in the external events?
- Are products IDs sent in the products field in the external events correctly?
- Is the value in the value field sent correctly in the external events and the field is not empty?
INTEGRATION OF EXTERNAL EVENTS BY SALESmanago PLUGIN
- Does the client have the newest version of the plugin?
IMPORTANT: Remember that all answers to these questions must be ‘yes’ answers. Then you can be sure that the integration of transactional data between an external platform and SALESmanago is done properly.