roi.insert

‹ BACK TO API PAGE


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 BlueHornet to associate the order to the individual contact and the email link associated with the sale. string Yes http://echo.​bluehornet.com/​ct/3416623:​619-295-1856:m:​1:97777016:
D40E94EF977A​CAA8AC1BE3
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>


Back to API Reference Guide