Bulk Upload

Google Ads scripts allows you to make bulk changes to your account by uploading data in CSV format. You can upload data from a CSV file from Google Drive, a Google spreadsheet, a Microsoft Excel spreadsheet, or construct a bulk upload request in your script at runtime. This guide explains how to use this feature in your scripts.

Benefits

Bulk upload provides the following benefits:

  • Utilize new features that may not yet be in Google Ads scripts.
  • Easier to transform reports data or make changes to entities.
  • Higher limits, both for quantities and time. Bulk upload limits are independent of the scripts that trigger them.

What operations are supported?

Google Ads scripts currently support the following operations for bulk uploads:

  • Campaign management: You can create, edit or delete campaigns, ad groups, keywords and text ads using bulk upload. You can also edit existing ad group criteria, ads and product groups.
  • Offline conversions: You can upload offline conversions to your account using bulk uploads.

Usage

Create bulk upload from Google Drive

The simplest way to use the bulk upload feature is to upload a CSV file in Google Drive, and upload that file into Google Ads using Google Ads scripts. This can be done as follows:

var file = DriveApp.getFilesByName("BulkCampaignUpload.csv")
    .next();
var upload = AdsApp.bulkUploads().newFileUpload(file);
upload.forCampaignManagement();
upload.preview();

This will create a bulk upload preview entry in your account. You can see this by navigating to Bulk operations > Bulk uploads in your account.

You can click the Preview link to view the changes.

To apply the changes to your account, click the Apply changes button on the details page. If the uploaded file has errors, or if you don’t want to make the changes, then click the Discard preview button to discard the changes.

Once you have verified your script logic to work correctly, you can skip the preview stage and apply the changes directly from your script. This can be done by calling the apply() method of the bulk upload instance, instead of the preview() method.

Create bulk upload from reports

Bulk upload can also be created from a Google Ads AWQL report. (Reports using GAQL and the Google Ads API do not produce the correct headers.) The following code snippet pauses all campaigns that spent more than $1000 this month.

// Run a report to fetch all campaigns that spent more than $1000
// last month.
var query = "SELECT CampaignId, CampaignName, CampaignStatus, Amount " +
    "FROM CAMPAIGN_PERFORMANCE_REPORT " +
    "WHERE Amount > 1000000000 " +
    "DURING THIS_MONTH";
var report = AdsApp.report(query);

// Create an upload with the report columns.
var upload = AdsApp.bulkUploads().newCsvUpload([
    report.getColumnHeader("CampaignId").getBulkUploadColumnName(),
    report.getColumnHeader("CampaignName").getBulkUploadColumnName(),
    report.getColumnHeader("CampaignStatus").getBulkUploadColumnName()]);
upload.forCampaignManagement();

var rows = report.rows();
while (rows.hasNext()) {
  var row = rows.next();
  // Pause the campaigns.
  row.CampaignStatus = "paused";

  // Convert the report row into an upload row.
  upload.append(row.formatForUpload());
}

// Use upload.apply() to make changes without previewing.
upload.preview();

Create bulk upload from scratch

You can create a bulk upload job from scratch as follows:

var columns = [
   "Campaign", "Budget", "Bid Strategy type", "Campaign type"
];

var upload = AdsApp.bulkUploads().newCsvUpload(columns);

upload.append({
   "Campaign": "Test Campaign 1",
   "Budget": 2.34,
   "Bid Strategy type": "cpc",
   "Campaign type": "Search Only"
});
upload.forCampaignManagement();
upload.preview();

Set monetary unit

By default, the money amounts in bulk uploads are interpreted as the actual currency amount. If you prefer using micros, you can set the moneyInMicros option to true when creating the upload job (ex. €2.34 would be entered as 2340000).

var upload = AdsApp.bulkUploads().newCsvUpload(columns,
    {moneyInMicros: true});

Set file locale

By default, the csv file contents are interpreted in US English locale (en_US). You can specify a different locale using the fileLocale option, as shown below:

var upload = AdsApp.bulkUploads().newCsvUpload(columns,
    {fileLocale: "fr_FR"});

When you specify a locale, you can provide the column headers either in en_US locale, or in the locale you specify in the fileLocale property.

Set time zone

By default, the time entries in the file are interpreted in PST. You can specify a different time zone using the timeZone option, as shown below:

var upload = AdsApp.bulkUploads().newCsvUpload(columns,
    {timeZone: "-0800"});

Setting a time zone can be useful when uploading offline conversions.

Spreadsheet templates for bulk upload

The easiest way to get a spreadsheet template for a bulk upload is from the Google Ads UI.

  • Sign in to your Google Ads account.
  • Select a campaign.
  • Click the Keywords, Ads, Ad groups, or Campaigns tab (depending on the type of edits you'd like to make).
  • From the Edit menu, press the "Download report" button.
  • Select a format for your spreadsheet and click Download.

You can programmatically retrieve these columns using the AdsApp.reports() method as follows:

var report = AdsApp.report("SELECT CampaignName, CampaignStatus " +
    "FROM CAMPAIGN_PERFORMANCE_REPORT " +
    "DURING TODAY");
Logger.log("%s, %s",
    report.getColumnHeader("CampaignName").getBulkUploadColumnName(),
    report.getColumnHeader("CampaignStatus").getBulkUploadColumnName()
);

You can also refer to the bulk upload entities reference page for details.

Code snippets

Check out our code snippets page for more examples on using this feature.