Importing Conversions

You can make use of the AdWords API to upload offline conversions back into AdWords. This feature gives you more flexibility in associating clicks with conversions; for example, you can track ads that led to sales made in the offline world such as over the phone or via a sales rep. In this guide, we show you how to use the AdWords API to construct a feed for importing your offline conversions.

Setup

The first step is to create import conversion types. This needs to be done for each unique conversion "classification" and can be accomplished using the AdWords UI or through code:

UploadConversion uploadConversion = new UploadConversion();
// Set an appropriate category. This field is optional, and will be set to
// DEFAULT if not mentioned.
uploadConversion.setCategory(ConversionTrackerCategory.LEAD);
uploadConversion.setName(conversionName);
uploadConversion.setViewthroughLookbackWindow(30);
uploadConversion.setCtcLookbackWindow(90);

// Optional: Set the default currency code to use for conversions
// that do not specify a conversion currency. This must be an ISO 4217
// 3-character currency code such as "EUR" or "USD".
// If this field is not set on this UploadConversion, AdWords will use
// the account's currency.
uploadConversion.setDefaultRevenueCurrencyCode("EUR");

// Optional: Set the default revenue value to use for conversions
// that do not specify a conversion value. Note that this value
// should NOT be in micros.
uploadConversion.setDefaultRevenueValue(2.50);

ConversionTrackerOperation uploadConversionOperation = new
    ConversionTrackerOperation();
uploadConversionOperation.setOperator(Operator.ADD);
uploadConversionOperation.setOperand(uploadConversion);

ConversionTrackerReturnValue conversionTrackerReturnValue =
    conversionTrackerService.mutate(
        new ConversionTrackerOperation[] {uploadConversionOperation});

In the above snippet, we create an UploadConversion object using the ConversionTrackerService. The given conversionName must be unique and will be used to identify this conversion event.

After creating your import conversion types, proceed to enable your website and lead tracking system to capture and store the GCLID, the unique ID that AdWords provides for every click that comes to your website from an AdWords ad. You'll also need to enable auto-tagging so your website will start receiving the GCLID as a URL parameter. For more details about these steps, visit the Tracking Offline Conversions help center.

Setup needs to be done only once, whereas the upload process can be repeated as often as required.

Uploading offline conversions

Once you've created the UploadConversion object, you need to associate your offline conversions with it by passing the GCLID, conversion time (with Timezone ID), conversion name, and optionally the conversion value and conversion currency to OfflineConversionFeedService:

List<OfflineConversionFeed> conversions = Lists.newArrayList();

// Offline conversion #1
OfflineConversionFeed conversion1 = new OfflineConversionFeed();
conversion1.setConversionName(conversionName1);
conversion1.setConversionTime(conversionTime1); // string format: "yyyyMMdd HHmmss tz"
conversion1.setGoogleClickId(gclId1);

// Optional: Set the conversion value.
conversion1.setConversionValue(conversionValue1);

// Optional: Set the conversion currency to an ISO 4217 3-character currency code
// such as "EUR" or "USD". If this field is not set, then AdWords will assume
// the conversion's value is in the default currency of the tracker.
conversion1.setConversionCurrencyCode(conversionCurrency1);

conversions.add(conversion1);

// Offline conversion #2
OfflineConversionFeed conversion2 = new OfflineConversionFeed();
conversion2.setConversionName(conversionName2);
conversion2.setConversionTime(conversionTime2);
conversion2.setGoogleClickId(gclId2);
conversion2.setConversionValue(conversionValue2);
conversion2.setConversionCurrencyCode(conversionCurrency2);

conversions.add(conversion2);

// Add additional conversions to the conversions list...

List<OfflineConversionFeedOperation> conversionOperations = Lists.newArrayList();
for (OfflineConversionFeed conversion : conversions) {
  OfflineConversionFeedOperation offlineConversionOperation = new OfflineConversionFeedOperation();
  offlineConversionOperation.setOperator(Operator.ADD);
  offlineConversionOperation.setOperand(conversion);

  conversionOperations.add(offlineConversionOperation);
}

OfflineConversionFeedReturnValue offlineConversionReturnValue = offlineConversionFeedService
    .mutate(conversionOperations.toArray(
        new OfflineConversionFeedOperation[conversionOperations.size()]));

Validation rules

The following conditions must be met for you to successfully upload a given OfflineConversionFeed:

• In order to avoid an OfflineConversionError.INVALID_CONVERSION_TYPE error, the conversionName must refer to an UploadConversion where:

  • The UploadConversion had a status of ENABLED at the time of the click.

  • The UploadConversion existed in the effective conversion account of the click's AdWords account at the time of the click. If the account was not using cross-account conversion tracking at the time of the click, AdWords will look for the UploadConversion in the account that is being used to upload conversions. You can find your account's effective conversion tracking account by navigating to Tools > Conversions in the AdWords UI, but keep in mind that this will show you the current effective conversion tracking account, which may differ from the effective conversion tracking account that was in place at the time of the click.

• The conversionTime has to be after the click happened, otherwise the server will throw an OfflineConversionError.CONVERSION_PRECEDES_CLICK error.

• The conversionTime must be before the click-through conversion lookback window you specified for the UploadConversion object, otherwise the server will throw an OfflineConversionError.EXPIRED_CLICK error.

• The conversionValue must be greater than or equal to zero.

• A Timezone ID is required for conversionTime. The Timezone ID can be for any valid timezone -- it does not have to match the account's timezone.

Tips

A few things to keep in mind when creating an OfflineConversionFeed:

• We recommend you wait 6 hours after creating the UploadConversion before uploading.

• It takes up to 3 hours for imported conversions statistics to show up in your AdWords account.

• Even though duplicate uploads of a conversion (same GCLID, name, and time) are permitted, only the first instance is recorded.

Code examples

The AdvancedOperations folder of each client library contains a code example of uploading offline conversions: