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 Search Ads 360 IDs, see Search Ads 360 IDs and Conversions.

Information regarding the restrictions on uploading historical conversions can be found in the Search Ads 360 help center.

If your Conversion.insert() request specifies multiple conversions, Search Ads 360 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 Search Ads 360 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 Campaign Manager 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 Search Ads 360 user signs into Search Ads 360 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 Search Ads 360 user to sign into Search Ads 360 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 Search Ads 360 help center for instructions.

  2. Upload conversions as soon as they are available. If you're attributing conversions to specific visits, wait at least 6 hours after the visit before you upload the conversion. Search Ads 360 might not recognize the visit's clickID if you upload sooner than 6 hours after the visit. In rare instances, you might need to wait up to 24 hours before Search Ads 360 could recognize the clickId.

    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.

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 only

The fields that are required in an Conversion.insert() request depend on the event or item you're attributing the conversion to. The following sections list the required and optional fields for each event or item you can attribute a conversion to.

Attribute a conversion to a specific visit

When a customer clicks one or more ads and lands on an advertiser's site, Search Ads 360 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:

Required fields

  • 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. Search Ads 360 will attribute the conversion to the keyword, ad, and other Search Ads 360 objects that were responsible for generating the visit.
    Wait at least 6 hours after Search Ads 360 generates a click ID to upload conversions. If you receive a "Click ID is not found" error, wait 24 hours, and then upload the conversions again. All conversions should be uploaded within 90 days of when the click ID is generated. Otherwise, the Search Ads 360 API might not recognize the visit.
  • conversionId: For offline conversions, advertisers provide this ID. Advertisers can specify any ID that is meaningful to them. Each conversion in a request must specify a unique ID, and the combination of ID and timestamp must be unique amongst all conversions within the advertiser. For online conversions, Search Ads 360 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: Specifies the type of conversion system that you're uploading the conversion to. Currently only Floodlight conversions are supported, so this field is always required to specify FLOODLIGHT.
  • segmentationName: The name of the Floodlight activity that the advertiser is using to report the conversion.

    If your advertiser contains activities with the same name (this can happen if the activities belong to different Floodlight groups), the recommended action is to rename one of the activities.

    Alternatively, if you know the ID Search Ads 360 has assigned to a Floodlight activity, you can specify the ID in the segmentationId instead of specifying the name in the segmentationName field. (Campaign Manager also assigns an ID to the Floodlight activity, but the Campaign Manager ID is different from the Search Ads 360 ID and it cannot be used to attribute conversions.) To view the Search Ads 360 ID for a Floodlight activity, download a conversions report (either from the Search Ads 360 UI or the reporting API). If at least one conversion has been attributed to the Floodlight activity during the report's timeframe, you'll see the Search Ads 360 ID in the report.

  • 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 field:

    • revenueMicros: The monetary value of the conversion.

Optional fields

  • 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, Search Ads 360 automatically inserts a value of 1000.
  • currencyCode: The currency of a transaction's revenue. By default, revenue is assumed to be in the advertiser's currency. If you specify a different currency, Search Ads 360 converts the specified revenue amount to the advertiser's currency. Learn more
    Use the ISO 4217 alphabetic (3-char) format to specify currency.
    Applicable only for TRANSACTION conversions.
  • customMetric and customDimension: Uploads additional data about a conversion, such as the country to which a purchased item is shipped, product IDs, or even the duration of a telephone call. Learn more about uploading data for custom Floodlight variables.
  • deviceType: Specifies the type of device on which the conversion occurred. See the list of values accepted for this field.

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

  /**
   * Instantiate the Doubleclicksearch 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 Doubleclicksearch 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 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 Search Ads 360 identifiers and only specify the keyword's identifier along with a few other fields:

Required 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 Search Ads 360 IDs and Conversions.
  • conversionId: For offline conversions, advertisers provide this ID. Advertisers can specify any ID that is meaningful to them. Each conversion in a request must specify a unique ID, and the combination of ID and timestamp must be unique amongst all conversions within the advertiser. For online conversions, Search Ads 360 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: Specifies the type of conversion system that you're uploading the conversion to. Currently only Floodlight conversions are supported, so this field is always required to specify FLOODLIGHT.
  • segmentationName: The name of the Floodlight activity that the advertiser is using to report the conversion.

    If your advertiser contains activities with the same name (this can happen if the activities belong to different Floodlight groups), the recommended action is to rename one of the activities.

    Alternatively, if you know the ID Search Ads 360 has assigned to a Floodlight activity, you can specify the ID in the segmentationId instead of specifying the name in the segmentationName field. (Campaign Manager also assigns an ID to the Floodlight activity, but the Campaign Manager ID is different from the Search Ads 360 ID and it cannot be used to attribute conversions.) To view the Search Ads 360 ID for a Floodlight activity, download a conversions report (either from the Search Ads 360 UI or the reporting API). If at least one conversion has been attributed to the Floodlight activity during the report's timeframe, you'll see the Search Ads 360 ID in the report.

  • 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 field:

    • revenueMicros: The monetary value of the conversion.

Optional fields

  • 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, Search Ads 360 automatically inserts a value of 1000.
  • currencyCode: The currency of a transaction's revenue. By default, revenue is assumed to be in the advertiser's currency. If you specify a different currency, Search Ads 360 converts the specified revenue amount to the advertiser's currency. Learn more
    Use the ISO 4217 alphabetic (3-char) format to specify currency.
    Applicable only for TRANSACTION conversions.
  • customMetric and customDimension: Uploads additional data about a conversion, such as the country to which a purchased item is shipped, product IDs, or even the duration of a telephone call. Learn more about uploading data for custom Floodlight variables.
  • deviceType: Specifies the type of device on which the conversion occurred. See the list of values accepted for this field.

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 Doubleclicksearch 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())

Upload data from a third-party attribution model

An attribution model distributes credit for a conversion across all of the activity in a conversion path. For example, if a consumer clicks on a paid search ad, a display ad, and another paid search ad before converting, a linear attribution model would give each click 33% of the conversion credit.

While Search Ads 360 provides attribution models, if you use a third-party service or a service you've developed to distribute credit to clicks, you can upload the third-party attribution data into Search Ads 360 and use the data in reports and Search Ads 360 bid strategies.

Before you start

In Campaign Manager, create a custom attribution model and import the model into Search Ads 360. Make sure you name the model External Attribution Model. This enables Search Ads 360 features to recognize that an attribution model has been applied to the conversion data you upload. Learn more

Required fields

To apply a third-party attribution model to a conversion, specify all of 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. Search Ads 360 will attribute the conversion to the keyword, ad, and other Search Ads 360 objects that were responsible for generating the visit.
    Wait at least 30 minutes after Search Ads 360 generates a click ID before uploading a conversion with the ID. Otherwise, the Search Ads 360 API might not recognize the visit.
  • attributionModel: Set to External Attribution Model. Learn more
  • countMillis: The amount of conversion credit to distibute to this click. Applicable only if the request also includes the attributionModel field.

    Don't confuse this with quantityMillis, an optional field that specifies the number of items in a conversion (such as the number of items in a shopping cart purchase).

  • conversionId: For offline conversions, advertisers provide this ID. Advertisers can specify any ID that is meaningful to them. Each conversion in a request must specify a unique ID, and the combination of ID and timestamp must be unique amongst all conversions within the advertiser. For online conversions, Search Ads 360 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: Specifies the type of conversion system that you're uploading the conversion to. Currently only Floodlight conversions are supported, so this field is always required to specify FLOODLIGHT.
  • segmentationName: The name of the Floodlight activity that the advertiser is using to report the conversion.

    If your advertiser contains activities with the same name (this can happen if the activities belong to different Floodlight groups), the recommended action is to rename one of the activities.

    Alternatively, if you know the ID Search Ads 360 has assigned to a Floodlight activity, you can specify the ID in the segmentationId instead of specifying the name in the segmentationName field. (Campaign Manager also assigns an ID to the Floodlight activity, but the Campaign Manager ID is different from the Search Ads 360 ID and it cannot be used to attribute conversions.) To view the Search Ads 360 ID for a Floodlight activity, download a conversions report (either from the Search Ads 360 UI or the reporting API). If at least one conversion has been attributed to the Floodlight activity during the report's timeframe, you'll see the Search Ads 360 ID in the report.

  • 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 field:

    • revenueMicros: The monetary value of the conversion.

If you track conversion revenue, be sure that your model distributes revenue across each touch point in a conversion path. For example, if your model uses a linear approach (equally distributing revenue across each touch point), in a conversion path that includes 3 ad clicks, each click will be attributed with 33% of the conversion. If the conversion earned $100 in revenue, make sure your model distributes $33 of revenue to each click, and make sure revenueMicros specifies only $33 of revenue for each click.

Optional fields

  • 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, Search Ads 360 automatically inserts a value of 1000.
  • currencyCode: The currency of a transaction's revenue. By default, revenue is assumed to be in the advertiser's currency. If you specify a different currency, Search Ads 360 converts the specified revenue amount to the advertiser's currency. Learn more
    Use the ISO 4217 alphabetic (3-char) format to specify currency.
    Applicable only for TRANSACTION conversions.
  • customMetric and customDimension: Uploads additional data about a conversion, such as the country to which a purchased item is shipped, product IDs, or even the duration of a telephone call. Learn more about uploading data for custom Floodlight variables.
  • deviceType: Specifies the type of device on which the conversion occurred. See the list of values accepted for this field.

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" : [{
    "clickId" : "PP5K8iI6ul7Vw09JZZDEp", // Replace with a click ID from your site
    "conversionId" : "test_20130906_04",
    "conversionTimestamp" : "1378710000000",
    "segmentationType" : "FLOODLIGHT",
    "segmentationName" : "Test",
    "type": "TRANSACTION",
    "attributionModel": "External Attribution Model",
    "countMillis": "330",
    "revenueMicros": "33000000", // 33 million revenueMicros is equivalent to $33 of revenue
    "currencyCode": "USD"
  }]
}

Handle Search Ads 360 responses

The response from Search Ads 360 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 Search Ads 360 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 Search Ads 360 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 Search Ads 360.

Responding to an error

If the request fails, try to re-submit the entire request call later. Search Ads 360 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.