Welcome!
Welcome to the Marin Software Support Center. We're glad you're here. Here's what you can look forward to:
  • Real-time search so you can find what you need faster than ever.
  • Easy-to-follow video guides for our most popular articles.
  • Interactive simulations and Live Screenshots to make learning easy.
  • Regular content updates to ensure every word you read is accurate and up-to-date.

Revenue and Conversion Tracking

Home > English > Revenue and Conversion Tracking > Revenue Upload > How To Articles: Revenue Upload > Revenue Upload Methods Advanced Guide

Revenue Upload Methods Advanced Guide

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

Note

  • When performing bulk edits, please delete any unused column headers prior to uploading or copy/pasting. Blank columns will result in the corresponding field data being overwritten with blanks.
  • Make sure your revenue upload file only contains revenue information for one account. If you have multiple accounts to update, make a separate upload document for each account. An exception to this is if you are enabled for Cross Client Attribution. Please contact your Platform Representative for more information on this.
  • The application supports either a tab-delimited (TSV) or comma-separated (CSV) revenue files.

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).

Important Notes

  • The file name can be anything you want, but it must come after the first "_" character. This example demonstrates an acceptable file name: bulkrevenuadd_marin_data_011508.txt
  • During “Clear by Conversion Type & PCA and Overwrite” revenue modes, PCA ID in the revenue file name is MANDATORY. The PCA should be linked in the uploaded client, so cross client upload is not supported. PCA ID is usually publisher account id that can identify the unique account. We suggest trying this ahead of time before use in scale for every PCA. We'll list some example PCA IDs below.

    • Google: 721-300-4232

    • Microsoft: F09871FB

    • Amazon: 4299345230893267

If uploading Revenue Upload by Order ID (RUBOID) files into FTP directory there is usually additional automation logic within Marin to process the file and upload in an add/overwrite mode rather than using the file naming convention. Please consult with your account representative to confirm further details.

If your job is successful, the mode you use will display in the Activity Log for this job, such as what you can see in the screenshot below. 

rdn1.png

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:

Date

Keyword ID

Creative ID

Match Type

Conversions

Revenue

Keyword

2017-06-01

kwid1234

crid5678

exact

1

10

keyword 1

2017-06-01

kwid1234 crid5679 broad 2 11 keyword 2

2017-06-01

kwid1234 crid5680 phrase 3 12 keyword 3

2017-06-01

kwid1234 crid5681 e 4 13 keyword 4

2017-06-01

kwid1234 crid5682 b 5 14 keyword 5

2017-06-01

kwid1234 crid5683 p 6 15 keyword 6

2017-06-01

kwid1234 crid5684 std 7 16 keyword 7

2017-06-01

kwid1234 crid5685 adv 8 17 keyword 8

2017-06-01

kwid1234 crid5686 standard 9 18 keyword 9

2017-06-01

kwid1234 crid5687 advanced 10 19 keyword 10

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:

Match Types -  {matchtype}

  • Marin internal insertion using [matchtype]

    • exact

    • broad

    • phrase

  • Google, Yahoo Japan and Yahoo Gemini

    • e (exact)

    • b (broad)

    • p (phrase)

  • Microsoft - Marin supports Microsoft's {BidMatchType} values in the Match Type column as listed below. {BidMatchType} should be used whenever possible in Microsoft URLs (as opposed to {MatchType} which returns delivered Match Type).

    • bb (broad)

    • bp (phrase)

    • be (exact)

    • bc (content)

  • Baidu

    • 1 (exact)

    • 2 (broad)

    • 3 (phrase)
       


Device - {device}

  • Google, Microsoft, and Yahoo Japan

    • m (mobile)

    • t (tablet)

    • c (computer)

  • Specific to Gemini

    • p (mobile)
       


Network - {network}

  • Google

    • s (search)

    • c (content)

  • Baidu

    • 1 (search)  

    • 2 (content)


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

If you submit multiple revenue files per day, their processing can overlap and potentially lead to unexpected results. Files are processed as they are received and multiple files can be processed simultaneously. As a result, if two revenue files are loading data for the same keyword, creative, or placement during concurrent processing, the file processed second can end up overwriting or clearing data loaded by the first file. For example, if you submit two files, one in Add mode and one in Overwrite Mode (e.g. from different revenue integrations), and the add file is processed first, the overwrite file could then end up overwriting the revenue data added by the first file.

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.

Uploading to a specific conversion type

To upload revenue and conversions to a specified Conversion Type, the [Name Conv] and [Name Rev] can be added to the uploads. Once a conversion type is created, you can see the exact naming convention for your column headers by navigating to the Upload Revenue page here: https://app.marinsoftware.com/keywords/addRevenue and finding the conversion type name in the box.

Below is a sample revenue file for uploading to a conversion type:

Date [Keyword ID] [Conversions] [Revenue] [Conversion1 Conv] [Conversion2 Rev]
2013-03-01 abcdef 35 2456 35 2456

Additional Information

For more information on understanding the attribution logic of loaded revenue files (which may also provide details on why your revenue uploads are not processing correctly), please see the following Help article: An Overview of Revenue and Conversion Tracking

Last modified

Tags

Classifications

This page has no classifications.

 

wiki.page("Internal/Mindtouch_Launch_Sandbox/js.cookie.js")