Upload Options

Our application supports three techniques to upload revenue data into the application.

1. Copy/paste directly into the interface.
    
2. Manually select a tab delimited file.
    
3. Drop the revenue file onto the FTP server

Uploading Revenue via FTP

If you are planning to use the FTP option, initially test your upload manually with a file. Once you are comfortable that the revenue is uploading correctly (see Verifying Revenue ), then proceed with configuring data to be sent via FTP. Our application's FTP server can be used to perform periodic "drops" of your revenue files. The credentials to use the FTP server are as follows:
 

• Server: integration.marinsoftware.com
• Username: your application username
• Password: your application password

We recommend creating a specific FTP user account for uploading revenue via FTP. This can be created by clicking into the Admin section and then clicking on the Users sub-tab. You can then click the Create button to create a new user. Be sure to check the radio box for FTP-only user. When all settings are in place, go ahead and click Save. 

If you try to upload revenue without having an FTP-only user, you will get an error pertaining to invalid credentials. 

Note: We do not recommend setting an existing user to be an FTP-only user, as doing so will lock your username and password out from the Marin platform. 

Revenue File Naming Conventions

Marin’s revenue platform offers great flexibility with how youi can load your data; it does this via offering different modes. This feature enables the platform to support multiple revenue sources for reporting and optimization, increasingly important as the ad measurement industry is more fractured than ever. This means we can support a mix of revenue from the publisher platforms, Marin’s own native, as well as 3rd party measurement tools for your account if required.

Below we'll explains the different modes and how to make use of them. The prefix of the filename (uploaded via FTP) will control how the revenue data is loaded into Marin's reporting. Note that if this is difficult to implement, you can request Marin to select the mode on the platform side by reaching out to our customer support team.

Add Revenue: bulkrevenueadd_FILENAME.txt (Simply adds the revenue and conversion values to the existing data for that date)

Negate Revenue: bulkrevenuenegate_FILENAME.txt (Subtracts the revenue and conversion values from the existing data for that date, down to 0)

Overwrite Revenue: bulkrevenueoverwrite_FILENAME.txt (Overwrites any existing values for the date/keyword/creative/placement ID combo)

Clear and Overwrite Revenue: bulkrevenueclearandoverwrite_FILENAME.txt (Clears all rev/conv data for the date and replaces with the new values)

Clear by Conversion Type and Overwrite Revenue: bulkrevenueclearbyconvtypedateandoverwrite_FILENAME.txt (Clear all revenue or conversion data for all object types which match the below conditions and replace with the new values). Conditions:

• Date range mentioned in the revenue file AND

• Conversion types* (CT) mentioned in the revenue file headers

*If the Marin “total” conversion type is included (i.e. Conversions, Revenue columns), or if any of the Conversion Types included is set to add to total, “totals” data will also be cleared

Clear by Conversion Type & PCA and Overwrite Revenue: bulkrevenueclearbypcaconvtypedateandoverwrite_PCAEXTIDS_xxx_SDITXEACP_FILENAME.txt (Clear all revenue or conversion data for all object types which match the below and replace with the new values). Conditions:

• Date range mentioned in the revenue file AND

• Conversion type** (CT) mentioned in the revenue file headers AND

• PCA ID (single) mentioned in the revenue file name (replace the xxx)

**if the Marin “total” conversion type is included (i.e. Conversions, Revenue column’s), or if any of the Conversion Types included is set to add to total, “totals” data will also be cleared.

This mode does not support Cross Client Attribution (CCA).

File Format

The accepted file formats are .txt and .csv. These should either be comma separated or tab delimited.

The following represents the columns that comprise a revenue upload file. The heading row MUST exist in the file to be uploaded in order to map the data correctly within the application:

Date [Keyword ID] [Creative ID] [Keyword] [Match Type] [Placement] [Device] [Product ID] [Conversions] [Revenue] [Currency] [SL ID] [Conversion Type] [Comments] [Group ID] [Target IDs] [Audience Target ID]

For more information about the [Keyword_ID] and [Creative_ID] headers please refer to the article Understanding The Platform Creative ID, Publisher ID And Unique ID.

Date Format Support

When uploading revenue, you can specify the dates both in your local format and in a locale-independent ISO format. For example, July 8 2010 can be 7/8/2010 in US locale, or 2010-07-08 in ISO format. For ISO dates, both YYYY-MM-DD and YYYYMMDD formats are allowed.

Match Type Support

The application supports a Match Type column in the revenue upload files that maps directly to the specific keyword match type as reported by the publisher.

Here's an example of a revenue upload file with all the known match types:

This allows you to use the data coming directly from the publishers with creative-level URLs in your setup in the application.

Text Insertion Support by Publisher

Insertion using ValueTrack parameters varies by publisher. Accepted values are specified below:

Other Marin Valuetracking Parameters

Marin expects publisher macros to be used for a number of the revenue upload files:

• [Group ID] : The ad group ID

  • Google {adgroupid}

  • Microsoft {AdGroupId}…

  • Marin has an macro [ext_group_id] but advise to always use publisher macros where possible.

• [Target IDs] : The ID of the keyword ("kwd"), remarketing or audience list ("aud"), product partition ("pla") that triggered the ad.

  • Google {targetid}

  • Microsoft …{TargetId}

• [Keyword] : The keyword that matches the search query

  • Google {keyword}

  • Microsoft {keyword}

• [Creative ID] : A unique ID for your ad

  • Google {creative}

  • Microsoft {AdId}

Add vs. Overwrite

This section covers some best practices to keep in mind when selecting modes, including examples. 

Please keep in mind, you need to include at least one valid row; it can be attributed to the object or the group successfully in the revenue file to have revenue processing working, since the date is part of the mandatory condition to clear or update the revenue data. If nothing is attributed throughout the revenue file, the job would fail directly without touching the data.

Add to Existing Revenue

Using the "Add to existing revenue" option, new revenue will be added to existing revenue for a keyword on a given day. Or, if you need to credit an order, you could upload a negative conversion and a negative revenue value in “Add” mode. This would in effect remove the sale from your numbers, however, we recommend removing the sale in “Negate” mode.

Negate to Existing Revenue

Using the “Negate to existing revenue” option, new revenue will be negated to existing revenue. If you need to credit an order you could upload a positive conversion and positive revenue value in “Negate” mode. This mode would minus value down to 0 instead of negative value.

Overwrite Revenue

When using the "Overwrite existing revenue" option revenue for a keyword on a given day will be overwritten with the newly uploaded data. An example of choosing overwrite is if you are always uploading all your revenue data over a period of time.

Please note that the “Overwrite” function will only modify keyword IDs that are included in the “Overwrite” upload sheet. It will not change or zero out any keywords that were not included. Finally, in most E-Commerce scenarios, revenue add is the option used.

Clear and overwrite all data for specified dates

All revenue and conversion data will be overwritten for all dates included in the revenue upload file and replaced with the values in the revenue upload. If there is a single keyword. This mode should be used if you are uploading all revenue/conversion information for the selected dates.Note that the overwrite will only occur for dates included in the upload file. For example, if the file includes conversions on 1/1 and 1/3, but not 1/2, the data on 1/2 will not be affected.

* If revenue is attributed across clients, the action of clearing the objects revenue data will only happen in the upload clients with this mode. While the action of overwriting revenue data will happen both in upload clients and CCA associated clients. That is because clear by date only is a strong scope to clear, which is considered a bit dangerous.

Clear and overwrite all data for specified dates and specified conversion type

The difference between this and “Clear and overwrite” is additionally limiting data zero out to those of the conversion types included in the revenue upload file. For example, if the file includes conversion type 123, but not includes conversion type 456, the data of conversion type 456 will not be affected. This mode should be used if you are uploading all marin account revenue/conversion information specific to some of the conversion types for the selected dates. For example, you are using different publisher trackings and want to compare them in different conversion events.

* If revenue is attributed across clients, both the action of clearing the objects revenue data and the action of overwriting revenue data will happen both in upload clients and cca associated clients. 

Clear and overwrite all data for specified dates and specified conversion type under single PCA

The difference between this and above is that additionally limiting data zero out under a single PCA provided in the revenue upload file name. This mode should be used if you are uploading all revenue/conversion information specific to some of the conversion types for the selected dates for a single PCA, and don’t want to impact other PCA data which share the same conversion types. For example, you are using publisher trackings for multiple PCAs and each pca data result coming in at a different time.

* This mode is not supported to attribute across clients (CCA).

Concurrent Revenue Uploads

Example of a valid revenue file

• Revenue for pair Creative by pub id and Keyword by keyword text + match type

Date     Creative ID     Keyword  Match Type     Revenue     Conversions     Currency     Group ID

2009/12/23    1456    key1    broad    12.00  1    USD    87654123

2009/12/24     1456     key2     phrase     2.62     1     GBP     87654123

• Revenue for pair Creative by pub id and Keyword / Product Target by pub id

Date     Creative ID     Target IDs     Revenue     Conversions     Currency     Group ID

2009/12/23     1456     kwd-1234     12.00     1     USD     87654123

2009/12/24     3321     pla-431433     2.62     1     GBP     87653142

• Revenue for pair Creative by pub id and objects by tracking value

Date     Creative ID     Keyword ID     Revenue     Conversions     Currency     Group ID

2009/12/23     1456     53a381d     12.00     1     USD     87654123

2009/12/24     1455     53a381d     2.62 1     GBP     87654123

Note the following in the above example:

• We recommend the date format to be ISO date format (yyyy-mm-dd), but it can also be specific to your locale setting.

• Group ID is always recommended to be included and value provided in Revenue File.

• Revenue is optional if simply uploading conversions. Do not include a revenue column in the header or the data set.
• Either tab delimited text files or CSV files can be used.
• Currency is the 3 letter ISO code which denotes the currency of the revenue captured.
• For details on multi-conversion revenue upload, see multi-conversion type section.