The Wayback Machine - https://web.archive.org/web/20161021033011/https://developers.google.com/doubleclick-search/v2/how-tos/conversions/insert

Add New Conversions

Call the Conversion.insert() method to add one or more conversions. To properly attribute the conversion, your request needs to specify the name of a Floodlight activity that the advertiser is using to report offline conversions, along with the ID of the keyword, ad, and possibly the click that led to the conversion. For information on obtaining DoubleClick Search IDs, see DoubleClick Search IDs and Conversions.

You can add or update conversions with a timestamp as far back as 2013/01/01.

If your Conversion.insert() request specifies multiple conversions, DoubleClick Search attempts to upload each conversion on a best-effort basis instead of uploading the entire batch as an all-or-nothing transaction. If some conversions in a batch fail to upload, others might still successfully upload. Conversion uploads can fail because of an invalid request or transient network or system failures. Therefore, we recommend you read the response for every inserted conversion to make sure that the upload is successful.

How soon can I use the uploaded data?

If you specify a conversionTimestamp of today or yesterday for a conversion, metrics for the conversion will show up in the campaign management UI within an hour of the upload. If you specify a conversionTimestamp that's older than yesterday, metrics will be updated in several hours.

Convert all timestamps for conversions to Epoch time (also known as Unix time).

Can I create Floodlight activities from the API?

If the advertiser hasn't yet created a Floodlight activity for tracking offline conversions, you can use the DoubleClick for Advertisers API to create one. You can't use the API to specify that a Floodlight activity is used primarily for offline conversions, which is a best practice when bid strategies will be using data from the conversion.

We recommend that after you use the API to create a Floodlight activity, a DoubleClick Search user signs into DoubleClick Search and changes the activity's setting to indicate that the primary source of conversions is offline activity.

Best practices for adding conversions

We recommend the following best practices for adding conversions:

  1. Ask a DoubleClick Search user to sign into DoubleClick Search and change the settings for each Floodlight activity that you use to report offline conversions. The settings should indicate that the primary source of conversions is offline activity. See the DoubleClick Search help center for instructions.

  2. Upload conversions as soon as they are available. If you're attributing conversions to specific visits, wait at least 30 minutes after the visit before you upload the conversion. DS might not recognize the visit's clickID if you upload sooner than 30 minutes after the visit.

    Make sure that each upload contains the most recent conversions. Within a single upload request, it’s OK if the entries are out of chronological order. But a bid strategy might not be able to consider older conversions that you upload later in a different request.

  3. If no conversions have been uploaded for a Floodlight activity in the last 1-2 hours, send a request to indicate that no conversions have occurred.

    This availability request clarifies whether the lack of conversion data during the last 1-2 hours means that no conversions have occurred or that you haven’t uploaded the data yet.

Handling a processing delay

If there's always a delay between the time that conversions occur and the time that you upload the conversions, be sure to adjust the timestamp in your availability requests to account for the delay.

For example, consider the following scenario for an advertiser who batches conversions and uploads them every 5 hours:

  1. A conversion occurs at 12pm.

  2. No other conversions occur by 2pm, so the advertiser sends an availabilty request to indicate that no conversions have occurred since 12pm.

  3. A conversion occurs at 3pm.

  4. No other conversions occur by 4pm, so the advertiser sends an availabilty request to indicate that no conversions have occurred since 12pm.

  5. At 5pm, the advertiser sends the conversions that occurred at 12pm and 3pm.

  6. No other conversions occur by 7pm, so the advertiser sends an availabilty request to indicate that no conversions have occurred since 3pm.

Send an insert request

You can send a Conversion.insert() request to do any of the following:

  • Attribute a conversion to a specific visit
  • Attribute a conversion to a keyword and ad
  • Attribute a conversion to a keyword only
  • Attribute a conversion to a product in a Shopping campaign

Attribute a conversion to a specific visit

When a customer clicks one or more ads and lands on an advertiser's site, DoubleClick Search considers the user session on the advertiser's site to be a visit. To attribute a conversion to a visit, specify the following in your Conversion.insert() request:

  • clickId: The visit's case-sensitive click ID. Look in the advertiser's web logs for the click ID or list conversions and use a click ID from another conversion. DoubleClick Search will attribute the conversion to the keyword, ad, and other DoubleClick Search objects that were responsible for generating the visit.
    Wait at least 30 minutes after DoubleClick Search generates a click ID before uploading a conversion with the ID. Otherwise, the DoubleClick Search API might not recognize the visit.
  • conversionId: For offline conversions, this is an ID that advertisers are required to provide. Advertisers can specify any ID that is meaningful to them. For online conversions, DS copies the dsConversionId or floodlightOrderId into this property depending on the advertiser's Floodlight instructions.
  • conversionTimestamp: Indicates the date and time at which the conversion occurred. For example, if the conversion occurs on Fri, 05 Aug 2016 11:53:22 AM Eastern Daylight Savings Time (GMT -4:00), specify the timestamp in Epoch milliseconds: 1470412402000.
  • segmentationType: This field of the request is always required to specify FLOODLIGHT.
  • segmentationName: The name of the Floodlight activity that the advertiser is using to report the conversion.
  • type: The type of the conversion, that is, either ACTION or TRANSACTION. An ACTION conversion has no monetary value, while a TRANSACTION conversion does. Examples are email list signups (ACTION) versus ecommerce purchases (TRANSACTION).

    If you specify TRANSACTION, you also need to specify the following fields:

    • revenueMicros: The monetary value of the conversion.
    • currencyCode: The currency of revenueMicros.
  • quantityMillis: The number of items in this conversion. For example, the number of people who signed up for an email newsletter or the total quantity of items sold. If you don't specify this field for ACTION conversions, DS automatically inserts a value of 1000.

JSON

POST  https://www.googleapis.com/doubleclicksearch/v2/conversion
Authorization: Bearer your OAuth 2.0 access token
Content-type: application/json
{
 "kind": "doubleclicksearch#conversionList",
  "conversion" : [{
    "clickId" : "COiYmPDTv7kCFcP0KgodOzQAAA", // Replace with a click ID from your site
    "conversionId" : "test_20130906_04",
    "conversionTimestamp" : "1378710000000",
    "segmentationType" : "FLOODLIGHT",
    "segmentationName" : "Test",
    "type": "TRANSACTION",
    "revenueMicros": "10000000", // 10 million revenueMicros is equivalent to $10 of revenue
    "currencyCode": "USD"
  }]
}

Java

  /**
   * Set up a DoubleClick Search service, create conversions, and upload them.
   */
  public static void main(String[] args) throws Exception {

    Doubleclicksearch service = getService(); // See Set Up Your Application.

    // Set up a List to keep track of each conversion you create.
    List<Conversion> conversions = new Vector<Conversion>();

    // Add a conversion to the List.
    addTransactionConversionForVisit(conversions, "COiYmPDTv7kCFcP0KgodOzQAAA", // Replace with a click ID from your site
        "test_" + System.currentTimeMillis(), 10000000L, 1378710000000L);

    // Upload the List and handle the response.
    uploadConversions(conversions, service);
  }


  /**
   * Create a TRANSACTION conversion and add it to a List<Conversion>. This sample hard-codes
   * the segmentation name and currency. You probably wouldn't want your production code to be so brittle.
   */
  private static List<Conversion> addTransactionConversionForVisit(List<Conversion> conversions,
      String clickId, String conversionId, Long revenue, Long timeStamp) {

    Conversion conversion = new Conversion().setClickId(clickId)
        .setConversionId(conversionId)
        .setSegmentationType("FLOODLIGHT")
        .setSegmentationName("Test")
        .setType("TRANSACTION")
        .setRevenueMicros(revenue)
        .setCurrencyCode("USD")
        .setConversionTimestamp(BigInteger.valueOf(timeStamp));

    conversions.add(conversion);
    return conversions;
  }


  /**
   * Convert the List of conversions to a DS ConversionList, send an insert request to DS,
   * and output the response to a file.
   */
  private static void uploadConversions(List<Conversion> conversions, Doubleclicksearch service)
      throws IOException {

    FileOutputStream outputStream =
        new FileOutputStream(new File("./", "InsertConversionsResponse.txt"));
    final PrintStream printStream = new PrintStream(outputStream);

    try {
      // Convert the List to a ConversionList.
      ConversionList conversionList = new ConversionList().setConversion(conversions);

      // Insert an upload request and download the response to a file.
      service.conversion().insert(conversionList).executeAndDownloadTo(printStream);
      printStream.close();
    } catch (GoogleJsonResponseException e) {
      System.err.println("Get request was rejected.");
      for (ErrorInfo error : e.getDetails().getErrors()) {
        System.err.println(error.getMessage());
      }
      System.exit(e.getStatusCode());
    }
  }

Python

def insert_conversion(service):
  """Create and upload a TRANSACTION conversion that is attributed to a visit.

  Args:
    service: An authorized Doublelcicksearch service. See Set Up Your Application.
  """
  request = service.conversion().insert(
      body=
      {
          'conversion': [{
              'clickId': 'COiYmPDTv7kCFcP0KgodOzQAAA', // Replace with a click ID from your site
              'conversionId': 'test_20140206_00',
              'conversionTimestamp': '1378710000000',
              'segmentationType': 'FLOODLIGHT',
              'segmentationName': 'Test',
              'type': 'TRANSACTION',
              'revenueMicros': '10000000', // 10 million revenueMicros is equivalent to $10 of revenue
              'currencyCode': 'USD'
              }]
      }
  )

  pprint.pprint(request.execute())

Attribute a conversion to a keyword and ad

Instead of attributing a conversion to a specific visit, you can attribute to an ad and keyword by specifying the following in your Conversion.insert() request:

  • DoubleClick Search identifiers for agency, advertiser, engine account, campaign, ad group, keyword (criterion) and ad. For information on obtaining these IDs, see DoubleClick Search IDs and Conversions.
  • conversionId: For offline conversions, this is an ID that advertisers are required to provide. Advertisers can specify any ID that is meaningful to them. For online conversions, DS copies the dsConversionId or floodlightOrderId into this property depending on the advertiser's Floodlight instructions.
  • conversionTimestamp: Indicates the date and time at which the conversion occurred. For example, if the conversion occurs on Fri, 05 Aug 2016 11:53:22 AM Eastern Daylight Savings Time (GMT -4:00), specify the timestamp in Epoch milliseconds: 1470412402000.
  • segmentationType: This field of the request is always required to specify FLOODLIGHT.
  • segmentationName: The name of the Floodlight activity that the advertiser is using to report the conversion.
  • type: The type of the conversion, that is, either ACTION or TRANSACTION. An ACTION conversion has no monetary value, while a TRANSACTION conversion does. Examples are email list signups (ACTION) versus ecommerce purchases (TRANSACTION).

    If you specify TRANSACTION, you also need to specify the following fields:

    • revenueMicros: The monetary value of the conversion.
    • currencyCode: The currency of revenueMicros.
  • quantityMillis: The number of items in this conversion. For example, the number of people who signed up for an email newsletter or the total quantity of items sold. If you don't specify this field for ACTION conversions, DS automatically inserts a value of 1000.

JSON

POST  https://www.googleapis.com/doubleclicksearch/v2/conversion
Authorization: Bearer your OAuth 2.0 access token
Content-type: application/json
{
 "kind": "doubleclicksearch#conversionList",
  "conversion" : [{
   "agencyId": "12300000000000456", // Replace with your ID
   "advertiserId": "45600000000010291", // Replace with your ID
   "engineAccountId": "700000000042441", // Replace with your ID
   "campaignId": "71700000002044839", // Replace with your ID
   "adGroupId": "58700000032026064", // Replace with your ID
   "criterionId": "43700004289911004", // Replace with your ID
   "adId": "44700000155906860", // Replace with your ID
   "conversionId": "test_1383157519886",
   "conversionTimestamp": "1378710000000",
   "type": "ACTION",
   "quantityMillis": "3000",
   "segmentationType": "FLOODLIGHT",
   "segmentationName": "Test"
  }]
}

Java

  /**
   * Creates an ACTION conversion that is attributed to a keyword and add. Adds the conversion
   * to a List<Conversion>. The example in the preceding section
   * contains the uploadConversions method, which can submit the list as an insert() request.
   */
  private static List<Conversion> addActionConversionForAdKeyword(List<Conversion> conversions,
      Long agencyId, Long advertiserId, Long engineAccountId, Long campaignId, Long adGroupId,
      Long criterionId, Long adId, String conversionId, Long quantity, Long timeStamp) {

    Conversion conversion = new Conversion()
        .setAgencyId(agencyId)
        .setAdvertiserId(advertiserId)
        .setEngineAccountId(engineAccountId)
        .setCampaignId(campaignId)
        .setAdGroupId(adGroupId)
        .setCriterionId(criterionId)
        .setAdId(adId)
        .setConversionId(conversionId)
        .setConversionTimestamp(BigInteger.valueOf(timeStamp)
        .setSegmentationType("FLOODLIGHT")
        .setSegmentationName("Test")
        .setType("ACTION")
        .setQuantityMillis(quantity));

    conversions.add(conversion);
    return conversions;
  }

Python

def insert_conversion(service):
  """Create and upload a TRANSACTION conversion that is attributed to a keyword
  and ad.

  Args:
    service: An authorized Doublelcicksearch service. See Set Up Your Application.
  """
  request = service.conversion().insert(
      body=
      {
          'conversion': [{
              'agencyId': '12300000000000456', // Replace with your ID
              'advertiserId': '45600000000010291', // Replace with your ID
              'engineAccountId': '700000000042441', // Replace with your ID
              'campaignId': '71700000002044839', // Replace with your ID
              'adGroupId': '58700000032026064', // Replace with your ID
              'criterionId': '43700004289911004', // Replace with your ID
              'adId': '44700000155906860', // Replace with your ID
              'conversionId': 'test_1383157519886',
              'conversionTimestamp': '1378710000000',
              'type': 'ACTION',
              'quantityMillis': '3000',
              'segmentationType': 'FLOODLIGHT',
              'segmentationName': 'Test'
              }]
      }
  )

  pprint.pprint(request.execute())

Attribute a conversion to a keyword only

If your primary concern is to attribute conversions to keywords—and you're not concerned about attributing to ads—you can omit most of the DoubleClick Search identifiers and only specify the keyword's identifier along with a few other fields:

  • criterionId: This is the keyword identifier. You can get the criterionId by adding the TrackerId macro to your landing page URLs. For information on obtaining keyword IDs, see DoubleClick Search IDs and Conversions.
  • conversionId: For offline conversions, this is an ID that advertisers are required to provide. Advertisers can specify any ID that is meaningful to them. For online conversions, DS copies the dsConversionId or floodlightOrderId into this property depending on the advertiser's Floodlight instructions.
  • conversionTimestamp: Indicates the date and time at which the conversion occurred. For example, if the conversion occurs on Fri, 05 Aug 2016 11:53:22 AM Eastern Daylight Savings Time (GMT -4:00), specify the timestamp in Epoch milliseconds: 1470412402000.
  • segmentationType: This field of the request is always required to specify FLOODLIGHT.
  • segmentationName: The name of the Floodlight activity that the advertiser is using to report the conversion.
  • type: The type of the conversion, that is, either ACTION or TRANSACTION. An ACTION conversion has no monetary value, while a TRANSACTION conversion does. Examples are email list signups (ACTION) versus ecommerce purchases (TRANSACTION).

    If you specify TRANSACTION, you also need to specify the following fields:

    • revenueMicros: The monetary value of the conversion.
    • currencyCode: The currency of revenueMicros.
  • quantityMillis: The number of items in this conversion. For example, the number of people who signed up for an email newsletter or the total quantity of items sold. If you don't specify this field for ACTION conversions, DS automatically inserts a value of 1000.

JSON

POST  https://www.googleapis.com/doubleclicksearch/v2/conversion
Authorization: Bearer your OAuth 2.0 access token
Content-type: application/json
{
 "kind": "doubleclicksearch#conversionList",
  "conversion" : [{
    "criterionId": "43700003491981017", // Replace with your ID
    "conversionId": "customerTransaction73126",
    "conversionTimestamp": "1351196386000",
    "segmentationType": "FLOODLIGHT",
    "segmentationName": "Offline Purchase",
    "type": "TRANSACTION",
    "revenueMicros": "20000000", // 20 million revenueMicros is equivalent to $20 of revenue
    "currencyCode": "USD"
  }]
}

Java

  /**
   * Creates a TRANSACTION conversion, attributes it to a keyword only, and adds it to a List<Conversion>.
   * The example in the preceding section contains the uploadConversions method,
   * which can submit the list as an insert() request.
   */
  private static List<Conversion> addTransactionConversionForKeyword(List<Conversion> conversions,
      Long criterionId, String conversionId, Long revenue, Long timeStamp) {

    Conversion conversion = new Conversion()
        .setCriterionId(criterionId)
        .setConversionId(conversionId)
        .setSegmentationType("FLOODLIGHT")
        .setSegmentationName("Test")
        .setType("TRANSACTION")
        .setRevenueMicros(revenue)
        .setCurrencyCode("USD")
        .setConversionTimestamp(BigInteger.valueOf(timeStamp));

    conversions.add(conversion);
    return conversions;
  }

Python

def insert_conversion(service):
  """Create and upload a TRANSACTION conversion that is attributed to a keyword only.

  Args:
    service: An authorized Doublelcicksearch service. See Set Up Your Application.
  """
  request = service.conversion().insert(
      body=
      {
          'conversion': [{
              'criterionId': '43700004289911004', // Replace with your ID
              'conversionId': 'test_1378710000000',
              'conversionTimestamp': '1378710000000',
              'segmentationType': 'FLOODLIGHT',
              'segmentationName': 'Test',
              'type': 'TRANSACTION',
              'revenueMicros': '20000000', // 20 million revenueMicros is equivalent to $20 of revenue
              'currencyCode': 'USD'
              }]
      }
  )

  pprint.pprint(request.execute())

Attribute a conversion to products in a Shopping campaign

Shopping campaigns generate product listing ads from product data in a Merchant Center inventory feed. To attribute a conversion to a product that was advertised in a Shopping campaign, specify all of the following in your Conversion.insert() request:

  • productId: The ID for the product. The advertiser specifies this ID in the inventory feed.
  • productGroupId: The ID of the product group that you want to attribute for the conversion. DS assigns this ID to a product group when the group is created.
  • inventoryFeedId: The ID of the inventory feed to which the product belongs. DS assigns this ID when the advertiser links a product feed to DS.

    If the advertiser's Merchant Center account is a multi-client account, specify the ID of the sub-account that contains the product. You can find this ID by signing in to DoubleClick Search, clicking Inventory management in the left navigation pane, and looking in the ID column on the Inventory accounts tab.

  • productCountry: The country that has been defined for the Merchant Center feed that contains data about the product. Specify an ISO 3166 country code.
  • productLanguage: The language that has been defined for the Merchant Center feed that contains data about the product. Specify an ISO 639 language code.
  • channel: Specify online for online product listing ads and local for Local Inventory Ads.
  • storeId: For Local Inventory Ads, specify the store for which the product was advertised. This should match the store IDs used in your inventory feed.
  • conversionId: For offline conversions, this is an ID that advertisers are required to provide. Advertisers can specify any ID that is meaningful to them. For online conversions, DS copies the dsConversionId or floodlightOrderId into this property depending on the advertiser's Floodlight instructions.
  • conversionTimestamp: Indicates the date and time at which the conversion occurred. For example, if the conversion occurs on Fri, 05 Aug 2016 11:53:22 AM Eastern Daylight Savings Time (GMT -4:00), specify the timestamp in Epoch milliseconds: 1470412402000.
  • segmentationType: This field of the request is always required to specify FLOODLIGHT.
  • segmentationName: The name of the Floodlight activity that the advertiser is using to report the conversion.
  • type: The type of the conversion, that is, either ACTION or TRANSACTION. An ACTION conversion has no monetary value, while a TRANSACTION conversion does. Examples are email list signups (ACTION) versus ecommerce purchases (TRANSACTION).

    If you specify TRANSACTION, you also need to specify the following fields:

    • revenueMicros: The monetary value of the conversion.
    • currencyCode: The currency of revenueMicros.
  • quantityMillis: The number of items in this conversion. For example, the number of people who signed up for an email newsletter or the total quantity of items sold. If you don't specify this field for ACTION conversions, DS automatically inserts a value of 1000.

Example

POST  https://www.googleapis.com/doubleclicksearch/v2/conversion
Authorization: Bearer your OAuth 2.0 access token
Content-type: application/json
{
  "kind": "doubleclicksearch#conversionList",
  "conversion": [
  { // Conversion from a Local Inventory Ad
    "productGroupId": "92700000000000001", // Replace with your ID
    "productId": "123-abc", // Replace with your ID
    "inventoryAccountId": "97700000000000001", // Replace with your ID
    "productCountry": "US",
    "productLanguage": "en",
    "channel": "local",
    "storeId": "123456",
    "conversionId": "customerTransaction73126",
    "conversionTimestamp": "1376452740000",
    "segmentationType": "FLOODLIGHT",
    "segmentationName": "Offline Purchase",
    "type": "TRANSACTION",
    "state": "ACTIVE",
    "revenueMicros": "20000000", // 20 million revenueMicros is equivalent to $20 of revenue
    "currencyCode": "USD"
  },
  { // Conversion from an online product listing ad
    "productGroupId": "92700000000000001", // Replace with your ID
    "productId": "123-abc", // Replace with your ID
    "inventoryAccountId": "97700000000000001", // Replace with your ID
    "productCountry": "CA",
    "productLanguage": "en",
    "channel": "online",
    "conversionId": "customerTransaction73126", // Replace with your ID
    "conversionTimestamp": "1429229922000",
    "segmentationType": "FLOODLIGHT",
    "segmentationName": "shopact",
    "type": "ACTION",
    "state": "ACTIVE",
    "revenueMicros": "20000000",
    "currencyCode": "CAD"
  }]
}

Handle DoubleClick Search responses

The response from DoubleClick Search indicates success only if all conversions in the request were successfully validated and uploaded.

If the request succeeds

If the request succeeds, the response includes the full DoubleClick Search internal representation for each uploaded conversion, such as campaign ID, ad group ID and keyword (criterion) ID.

{
 "kind": "doubleclicksearch#conversionList",
 "conversion": [
  {
   "agencyId": "12300000000000456",
   "advertiserId": "45600000000010291",
   "engineAccountId": "700000000042441",
   "campaignId": "71700000002044839",
   "adGroupId": "58700000032026064",
   "criterionId": "43700004289911004",
   "adId": "0",
   "dsConversionId": "48719131694768384",
   "conversionId": "test_1383157331951",
   "state": "ACTIVE",
   "type": "TRANSACTION",
   "revenueMicros": "20000000",
   "currencyCode": "USD",
   "segmentationType": "FLOODLIGHT",
   "segmentationId": "25700000001464141",
   "segmentationName": "Test",
   "conversionTimestamp": "1378710000000",
   "conversionModifiedTimestamp": "1383157332368"
  },
  ...
 ]
}

If the request does not succeed

If one or more conversions fail to validate or upload, the response includes messages for each failed conversion upload. The response does not contain messages about conversions that successfully uploaded.

Here's an example response to a request that does not fully succeed:

{
 "error": {
    "errors": [
       {
          "reason": "requestValidation",
          "message": "The request was not valid. Details: [0x0000011F: Advertiser conversion ID ..."
       },
       {
          "reason": "requestValidation",
          "message": "The request was not valid. Details:  [0x00000101: Click ID ..."
       }
    ]
  }
}

Each failure message contains two important fields: a reason and a detailed error message. The reason field can contain requestValidation, internalError, transactionFailed, or lateStageRequestError.

requestValidation errors

requestValidation errors indicate data problems in the conversion upload request (e.g., the conversion has already been uploaded, or the clickId is not found). In this type of error, the message details contains two items:

  • A hexadecimal code that identifies the type of error. You can use the code in your own scripts to identify the errors.
  • A description of the validation error.

For more information, see the list of codes and descriptions that DoubleClick Search can return for conversion upload errors.

Other types of errors

All other types of errors (internalError, transactionFailed, or lateStageRequestError) indicate that there is an internal problem in DoubleClick Search.

Responding to an error

If the request fails, try to re-submit the entire request call later. DoubleClick Search will report requestValidation errors for any conversions that were already uploaded, but it will attempt to upload the remaining conversions.

If you still see errors after re-submitting, view the troubleshooting section for information on how to proceed.

Send feedback about...

This page
Documentation feedback
DoubleClick Search API
Product feedback