conversion.track

‹ BACK TO API PAGE


Description

This method enables you to submit conversions on your web site that originated from click-throughs of emails sent from eMS Enterprise. The conversion is submitted as a single transaction, allowing the system to associate the conversion with the originating message, the specific link within the message that was clicked, and the subscriber who clicked the link.

Use this API method if you want to provide your own definition of a "conversion" – whether it be total nights booked in a hotel, a completed survey, a downloaded prospectus, a seminar registration, you name it. You can also use this method to define different aspects of a conversion that was completed within a single transaction (e.g. "rooms booked" and "reservation total").

Conversion data provided via this API method is displayed within eMS Enterprise as a custom report. The conversion data provided by this API method is not available for segmentation. Instead, use the roi.insert API method if you want to perform segmentation on your conversion data.

The implementation of this method assumes the following:

  • Your eMS Enterprise account is configured for Conversion Tracking. If you aren't sure if it is, contact your Account Manager, or https://mapp.com/support/ .
  • You have selected the option within the "Manage and Track Links" section of a message within eMS Enterprise to track conversions. You also have the option to track all links within the body of the email, or to only track conversions from specific links.
  • Your web site is properly capturing the unique parameter value being passed it from the email click-through and then returning that value back in this method call.
  • Your site visitor's browser is configured to accept the conversion tracking mechanism you are using on your site (i.e. accepts cookies, etc.).

Arguments

Field Description Field Type Required Example
conversion_type A string value that your system uses to identify the conversion type that occurred on the website after arriving from an email. The

NOTE: The usage of this element value is case-sensitive when eMS Enterprise computes the total and average amounts per conversion type.

string Yes rooms_booked
conversion_data A string value containing the "roi" parameter value passed to the client's website from the link in the email that the subscriber clicked. This value allows eMS Enterprise to associate the transaction to the individual and the email link the subscriber clicked that lead to the conversion. string Yes echo2-12346792-9292
389-0C978FABD
98766C7A88EDB98A76
amount A numerical value containing the total conversion value for the transaction, containing up to 4 decimal places. The value can be either positive (indicating a successful conversion) or negative (indicating a refund and cancellation). string Yes 4
transaction_id A string value used as the client's unique identifier for the specific transaction (e.g. "receipt number"). You may only use one transaction_id for a given conversion_type. Attempting to use a previously used transaction_id for the same conversion_type will result in the newer information being discarded. string Yes M112358
transaction_date The date the transaction occurred, in YYYY-MM-DD format. If not provided, this value will default to the date and time the conversion was processed by eMS Enterprise in US Pacific time zone. date No 2010-07-27
ignore_duplicate_transactions Overrides the default behavior of discarding transaction data when using a previously used transaction_id. Passing a value of 1 will allow additional transactions with the same transaction_id.

You would typically include this element if you wanted to submit incremental payments toward the full purchase price of an item (e.g. down payments, payments on installment, etc.) You can also use this element if you need to POST a refund.

boolean No 1

Response

Field Description Example
db_spec The database schema name assigned to the client. farm
mes_cont_id A system-generated unique number that identifies the contact and the message that lead to the conversion.
tracked_id A system-generated unique number that identifies the specific link within the email that lead to the conversion.
conversion_hash A system-generated hash code preventing artificial values submitted for conversion data. 96d5eb872565a12a6ca00b4034c8bafd
transaction_id The transaction_id passed in the original POST. M112358
conversion_type The conversion_type passed in the original POST. rooms_booked
amount The amount passed in the original POST. 152.99
transaction_date The purchase date passed in the original POST. 2010-07-27
ignore_duplicate_transactions The boolean flag passed in the original POST. 1

Response Codes

Response Code Response Text Description
201 Conversion will be saved and processed later A successful insertion of a conversion event.
401 Insert failed: invalid amount, field is not numeric The value provided in the <amount> element is non-numeric.
402 Insert failed: invalid transaction date, unable to parse The value provided in the <transaction_date> element is not in a valid date format.
403 Insert failed: Conversion Hash does not match The value provided in the <conversion_data> element is not a valid hash.

Example Post

<methodCall>

<methodname>conversion.track</methodname>

<conversion_data>echo2-10306055242-4306785-4a6eb932bc5cc82785b45d1f35d9851e </conversion_data>

<conversion_type>rooms_booked</conversion_type>

<amount>4</amount>

<conversion_date>2010-07-29</conversion_date>

<transaction_id>M112358</transaction_id>

</methodCall>

<methodCall>

<methodname>conversion.track</methodname>

<conversion_data>echo2-10306055242-4306785-4a6eb932bc5cc82785b45d1f35d9851e </conversion_data>

<conversion_type>reservation_total</conversion_type>

<amount>1020.25</amount>

<conversion_date>2010-07-29</conversion_date>

<transaction_id>M112358</transaction_id>

</methodCall>

Example Response

<methodResponse>

<item>

<methodName>conversion.track</methodName>

<responseText>Conversion will be saved and processed later.</responseText>

<responseData>

<db_spec>echo2</db_spec>

<mes_cont_id>10306055242</mes_cont_id>

<tracked_id>4306785</tracked_id>

<conversion_hash>4a6eb932bc5cc82785b45d1f35d9851e</conversion_hash>

<conversion_type>rooms_booked</conversion_type>

<transaction_id>M112358</transaction_id>

<amount>4</amount>

<transaction_date>2010-07-29</transaction_date>

<ignore_duplicate_transactions></ignore_duplicate_transactions>

</responseData>

<responseNum>1</responseNum>

</item>

<item>

<methodName>conversion.track</methodName>

<responseText>Conversion will be saved and processed later.</responseText>

<responseData>

<db_spec>echo2</db_spec>

<mes_cont_id>10306055242</mes_cont_id>

<tracked_id><4306785</tracked_id>

<conversion_hash>4a6eb932bc5cc82785b45d1f35d9851e</conversion_hash>

<conversion_type>reservation_total</conversion_type>

<transaction_id>M112358</transaction_id>

<amount>1020.25</amount>

<transaction_date>2010-07-29</transaction_date>

<ignore_duplicate_transactions></ignore_duplicate_transactions>

</responseData>

<responseNum>1</responseNum>

</item>

</methodResponse>


Back to API Reference Guide