purchase command makes it possible for you to track purchases in your web store. It has to be called whenever a purchase is made, and should pass the order ID, the list of purchased items, the quantities and prices of each orderline to Emarsys.
Emarsys uses the data collected with this command widely in the platform, among other things for behavior analysis and personalization, revenue statistics and campaign attribution. You will also be able to use it to trigger events or personalize content in certain Emarsys products, such as the Automation Center, Smart Insight and Predict.
What happens with this data?
Within a few hours, the data reported by the
purchase command is written to the following behavior fields in your contact database:
- predict last purchase date – This field is updated with the date stamp YYYY-MM-DD.
predict last purchase products – This field is updated with a pipe-separated list of the items passed by the last
item1 | item2…). A maximum of 10 items are stored in the field.
- predict last purchase categories – This field is updated with a pipe-separated list of the product categories the purchased items belonged to. A maximum of 10 categories are stored in the field.
predict last purchase total price – This field is updated with the total amount of the order based on the
- Orders are added to revenue statistics on the following day (Data Sources > Site Traffic).
- If the purchase is attributable to a click on an email campaign, it gets attributed to that campaign (Analysis > Trends).
- The order becomes available as behavioral data for segmentation throughout the platform.
purchase command must always be called together with a user identification command. The purchase, as such, is the most important interaction on your website, and we want to be sure that an explicit user identifier accompanies each purchase so that we can link orders to contacts found in your contact database.
Where should this command go in my web store?
Purchases should be reported to Emarsys once the order is placed and the payment is complete, ideally on the order confirmation page.
Make sure to implement the command on all possible checkout paths (quick/standard checkout/mobile website/mobile app), and for the return paths of all available payment methods (e.g. credit card, Paypal, bank transfer).
Every purchase should be reported to Emarsys only once.
Who do I need to involve from my side?
purchase command is implemented on the store frontend, for which you will need a frontend developer. It is a single script, taking an array of 4 parameters:
How can I monitor if it works properly?
The Data Sources page is your starting point for troubleshooting any integration issues and monitoring your Web Extend implementation.
In the Web Behavior box:
- Warnings and error messages will be displayed if we detect issues.
- You can monitor your visitors’ activity, including purchases, in real time in a live ticker.
In the Product Matching box on the right, you will see warnings and error messages if the product IDs passed by the
purchase command are not consistent with the IDs found in your product database.
On the Data Sources > Site Traffic page, you can get an overview of the total number of orders and order lines as well as the revenue tracked in a selected period and compare it to your in-house website statistics. From this page, you can also download all recorded purchases in a .csv file (for a period of 30 days).
Do not use our revenue reports for accounting purposes as they only include product purchases we can track on your website. Other revenue, such as delivery or packaging costs, offline sales, returns and cancellations are not figured in the statistics shown on the Site Traffic page.
testMode command to prevent test data from being written to your real contact database as this may skew your reporting.
- Pass all the purchased items in a single command (do not split an order into multiple purchases).
- Empty the cart once the purchase is completed.
- Issue the command only once for any given purchase. Emarsys does not deduplicate orders.
- Always issue a user identifier command (
setCustomerId) together with the
- Make a decision about whether you want to report net or gross prices, and use either of them consistently whenever your pass prices with the Web Extend commands. The prices you pass here will be the basis of all revenue reporting.
- For precise revenue reporting, pass only standard product purchases with this command (and exclude items like packaging and delivery costs, gifts etc.). If you do want to pass such non-standard items, always add them to your product data file and mark them as unavailable first.
- Make sure to implement the command on all possible checkout paths (quick/standard checkout/mobile website/mobile app), and for the return paths of all available payment methods (eg. credit card, Paypal, bank transfer).
- If you have a dedicated m.domain.com mobile page and a mobile app, do not forget to add the command to these as well. For mobile apps, use our SDK.
Check if it works
To see if the
purchase commands work properly on your website, do the following:
- In your browser, open your web store and make a test purchase.
- Open another tab in your browser, log in to your Emarsys account, go to Admin > Data Sources > Web Behavior and click Live Events in the upper right-hand corner. This will open the Live Events page.
- Select my visit in the second drop-down.
- You should see an event containing an email hash (or customer ID), an orderID, an empty cart box, and a purchase box with the purchased items, quantities and prices listed in it.
On the Live Events page, you will see product images in the purchase boxes if the products reported by the
purchase command are found in your product database. If no product image is shown, either a wrong ID was passed, or your uploaded product data is not up to date.
If the command is implemented correctly then:
orderIDshould match that of your test order.
- The cart should be empty.
- All purchased items are listed in the purchase box.
- The product quantities and subtotals match those of your test order.
purchasecommand is accompanied by a user identifier in same event (here Emailhash).
You can also install our Inspector bookmarklet that allows you to monitor live the Web Extend commands called on your website. If you implemented the
purchase command correctly, it should appear in the Inspector overlay on the order confirmation pages, and only there.
If everything works as expected, deploy the code to your live environment.
Always remember to remove the
testMode command from your code first!
In this section, you can read about the tools you can use and the things you can do to check if the
purchase command is doing its job properly on your website.
Once your JS implementation has gone live, the Live Events ticker will start showing data in the Web Behavior box of the Data Sources page. The ticker should now show purchases in real time.
- Check if Live Validator has any warnings or error messages related to the
- If it does, fix the issues or contact Emarsys Support if you need help.
Site Traffic statistics
Check if the following metrics match your in-house data:
Total Revenue Tracked - This number is calculated by simply adding up the values reported to Emarsys in the
priceattribute of the
Total Orders - This number is calculated from the number of times the
purchasecommand was called. It should equal the number of orders in your records.
Total Order Lines - This number is calculated by adding up each line (item) reported with the
If the difference between these numbers and your in-house reports is greater than 5% then you should review your implementation.
Check contact DB field updates
Another way to validate purchase-related data collection is to directly segment your contact database for a relevant behavior field, for example predict last purchase date
was in last 2 days. This segment should include all known contacts who have made a purchase in the last two days, a list that should be easy enough to compare with your in-house data.
Select a few random contacts, and review the contents of the three other predict last purchase... behavior fields as well.