Description
This method submits the information of a single e-commerce transaction allowing the system to associate the transaction with the originating message, the link in that message clicked, and the contact that clicked the link. The response back indicates whether the insert was successful.
Consider using the conversion.track method to POST all types of web site conversions. This particular API method gives you more flexibility in defining the types of email click-through conversions that you want to track.
Arguments
| Field | Description | Field Type | Required | Example |
|---|---|---|---|---|
| roi_data | A string value containing the ROI variable data passed to the client's web site through the link in the email the contact clicked. This value allows Mapp to associate the order to the individual contact and the email link associated with the sale. | string | Yes | http://echo.Mapp.com/ct/3416623:619-295-1856:m:1:97777016: D40E94EF977ACAA8AC1BE3 F94318DC58 |
| amount | A numeric value containing the amount associated with the order in USD. This variable should not contain the dollar sign ($) or commas, and should have the format "dollars.cents", with cents only consisting of two digits. | string | Yes | 152.99 |
| order_id | A string value used as the unique identifier for the specific transaction. Think of it as the receipt number. Only one order ID may be used per method call. Attempting to use a previously used order ID will result in the newer information being discarded. | string | Yes | 1123 |
| ignore_duplicate_orders | Overrides the default behavior of ignoring order data when the the same order_id is used multiple times. Passing this argument will allow additional entries with the same order_id. | boolean | No | 1 |
| purchase_date | The purchase date of the order in YYYY-MM-DD format. If not provided, this value will default to the current date in Pacific (US) time zone. | string | No | 2010-03-01 |
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 purchase. | |
| tracked_id | A system-generated unique number that identifies the specific link within the email that lead to the purchase. | |
| roi_hash | A system-generated hash code preventing artificial values submitted for roi_data. | 96d5eb872565a12a6ca00b4034c8bafd |
| order_id | The order_id passed in the original POST. | 1123 |
| amount | The amount passed in the original POST. | 152.99 |
| purchase_date | The purchase date passed in the original POST. | 2009-09-01 |
| ignore_duplicate_orders | 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. |
| 402 | Insert failed: invalid purchase date, unable to parse | The value provided in the <purchase_date> element is not in a valid date format |
| 403 | Insert failed: ROI Hash does not match | The value provided in the <roi_date> element is not a valid hash |
Example Post
<methodCall>
<methodName>roi.insert</methodName>
<roi_data>echo3-619-295-1856-1242357-1daecd68df79e83bf13f244b9a880ab9</roi_data>
<amount>123.45</amount>
<order_id>M2567814</order_id>
</methodCall>
Example Response
<methodResponse>
<item>
<methodName>roi.insert</methodName>
<responseText>Insert will be saved and processed later.</responseText>
<responseData>
<db_spec>farm</db_spec>
<mes_cont_id>18547855</mes_cont_id>
<tracked_id>135843</tracked_id>
<roi_hash>96d5eb872565a12a6ca00b4034c8bafd</roi_hash>
<order_id>123</order_id>
<amount>152.99</amount>
<purchase_date>2009-03-18 16:41:28</purchase_date>
<ignore_duplicate_orders>1</ignore_duplicate_orders>
</responseData>
<responseNum>1</responseNum>
</item>
</methodResponse>