- 2 Minutes to read
- Print
- DarkLight
roi.insert
- 2 Minutes to read
- Print
- DarkLight
General Information
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 website 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 website 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 |
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 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 is in YYYY-MM-DD format. If not provided, this value will default to the current date in the 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 leads 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 | 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>