How can we help you?
Our application supports three techniques to upload revenue data into the application.
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:
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.
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).
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.
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.
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.
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.
Insertion using ValueTrack parameters varies by publisher. Accepted values are specified below:
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)
Google, Microsoft, and Yahoo Japan
m (mobile)
t (tablet)
c (computer)
Specific to Gemini
p (mobile)
s (search)
c (content)
Baidu
1 (search)
2 (content)
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}
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).
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:
Group ID is always recommended to be included and value provided in Revenue File.
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 |
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