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.
Deprecation notice: We are deprecating Conversion ID (corresponding to the id header) and migrating to TUNE Event ID (corresponding to the tune_event_id header). Throughout the document you will see TUNE Event ID (tune_event_id) in lieu of Conversion ID (id).
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 TUNE Event ID (formerly Conversion ID) instead.
The TUNE Event 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 TUNE Event 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 TUNE Event IDs, the first field instead uses tune_event_id as the header and contains TUNE Event ID values. We no longer support Conversion ID (with id as a header), according to the Deprecation notice above. TUNE Event ID now replaces Conversion ID.
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 |
| tune_event_id
(id is deprecated) |
ID of the conversion in your network | ID that corresponds to an existing conversion in your network. Found by exporting the conversion report. | b6d33f9e-b9fe-4f07-b8c5-fdf1405ebeb5 |
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.