Importing Conversions

If you want to update or create many conversions at a time, you can use the Conversion Upload tool to help you do so more quickly. In this article, we go through acceptable input files and discuss the tasks you can do: creating conversions by transaction ID, updating existing conversions, and creating conversions without transaction IDs.

Once you’ve prepared an input file, you can import your conversions. From the main navigation, go to Reports > Conversion Report. Then click the Conversion Upload button at the top of the table.

For notes on importing errors, pixel-based offers, and creating multiple conversions per transaction ID, skip to Additional Notes below.

Formatting Your Input File

As a best practice, we recommend using separate input files for each task. This facilitates any future troubleshooting or investigation you may want to do. Only highly advanced users should attempt to combine multiple formatting methods below in the same CSV file.

Your input file must be a comma-delimited CSV file containing the conversions you want to import. It must also:

  • Contain no more than 10,000 conversions
  • Match accepted value restrictions (case-sensitive)
  • Include headers for each column/field
  • Separate records using newline characters

Creating Conversions by Transaction ID

To create conversions in your network by transaction ID, your input file should contain only transaction IDs. This creates conversions in each session with a matching transaction ID and pulls in any available session data. A common use case for this is to process clicks that don’t yet have conversions.

New conversions added with this method default to the “approved” conversion approval status. For offers with the Approve Conversions tracking setting enabled, new conversions are instead set to “pending”.

When you use the tool to create new conversions for three existing transaction IDs, your input file should look something like this:

transaction_id
102b3t4hj545lbgl4v9833
102kjluwer0935842083g
1024235t9078tw987697

Important: If you attempt to create a conversion for a session that has already converted using this method, then that session may be updated instead. Existing conversions that match an uploaded transaction ID and have a conversion approval status of “pending” are set to “approved”.

Exception When Using Payout & Revenue Groups

When creating a conversion for an offer that uses payout and revenue groups, you must also include fields for payout and revenue values. As with the above method, conversions must not already exist for the sessions being referenced. Otherwise, the conversion for that session will be updated instead.

For example, the above input file looks like this when including fields and values for payout and revenue:

transaction_id,payout,revenue
102b3t4hj545lbgl4v9833,3.25,5.5
102kjluwer0935842083g,0.80,1.30
1024235t9078tw987697,1.00,2.00

Updating Existing Conversions

To update conversions, your input file must contain a reference to an existing conversion and additionally contain values for status, payout, revenue, or sale amount. This reference is almost always a transaction ID. However, if you need to update goal conversions or conversions created without a transaction ID, you can use the conversion ID instead.

The conversion ID can be found by exporting the conversion report and uniquely identifies each conversion in your network. It’s most often used when updating goals, as different goals can have the same transaction ID but different conversion ID values.

The example below shows how your file could look when updating the conversion approval status, payout, and revenue of three sessions by transaction ID. In the second record, we plan to reject the conversion and intentionally leave the payout and revenue values blank:

transaction_id,status,payout,revenue
102b3t4hj545lbgl4v9833,approved,3.25,5.5
102kjluwer0935842083g,rejected,,
1024235t9078tw987697,approved,1.00,2.00

To update using conversion IDs, the first field instead uses id as the header and contains conversion ID values.

Important: If you enter reference a transaction ID that doesn’t have an associated conversion, then that conversion is created instead. The approval status of the new conversion is based on the Approve Conversions offer tracking setting and ignores the status field of the input file. To ensure no new conversions are created with incorrect statuses, you can upload the same CSV file again.

Required Fields (include one or the other):

Field Name Description Accepted Values Example
transaction_id ID of the user session in your network Transaction ID that corresponds to an existing conversion in your network 102b3t4hj545lbgl4v9833
id ID of the conversion in your network Conversion ID that corresponds to an existing conversion in your network. Found by exporting the conversion report. 14368

Other Fields (must include at least one):

Field Name Description Accepted Values Example
status Approval status of the conversion “pending”, “approved”, or “rejected” approved
payout Amount partner earns for conversion (only for offers that do not use CPS; see below for CPS offers) Monetary value with up to two decimal places. 10.00
revenue Amount your business earns for conversion (only for offers that do not use RPS; see below for RPS offers) Monetary value with up to two decimal places. 15.00
sale_amount Amount of total sale which is important when offer payout or offer revenue is percentage of sale amount (used to set payout and revenue for CPS/RPS offers) Monetary value with up to two decimal places. 100.00
ip Advertiser IP address used to create conversion Valid IP addresses up to 15 characters (IPv6 not supported) 192.168.0.0
pixel_refer Referral URL for advertiser-side conversion pixel Any URL (http:// included) http://example.com

Exception for CPS / RPS Offers

For cost per sale (CPS) and revenue per sale (RPS) offers, include the sale amount and exclude payout and revenue. Because payout is based on sale amount for CPS offers and revenue is based on sale amount for RPS offers, those values are recalculated when the sale amount is reset.

The example below shows how your file could look when updating an offer with both CPS and RPS by transaction ID. We include the sale amount field and avoid using the payout and revenue fields. In the second record, we plan to reject the conversion and intentionally leave the sale amount value blank:

transaction_id,status,sale_amount
102b3t4hj545lbgl4v9833,approved,19.00
102kjluwer0935842083g,rejected,
1024235t9078tw987697,approved,2.00

Creating Conversions without Transaction IDs

To upload new conversions without transaction IDs, your input file must contain the partner ID, offer ID, payout, and revenue fields. Payout and revenue values can be left blank, but the headers must be in place. A common use case for creating conversions this way is to add conversions to offers with expired sessions.

The example below shows how your file could look when creating three conversions. In the second record, we plan to reject the conversion and intentionally leave the payout, revenue, and goal ID values blank:

affiliate_id,offer_id,payout,revenue,status,goal_id
100,42,2.00,4.00,approved,2
102,46,,,rejected,
114,42,2.00,4.00,approved,4

Important: If you omit the status field for a given conversion, then that conversion defaults to “approved”. This method of creating conversions ignores the Approve Conversions offer tracking setting.

Required Fields:

Field Name Description Accepted Values Example
affiliate_id ID of the partner in your network Numeric ID of the partner in your network 1000
offer_id ID of the offer in your network Numeric ID of the offer in your network 1000
payout Amount partner earns for conversion Monetary value with up to two decimal places. 10.00
revenue Amount your business earns for conversion Monetary value with up to two decimal places. 15.00

Other Fields:

Field Name Description Accepted Values Example
status Approval status of the conversion “pending”, “approved”, or “rejected” approved
goal_id ID of the goal in the offer that you want to credit the conversion for Numeric ID of the goal in your network 10
sale_amount Amount of total sale which is important when offer payout or offer revenue is percentage of sale amount Monetary value with up to two decimal places. 20.00
datetime Date and time for the conversion YYYY-MM-DD HH:MM:SS 2020-01-31 23:59:59
affiliate_manager_id ID of network employee managing the partner in TUNE Numeric ID of the network employee managing the partner 1000
advertiser_id ID of advertiser for offer in TUNE Numeric ID of the advertiser in your network 100
advertiser_manager_id ID of network employee managing the advertiser in TUNE Numeric ID of the network employee managing the advertiser 100
creative_url_id ID of the offer URL/landing page in TUNE Numeric ID of the offer URL/landing page in your network 1000
offer_file_id ID of the creative file used for the offer in TUNE Numeric ID of the creative file in your network 1000
ad_campaign_id ID of the ad campaign in TUNE Numeric ID of the ad campaign in your network 100
ad_campaign_creative_id ID of ad campaign creative in TUNE Numeric ID of the ad campaign creative in your network 1000
payout_type Method of compensation for partners (recorded as cost) “cpa_flat”, “cpa_percentage”, “cpa_both”, “cpc”, or “cpm” cpc
revenue_type Method of payment by advertiser (recorded as revenue) “cpa_flat”, “cpa_percentage”, “cpa_both”, “cpc”, or “cpm” cpc
source Traffic source passed in by partner when session was started Up to 500 characters example_affiliate_traffic_source
affiliate_click_id Partner click ID passed in by partner when session was started Up to 500 characters example_affiliate_click_id
affiliate_info1 Partner sub ID 1 passed in by partner when session was started Up to 500 characters example_affiliate_info
affiliate_info2 Partner sub ID 2 passed in by partner when session was started Up to 500 characters example_affiliate_info
affiliate_info3 Partner sub ID 3 passed in by partner when session was started Up to 500 characters example_affiliate_info
affiliate_info4 Partner sub ID 4 passed in by partner when session was started Up to 500 characters example_affiliate_info
affiliate_info5 Partner sub ID 5 passed in by partner when session was started Up to 500 characters example_affiliate_info
affiliate_unique1 Partner unique value 1 passed in by partner when session was started Up to 250 characters example_affiliate_unique
affiliate_unique2 Partner unique value 2 passed in by partner when session was started Up to 250 characters example_affiliate_unique
affiliate_unique3 Partner unique value 3 passed in by partner when session was started Up to 250 characters example_affiliate_unique
affiliate_unique4 Partner unique value 4 passed in by partner when session was started Up to 250 characters example_affiliate_unique
affiliate_unique5 Partner unique value 5 passed in by partner when session was started Up to 250 characters example_affiliate_unique
advertiser_info Advertiser sub ID passed in by advertiser on conversion Up to 500 characters example_advertiser_info
advertiser_info2 Advertiser sub ID 2 passed in by advertiser on conversion Up to 500 characters example_advertiser_info
advertiser_info3 Advertiser sub ID 3 passed in by advertiser on conversion Up to 500 characters example_advertiser_info
advertiser_info4 Advertiser sub ID 4 passed in by advertiser on conversion Up to 500 characters example_advertiser_info
advertiser_info5 Advertiser sub ID 5 passed in by advertiser on conversion Up to 500 characters example_advertiser_info
user_agent User agent for user when session was started User agent string up to 500 characters TUNE/1.0 (http://tune.com; Affiliate Tracking Software)
country_code Two-letter ISO country code for user when session was started Two-letter country code US
refer Referral URL where session was started Any URL (http:// included) http://example.com
ip Advertiser IP address used to create conversion Valid IP addresses up to 15 characters (IPv6 not supported) 192.168.0.0
is_adjustment Flag for marking the conversion status as “Adjustment” “1” (enabled) or “0” (disabled) 1
currency Three-letter ISO currency abbreviation Three-letter currency code USD
pixel_refer Referral URL for advertiser-side conversion pixel Any URL (http:// included) http://example.com
note Note for conversion detail page (accessed via the conversion report) Up to 255 characters Two (2) words.

Additional Notes

Issues with the conversion import process may be due to server-side limitations, improperly formatted input files, or specific aspects of your offers. In this section, we briefly cover those cases. For any issues not covered here, contact our support team with your CSV file and any error messages you encounter.

Pixel-Based Offers

The upload process uses server-side information for determining validity of a transaction ID. If you need to upload a transaction ID from pixel-based offers, pass the transaction ID macro in the offer URL to generate a server-side session. For more information, read our section on cookieless tracking for pixels.

Known Issues with CSVs

Details on this are covered in our Bulk Creating & Updating Offers article.

Errors in Uploading

You may be notified of errors at some point during the conversion import process. Once you start the upload, the conversion upload page can be refreshed to see task progress:

  • Queued – File is uploaded and is waiting to be processed.
  • Processing – File is being processed, and the results for the total processed count and failed count will update on each page refresh.
  • Finished – File has finished processing and the final count for lines, processed and failed lines are displayed. The employee who uploaded the conversion file receives an email notification when the process has finished.

An error prior to upload completion could be caused by one the following reasons:

  • File contains more than the maximum of 10,000 lines.
  • Headers contain invalid fields or are not formatted correctly.
  • File type is not valid. Make sure you’re uploading a comma-delimited CSV file.

Lines failing to update could be caused by one of the following issues:

  • Click session has expired or isn’t active.
  • Transaction ID is invalid or doesn’t match any recorded sessions in your network. Pixel-based sessions aren’t recorded until the transaction ID is passed in an offer URL.
  • Data for a field is invalid or is formatted incorrectly. For example, using “Pending” or “123” as a value for the status field instead of “pending”.
  • Conversions already exist for the transaction ID. The upload won’t record duplicate transaction IDs unless the Multiple Conversions offer tracking setting is enabled.