Description
This method enables you to submit conversions on your web site that originated from click-throughs of emails sent from Empower 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 Empower 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 Empower Enterprise account is configured for Conversion Tracking. If you aren't sure if it is, contact your Account Manager, or https://mapp.com/tech-support/.
- You have selected the option within the "Manage and Track Links" section of a message within Empower 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 Empower 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 Empower 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 Empower 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>