Contents x
      roi.insert
      • 2 Minutes to read
      • Print
      • Dark
        Light
      Contents

      roi.insert

      • 2 Minutes to read
      • Print
      • Dark
        Light
      Article Summary

      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: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 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>

      Was this article helpful?
      What's Next