Upload data using a CSV file

If you are using a third-party tracking system, CRM, or internal reporting tool that is not directly integrated with TheOptimizer via API, you can still bring your conversion and revenue data into the platform by uploading a CSV file. Once uploaded, this data is treated exactly like data pulled from an integrated tracker — it appears in your dashboards, feeds into calculated metrics like ROI and CPA, and can be used by your automation rules to make decisions.

This article covers everything you need to know: when CSV upload is useful, how to prepare your file, what each column means, and how to handle common scenarios across Facebook, TikTok, and Native traffic sources.

In This Article

1. When to Use CSV Upload
2. Where to Find It
3. Download the CSV Template
4. How the CSV Works — Key Concepts
5. CSV Column Reference
6. Examples by Platform
7. Google Sheets Integration — Automated Alternative
8. Tips and Common Mistakes

1. When to Use CSV Upload

The most common scenarios where a CSV upload is the right solution:

Delayed or confirmed revenue. You are running search feed arbitrage campaigns (Tonic, Sedo, DomainActive, System1, etc.) and the revenue is only confirmed 24–36 hours after the click. You need to upload the confirmed numbers once they become available so your rules and reports reflect actual performance — not estimates.

Unsupported tracker or CRM. Your tracking platform is not one of the 15+ systems TheOptimizer integrates with via API. Rather than going without tracker data, you export a report from your tracker and upload it as a CSV.

Manual reconciliation. Conversions were not posted to your tracker in real time — delayed postbacks, server issues, or manual entry workflows. A CSV upload lets you backfill the missing data so your historical reports and rule evaluations are accurate.

Internal reporting systems. You track conversions in an internal database, a BI tool, or a spreadsheet. Exporting to CSV and uploading is the simplest way to get that data into TheOptimizer without building an API integration.

2. Where to Find It

Go to Manual Stats Update in the left-hand menu, then click Upload CSV File.

The Manual Stats Update page supports two workflows: pulling data on demand from a connected tracker (using the dropdowns at the top), and uploading a CSV file. This article covers the CSV upload path.

3. Download the CSV Template

TheOptimizer provides a ready-made CSV template that contains all supported columns with the correct header names. Always start from this template — if column names don't match exactly, the upload will fail.

Download the CSV Template (Google Sheets)

Make a copy of the template into your own Google Drive, fill in the data you need, then export it as a .csv  file and upload it to TheOptimizer.

4. How the CSV Works — Key Concepts

One row = one entity on one date. Each row updates the data for a single entity (a campaign, an ad set, an ad group, an ad, a widget, etc.) for a single date. If you want to update campaign-level revenue for three days, you need three rows — one per day.

Rows are scoped to the entity type in that row. If you enter a row with Type=campaign  and TrafficSourceCampaignId=12345 , the revenue in that row will only be updated at the campaign level for campaign 12345. Ads, ad sets, or other placements inside that campaign will not be updated. You need separate rows for each entity level you want to update.

You can mix entity types in a single file. A single CSV can contain rows for campaigns, ad sets, ad groups, ads, widgets, sections, and domains — all in one upload. The Type  column tells TheOptimizer how to interpret each row.

Data columns are additive — use only what you need. The template contains columns for tracker data (TrackerClicks, TrackerConversions, TrackerRevenue), traffic source data (TrafficSourceImpressions, TrafficSourceClicks, TrafficSourceConversions, Cost, TrafficSourceRevenue), and publisher/search feed data (PublisherClicks, PublisherRevenue, PublisherConversions). You only need to fill in the columns that are relevant to your upload. Leave everything else empty.

After upload, you will receive an email with details about the upload process, including any errors that were encountered (e.g., unrecognised campaign IDs, invalid dates, or formatting issues).

5. CSV Column Reference

Required Columns (always needed)

Entity ID Columns (use the one that matches your Type)

Special Column

Data Columns (fill in only what you are uploading)

6. Examples by Platform

Facebook — Upload Tracker Revenue for Campaigns

You are running Facebook campaigns tracked by an internal CRM. You want to upload yesterday's confirmed revenue at the campaign level.

All other columns are left empty. The campaign IDs are the Facebook campaign IDs as they appear in Ads Manager and in TheOptimizer.

Facebook — Upload Revenue for Individual Ads

If you want revenue data to appear at the ad level (not just campaign level), you need separate rows with Type=content  and the ad ID.

Facebook — Upload Revenue for Ad Sets

TikTok — Upload Revenue for Campaigns and Ad Groups

TikTok uses "ad groups" instead of "ad sets". Use Type=campaign  for campaign-level data and Type=adgroup  for ad-group-level data.

TikTok — Upload Revenue for Individual Ads

Native (Taboola, Outbrain, etc.) — Upload Revenue with Widget Data

Native traffic sources have additional entity types like widgets, sites, sections, and domains. A common use case is uploading search feed revenue broken down by widget.

Note that for search feed data at the widget level, the TrackerCampaignId  is required — it tells TheOptimizer which tracker campaign to associate the publisher data with.

Mixing Entity Types in One File

You can combine all of the above in a single CSV. Each row is processed independently based on its Type  value.

7. Google Sheets Integration — Automated Alternative

If you find yourself uploading a CSV every day — for example, because you are reconciling confirmed search feed revenue each morning — consider using the Google Sheets integration instead. It uses the same column format as the CSV template, but TheOptimizer pulls the data from your Google Sheet automatically every 30 minutes. You just keep the spreadsheet up to date, and TheOptimizer handles the rest.

How to Set It Up

1. Go to the Account Wizard page and select the traffic source account you want to connect.
2. Click Add New in the tracker step and select Google Sheets from the tracking platform dropdown.
3. Clone the Google Sheets template into your own Google Drive: Get a Copy of the Template
4. Share your Google Sheet with TheOptimizer's service account by adding this email as a viewer: [email protected]
5. Paste the Google Sheet URL into TheOptimizer, select your currency, and save.

Once connected, TheOptimizer will pull data from your Google Sheet every 30 minutes. The column format and naming rules are identical to the CSV template — so if you've already been preparing CSV files, you can use the same structure.

8. Tips and Common Mistakes

Always use the template. Column names must match exactly — including capitalisation. TrackerRevenue  works; tracker_revenue , Tracker Revenue , or Revenue  will not. Download the template and work from it to avoid formatting issues.

Use yyyy-mm-dd  for dates. The date format must be 2026-04-13 , not 04/13/2026  or 13-Apr-2026 . If your spreadsheet application auto-formats dates into a different style, format the Date column as plain text before exporting.

Campaign IDs must match exactly. The TrafficSourceCampaignId  must be the ID as it appears in TheOptimizer and on the traffic source — not a tracker campaign ID or an internal reference number. If an ID doesn't match, that row will be skipped and reported as an error in the confirmation email.

One row updates one entity on one date. If you want to update both the campaign level and the ad level for the same campaign on the same day, you need separate rows — one with Type=campaign  and one (or more) with Type=content . The campaign-level row does not cascade down to ads.

Leave unused columns empty — don't enter zero. An empty cell means "no data to upload for this metric". A zero means "the value is zero" and will overwrite whatever is currently stored. If you accidentally fill cost or revenue columns with 0 , you'll wipe out that day's data for those entities.

Check your confirmation email. After every upload, TheOptimizer sends an email summarising what was processed and any errors. If rows were skipped, the email will tell you why — usually an unrecognised campaign ID or a formatting issue in one of the columns.

Use the Google Sheets integration for recurring uploads. If you are uploading the same type of data every day (e.g., confirmed search feed revenue), the one-time setup of the Google Sheets integration will save you a daily manual step and ensure data is always current.