Cost Import guide

Premium

For:

Marketers Agencies

Last update: January 09, 2025 08:42

At a glance: Cost Import, part of AppsFlyer ROI360, allows advertisers to get full and accurate coverage of their marketing cost by importing CSV files via upload or email.

Overview

Use Cost Import to:

Get campaign costs of any marketing activity (mobile campaigns, influencer campaigns, CTV, and more) to AppsFlyer. This is particularly important for media sources that don't report cost via API or on the attribution link.
Retroactively overwrite and correct existing cost data.

Cost is reported via CSV files uploaded or emailed to AppsFlyer. Once AppsFlyer receives the file, the data is processed and becomes available in dashboards and reports within a few hours. This gives you a complete picture of your campaign costs and ROI.

Note:

Ad networks can import cost files for their customers if the relevant permissions are provided.
Agencies can prepare files, but advertisers must upload them.

Procedures

To use Cost Import and send cost data to AppsFlyer, you need to:

Prepare the CSV file with the cost data to send.
Send the file to AppsFlyer via either:
- Uploading it in the AppsFlyer UI.
- Email. Note: For apps on CTV, PC, and console platforms, use only this method.

See the sections that follow for detailed instructions.

Prepare CSV file with cost data

Advertisers, ad networks, and agencies can prepare the Cost Import CSV file. See sample file

To prepare the CSV file:

Follow the file schema, format, and rules detailed in the following tables.
Note: If you use Excel or Google Sheets to create the file, follow the Excel and Google Sheets formatting instructions.

CSV schema

Column name (case sensitive)	Format/remark	Example	Mandatory
date	The date the cost occurred Format: String (Best practice): YYYY-MM-DD YYYY/MM/DD MM-DD-YYYY MM/DD/YYYY Future dates not permitted Best practice: Use the same timezone as the one defined for your app in AppsFlyer. Note: Are you using Excel/Google sheets to prepare the file? Read this.	2019-05-30 2019/05/30 5-30-2019 5/30/2019 05-30-2019 05/30/2019	✓
app-id	Format: String App ID as it appears in AppsFlyer. Multiple app IDs are allowed in a single file. All app IDs need to belong to the same advertiser account.	com.app.name id12356789	✓
media-source	Format: String Media source name exactly as it appears in AppsFlyer. Note: Include the _int suffix if relevant. Only one media source per file permitted. Multiple apps for the same media source are permitted.	network_x_int	✓
campaign	Format: String Campaign name. If the campaign name appears in the ad network, the name in this file should match it (case sensitive). Don't use the same campaign name for multiple apps.	campaign_a	✓ Note: If attribution data exists with both name and ID, the CSV must contain both in order to match.
spend	Monetary cost Five digits allowed after the decimal point The value 0 (zero) is permitted Note: 1000 comma separators aren’t allowed, for example: "2,874.12". Are you using Excel/Google sheets to prepare the file? Read this.	2874.12345	✓
geo	Format: String Two-letter country code compliant with ISO 3166. Note: Ensure that you send 2 characters with no blanks. For the United Kingdom use UK, not GB.	US, CN, AU	No
currency	Format: String Three-letter currency code compliant with ISO 4217. Note: Ensure that you send three characters with no leading or trailing blanks. One currency code per app in the file allowed. Different apps can have different currency codes.	USD, GBP, EUR, JPY	No. Will default to USD if left empty.
campaign-id	Format: String	abc1234def	No. Note: If attribution data exists with both name and ID, the CSV must contain both in order to match.
adset	Format: String	my_adset_1
adset-id	Format: String	id5678ghi
ad	Format: String	my_ad_name
ad-id	Format: String	id91011jkl
site-id	Format: String Unique ID that identifies the publisher that displays the ad. Learn more	id1213mno	No
channel	Format: String	video	No
keywords	Format: String	better better you app better you online	No
agency	Format: String The agency name. The value in the af_prt parameter) Only one agency can be included in a file, and only campaigns managed by that agency can be included in the file. The agency name is mandatory per row. No blank cells are allowed in the agency column. The agency must have permission to all the apps included in the file. Only advertisers can upload the file. Agencies can't upload data. They can prepare their files and send them to the advertiser to upload.	AgencyName	No
Note: Names with non-English characters must be encoded using UTF-8.

CSV format and rules

Rule	Requirement
Prohibited characters	Fields in string format can't have `=`, `+`, `-`, or `@` as the first character. For example, `@example_campign` or `=123` are prohibited.
App owner	One advertiser (app owner) per file permitted. Multiple apps from the same advertiser account are permitted.
Filename extension	CSV Example: abc123.csv
File structure	Format: Files have a CSV format meaning that each column is separated by a comma. Header row: The first row is a header row that matches the schema Data rows: Contain the mandatory columns. Note: Ensure that there are no trailing blanks in your data. For example, [USD] (a blank follows the D should be changed to [USD]. Blank rows: Not permitted Duplicate rows having the same key: Not permitted. The key is derived from using the mandatory fields. Blank cells: Empty values are not allowed in the file. If you do not want to upload certain fields, they should not be in the file.
Advertising hierarchy	Cost must be recorded at the campaign level with other dimensions in the advertising hierarchy being optional. Any partial data that is uploaded at a lower hierarchy will override all data from the campaign level down. For example: If you import a file with campaign cost for adset 1, and separately import another file for adset 2 of the same campaign, the total cost of the campaign will be replaced and show only adset 2 data. For total campaign cost, the file you import needs to include adset 1 and adset 2.

Upload file

Advertisers and ad networks can upload Cost Import CSV files.

Prerequisites: Ad networks require Cost Import permission from the advertiser.

To upload the CSV file via the AppsFlyer UI:

In AppsFlyer, from the side menu, select Settings > Cost Import.
The Cost Import page displays.
Click + Import cost file
The Import cost window opens.
Drag the CSV file to the Import cost file window.
Processing file message displays.
If an error message displays during upload, rectify the error and repeat the relevant steps.
The Cost Import: file summary window opens.
Do one of the following:
- Abort the upload, click Cancel import.
- Complete the import process, click Import file.
  The message, All set! displays.
- If an error message displays, follow the error message instructions.
Click Import another file or Done.

Email file

Advertisers and ad networks can email Cost Import CSV files.

Prerequisites:

Advertisers:
- Sender email must be for a registered AppsFlyer user.
Ad networks:
- Sender email must be for a registered AppsFlyer user.
- Cost Import permission from the advertiser.

To send the CSV file by email:

Get the token for email import.
1. In AppsFlyer, from the side menu, select Settings > Cost Import.
2. In the upper right-hand of the page, click Token for email import.
3. Copy and save the token.
Compose the email with the following fields:
- To:adspend-upload@appsflyer.com
- CC: Users who should get a copy of the automatic feedback
- Subject: Paste the token for email import in the subject field.
- Attachment: CSV file with the data.
Send the email.
- Once the file is received and processed, a status email summarizes the details, issues, or errors found during processing. The email is sent to all parties on the submission email and to the advertiser admin. Where errors are identified, follow the error message instructions.
- You can view the status of files submitted on the Cost Import dashboard

Dashboard

The Cost Import dashboard is where you can upload files and view details of previously uploaded files.

Cost Import dashboard

To view the Cost Import dashboard, in AppsFlyer, from the side menu, select Settings > Cost Import.

Details about the information available for previously imported files are described in the following table.

Column name	Description
CSV file name	The name of the cost files imported to AppsFlyer.
Upload date	Date file was imported.
Media source	Media source included in the file.
Date range	First and last dates in the file in which ad spend occurred.
Matched rows (%)	The percentage of rows in the file where cost was matched to attribution. Learn more.
Status	The status of the imported file: Success: Action completed successfully. Cost is recorded and available in AppsFlyer dashboards and reports. Validation error: AppsFlyer system problem. Wait 10 minutes and try again. If it fails again, contact AppsFlyer support. No permissions: The token is not approved for this app. Advertisers: Ensure the app ID is correct. Ad networks: Confirm with the advertiser that they've given you Cost Import permission. Reverted: Action completed successfully. File was overwritten/replaced by other data.
Action	At the file level: If you have app permissions to all the apps contained in the file, you can: Download CSV file: This a copy of the imported CSV file. Download unmatched report for all apps in the file. See the Matched rows section of this table to learn more. At the app level: If you click a specific file, information about all Cost Imports for the app displays, from that specific file, as well as other files. If you have app permission for the app you can: Download app data. Download unmatched report for the app Revert (cancel) the Cost Import for the selected app.

Matched rows

Row matching is the process where the cost reported by import is matched with attribution data recorded in AppsFlyer. This is done using all dimension names (not IDs) available, such as media source, campaign, adset, ad, etc. If they all match, the rows are designated as is-matching=TRUE.

Cost is recorded and available in AppsFlyer dashboards and reports regardless of matched status.

The percentage of matched rows displays on the Cost Import dashboard. If unmatched rows are unexpected or the number of matched rows (%) is higher than expected:

Download the Unmatched report to investigate the cause. The Unmatched report contains a column "is-matched" which can have a value of TRUE (matched) or FALSE (unmatched) rows.
If necessary, cancel the import by reverting it.
See the Action section of this table for details.

Additional information

Using Excel or Google Sheets to prepare CSV file

When using Excel or Google Sheets to prepare the CSV file, the date and spend columns need to be formatted correctly before you save the file as a CSV file. After you save the CSV file, verify that the content is formatted correctly. Use the following guidelines to:

Format the date cells.
Format the spend cells.
Verify the content format.

Format date cells

To format date cells in Excel with the format YYYY-MM-DD:

Select the cells to be formatted.
Right-click and then select Format cells.
The format cells window opens.
Select Custom.
In the Type field, enter YYYY-MM-DD
Click OK.
The date is formatted.

Formatting spend cells

Excel usually formats value cells with a comma to separate the thousands, as shown in the following image. This format isn't suitable for Cost Import files.

To format spend cells without a 1000 comma separator:

Select the cells to be formatted.
Right-click and then select Format cells.
The format cells window opens.
Select Number.
Clear Use 1000 separator (,).
(Optional) Set the number of Decimal places. The default is 2. The maximum permitted is 5.
Click OK.
The cells are formatted correctly.

Verify content format

To verify the content format:

Use an editor to view the file.
- Windows: Notepad, Notepad++
- macOS: TextEdit
Pay special attention to the following:
- Blank spaces: Ensure that there are no leading or trailing blank spaces before or after the commas that separate the fields. In Excel, use the @trim command to remove blank spaces.
- Date: Ensure that the date cells have the format YYYY-MM-DD.
- Spend: Ensure there are no commas in the spend cells.
- Delimiters: Must be commas. If they are semi-colons:
  - This may occur when your computer's regional settings are set to a language/region that's not English, especially German.
  - The solution differs depending on your computer operating system (macOS or Windows).
  - To resolve this issue, search for the latest guidance from Microsoft or other forums. Use the following search terms: Operating system (macOS or Windows) Excel change delimiter for CSV files.

The following image contains a screenshot of the sample CSV file displayed in an editor.

Token for email import

The token for email import is used to verify that the email sender is authorized to submit the Cost Import file.

Advertiser and ad network tokens are different:

Advertiser token:
- The same token is valid for all apps in the account.
- Any account user can get the token.
Ad network token:
- The same token is used for all advertisers.

Advertisers and ad networks shouldn't share their tokens with each other!

Cost Import permissions for ad networks

Ad networks require advertiser permission per app to access Cost Import.

To grant an ad network Cost Import permission:

In AppsFlyer, the advertiser needs to go to the side menu and select Collaborate > Active Integrations.
The Integrated Partner page displays.
Select the integrated partner.
Go to the Permissions tab.
Enable Ad Network Permissions if it is not already so.
(optional) Add account users.
Enable Use Cost Import.
Click Save permissions.

Troubleshooting, traits, and limitations

Error messages and solutions

The following table lists all possible Cost Import error messages and corresponding solutions.

Error message	Description	Solution
None of the app IDs provided in the file exist in AppsFlyer. Please verify the correctness of app IDs.	App ID does not exist in the account.	Change app ID and resubmit.
Line [line name] has the wrong number of columns. Expected [number] columns, received [number] columns.	All columns in the file must have a value.	Change the values populated in the file based on the headers you defined.
Missing 'media-source' in file header.	File header is missing media- source. The column name needs to be exactly as it is in the scheme.	Add media-source as a header name.
The file can contain only one media source. Multiple media sources encountered in the file: [number of media sources].	Cannot upload a file with more than one media source.	Split the upload into one file for each media source.
The value provided [value] for [field] is not a valid value for this column.	Data format in the column is incorrect. For example, the date is dd-mm-yy instead of yyyy-mm-dd.	Correct the format and resubmit.
Multiple currencies identified for the app. Please use a single currency for each app in the file. Encountered currencies: %number of currencies%.	Only one currency can be used for an app.	Use one currency in the upload and resubmit.
The following columns in the file header are not supported: [file headers]	File header does not match the scheme. Meaning, the column name needs to be exactly as it is in the scheme.	Remove the unsupported columns and resubmit.
Missing required columns in file header: [file headers]	File header is missing a mandatory column.	Add the missing column and its values and resubmit.
The app contains a future date: [date]	Future dates are not allowed.	Correct the date to today's date or earlier, and resubmit.
The file is empty. There is no data to process.	The file is empty.	Populate data in the file and resubmit.
The following two rows conflict due to identical dimensions. Please provide a single row of spend per set of dimensions. [conflicting rows]	There is more than one row with the same key (mandatory) fields.	Remove the duplicate rows and resubmit.
The file can contain data only from a single advertiser account. Different advertisers encountered in file: [advertiser names]	For partners, an upload cannot be for more than one advertiser.	Split the upload into one file per advertiser.
The app [app ID] doesn't exist in the account. Please verify the app ID.	App ID does not exist.	Correct the app ID and resubmit.
Geo (country) code was not found for app [app ID]. Use an ISO 3166 2-letter code	Geo does not exist.	Correct the geo and resubmit.
Currency code was not found for app [app ID]. Use an ISO 4217 3-letter code.	Currency does not exist	Change the currency to a valid currency and resubmit.
There were validation errors for one or more apps in the file. Please review the file information for more details.	There is more than one error in the file.	Download the file and review for errors.
There was an internal error processing the file, please try uploading it again.	Backend issue processing the file. Typically a temporary issue.	Wait 1 hour and upload again.

Traits and limitations

Trait	Remarks
Ad networks	Supported. Exceptions: Meta Ads X Ads ASA
Agencies	Agencies can't upload data. They can prepare their files and send them to the advertiser to upload. The CSV files must contain an Agency column with the agency name (the agency name is the value in the af_prt parameter). See CSV schema
Agency transparency	Not supported
App-specific timezone	Supported
App-specific currency	Supported. Campaign costs are converted to the app-specific currency.
Campaign name	The same campaign name can't be used for multiple apps, or the cost of one app will apply to both.
Field names	If field names in the campaign hierarchy do not match the field names as they appear in the attribution data, they will be counted separately. For example, if the campaign names do not match, then even though the campaign IDs are the same, they will be counted as different campaigns.
File size	When uploading a CSV Cost Import file the size limit is: Via AppsFlyer dashboard: 2 MB Via email: 5 MB per file
Organic data	Supported
Non-organic data	Supported
Data freshness	Ad spend
Historical data	Supported. Cost reported can be reverted, and corrected data submitted, for up to 90 days.
Retargeting	Not supported.
Account user access	Not available for users with geo or media source restrictions.