Page Summary
-
The
Conversion.update()method allows modification of existing conversions in Search Ads 360, such as revenue, currency, quantity, order ID, custom Floodlight variables, and conversion state. -
While certain aspects like conversion date, type, attribution, and Floodlight activity cannot be directly changed via update, you can remove the conversion and upload a new one with the desired modifications.
-
Search Ads 360 handles updates on a best-effort basis for batches, meaning some may succeed while others fail; it is recommended to review the response for each conversion.
-
You can identify conversions to update either by their
clickId(within 60 days of generation) or bycriterionId(keyword ID), alongside mandatory fields likeconversionId,conversionTimestamp, andtype. -
Responses indicate success only if all updates succeed, providing full conversion details upon success and failure messages for unsuccessful ones.
Call the Conversion.update()
method to make the following types of changes to one or more existing conversions:
- Modify the revenue, currency code, or quantity.
- Modify the advertiser-provided order ID and any custom Floodlight variables.
- Remove the conversion by changing the
conversion.statefromACTIVEtoREMOVED.
Search Ads 360 does not support changing the following:
- The conversion date.
- The conversion type.
- The keyword or visit that is attributed for the conversion.
- The Floodlight activity or activity name.
However, you can always mark an existing conversion as REMOVED and upload a new conversion
with the updated date, type, attribution IDs, or Floodlight activity (be sure to specify a
new conversionId as well).
You can edit both conversions that were uploaded through the Search Ads 360 API (offline conversions) and conversions that Search Ads 360 recorded through Floodlight tags (online conversions), subject to the following time limits:
-
If you identify the conversion by
clickId, the click ID must have been generated within the last 60 days (error code0x0000012Fotherwise). -
Conversions recorded through Floodlight tags can only be edited within 28 days of the
conversionTimestamp(error code0x00000125otherwise).
As with Conversion.insert(), if your update request specifies multiple
conversions, Search Ads 360 attempts to update each conversion on a best-effort basis
instead of updating the entire batch as an all-or-nothing transaction. If some updates in a
batch fail, others might still succeed. We recommend you read
the response for every updated conversion to make sure that the update is successful.
Deprecation of dsConversionId
The dsConversionId field is deprecated and can no longer be used to identify
conversions. You must use conversionId (the advertiser conversion ID) to edit
conversions in the Search Ads 360 Conversion API. Conversion.update() rejects
a conversion with error code 0x0000013C (Conversion editing using
integer DS conversion ID is deprecated) if the conversion either:
- specifies the
dsConversionIdfield, or - passes a Search Ads 360 conversion ID (the 17-digit numeric ID that
Search Ads 360 generates for each conversion) in the
conversionIdfield.
Key Changes:
-
dsConversionIdDeprecation:dsConversionIDis no longer supported in the Search Ads 360 Conversion API, the Search Ads 360 Reporting API (referred to asconversion.id), or the reporting UI (referred to as "Conversion ID"). -
conversionIdRequirement:conversionIdis a mandatory field for editing conversions through the Search Ads 360 Conversion API.
How to obtain conversionId:
-
Conversions uploaded through the Search Ads 360 API: Use the
conversionIdthat you specified when you inserted the conversion. -
Conversions recorded through Floodlight tags: Use the Floodlight
order ID (the
ordvalue) that the Floodlight tag reported for the conversion, for example the order or transaction ID of a Floodlight sales activity. -
Search Ads 360 Reporting API: You can retrieve
advertiser_conversion_idusing the Search Ads 360 Reporting API. This value corresponds to theconversionIdrequired for editing. -
Search Ads 360 UI: You can find “Advertiser conversion ID” in the
conversion reporting page within the Search Ads 360 user interface.
Send an update request
Most of the fields that you specify in a Conversion.update() are used to
identify the conversions you want to update. You can use either of the following
techniques to identify an existing conversion:
- Specify the conversion's
clickId- All the conversions edited must be within 60 days of the time when the click ID is generated.
- Specify the conversion's keyword (
customerId,campaignId,adGroupId, andcriterionId)
Both techniques require you to specify the conversion's conversionId, conversionTimestamp,
and transaction type. The conversionTimestamp must be the timestamp
of the existing conversion, in Epoch milliseconds UTC. If the timestamp doesn't match the
existing conversion (for example, because it was converted from a local time zone),
Search Ads 360 can't find the conversion and returns error code 0x0000011B.
For conversions that Search Ads 360 recorded through Floodlight tags, you must also
specify the Floodlight activity of the conversion (segmentationType and
either segmentationName or segmentationId). Otherwise, the
request fails with error code 0x0000010C. We recommend that you specify the
Floodlight activity in every update request.
In addition, if the original conversion specified revenueMicros and currencyCode
or quantityMillis, the update request needs to specify this data even if you
aren't changing it.
Identify conversion by click ID
If a conversion originally specified a click ID, you can send a Conversion.update()
request that specifies the following fields:
clickIdconversionIdconversionTimestamptypesegmentationTypeandsegmentationName(orsegmentationId) (required for conversions recorded through Floodlight tags, recommended for all conversions)state(only required if you want to change the state to REMOVED or ACTIVE)quantityMillis(only if specified in the original conversion)revenueMicros(only if specified in the original conversion)currencyCode(only if specified in the original conversion)
Example
Here's an example of two existing conversions:
{ "kind": "doubleclicksearch#conversionList", "conversion" : [{ "clickId" : "COiYmPDTv7kCFcP0KgodOzQAAA", "conversionId" : "test_20130906_10", "conversionTimestamp" : "1378710000000", "segmentationType" : "FLOODLIGHT", "segmentationName" : "Test", "type": "TRANSACTION", "revenueMicros": "100000000", // 100 million revenueMicros is equivalent to $100 of revenue "currencyCode": "USD" }, { "clickId": "COiYmPDTv7kCFcP0KgodOzQAAA", "conversionId": "test_1383337059137", "conversionTimestamp": "1378710000000", "segmentationType" : "FLOODLIGHT", "segmentationName" : "Test", "type": "ACTION", "quantityMillis": "1000" }] }
The following request updates one of the conversions from the previous example and removes the other:
JSON
Note that a Conversion.update() request uses the PUT
HTTP method.
PUT 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 data from your site "conversionId": "test_20130906_10", "conversionTimestamp": "1378710000000", "segmentationType" : "FLOODLIGHT", "segmentationName" : "Test", "type": "TRANSACTION", "revenueMicros": "90000000", // 90 million revenueMicros is equivalent to $90 of revenue "currencyCode": "USD" }, { "clickId": "COiYmPDTv7kCFcP0KgodOzQAAA", // Replace with data from your site "conversionId": "test_1383337059137", "conversionTimestamp": "1378710000000", "segmentationType" : "FLOODLIGHT", "segmentationName" : "Test", "type": "ACTION", "quantityMillis": "1000", "state": "REMOVED" } ] }
Java
/** * Instantiate the Doubleclicksearch service, create a conversion that updates an existing conversion, * and upload the conversions. */ 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>(); // Create a conversion and add it to the conversion list. // Just to get a little fancy, the updateConversionFromVisit() method can be used for all // visit conversions, including conversions that don't specify quantity, revenue, or currency. // If quantityMillis wasn't specified in the original conversion, specify -1L for the // quantityMillis parameter. Likewise, if revenueMicros wasn't specified originally, // specify -1L for the revenueMicros parameter and an empty string for currency. conversionList = updateConversionFromVisit( conversionList, "COiYmPDTv7kCFcP0KgodOzQAAA", // clickId. Replace with data from your site "test_20130906_10", // conversionId 1378710000000L, // timeStamp "TRANSACTION", // type "", // state -1L, // quantityMillis 90000000L, // revenueMicros. Equivalent to $90 of revenue "USD"); // currencyCode // Here's a conversion that needs to be removed. Just set the state parameter to "REMOVED". conversionList = updateConversionFromVisit( conversionList, "COiYmPDTv7kCFcP0KgodOzQAAA", // clickId. Replace with data from your site "test_1383337059137", // conversionId 1378710000000L, // timeStamp "ACTION", // type "REMOVED", // state 1000L, // quantityMillis -1L, // revenueMicros ""); // currencyCode // Upload the List and handle the response. uploadConversions(conversions, service); // See an example in Add New Conversions. } /** * Create a conversion and add it to a List<Conversion>. */ private static List<Conversion> updateConversionFromVisit(List<Conversion> conversions, String clickId, String conversionId, Long timeStamp, String type, String state, Long quantity, Long revenue, String currency) { // Identifies the existing conversion. This sample hard-codes the segmentation name. Conversion conversion = new Conversion() .setClickId(clickId) .setConversionId(conversionId) .setConversionTimestamp(BigInteger.valueOf(timeStamp)) .setSegmentationType("FLOODLIGHT") .setSegmentationName("Test") .setType(type); // Only add these fields if the value is not empty greater than -1. if(!state.isEmpty()) conversion.setState(state); if (quantity > -1L) { conversion.setQuantityMillis(quantity); } if (revenue > -1L) { conversion.setRevenueMicros(revenue); if (!currency.isEmpty()) { conversion.setCurrencyCode(currency); } else { System.err.println(String.format( "Can't add conversion %s. It specifies revenue but no currency.", conversion.getConversionId())); return conversions; } } conversions.add(conversion); return conversions; }
Python
def update_conversion(service): """Change the revenue for one existing conversion and remove another. Args: service: An authorized Doubleclicksearch service. See Set Up Your Application. """ request = service.conversion().update( body= { 'conversion' : [{ 'clickId' : 'COiYmPDTv7kCFcP0KgodOzQAAA', // Replace with data from your site 'conversionId' : 'test_20130906_13', 'conversionTimestamp' : '1378710000000', 'segmentationType' : 'FLOODLIGHT', 'segmentationName' : 'Test', 'type': 'TRANSACTION', 'revenueMicros': '90000000', // 90 million revenueMicros is equivalent to $90 of revenue 'currencyCode': 'USD' }, { 'clickId': 'COiYmPDTv7kCFcP0KgodOzQAAA', // Replace with data from your site 'conversionId': 'test_1383337059137_01', 'conversionTimestamp': '1378710000000', 'segmentationType' : 'FLOODLIGHT', 'segmentationName' : 'Test', 'type': 'ACTION', 'quantityMillis': '1000', 'state': 'REMOVED' }] } ) pprint.pprint(request.execute())
Identify conversion by keyword ID
If you don't have access to a click ID, or if a conversion was originally attributed to a
keyword or keyword/ad, you can send a Conversion.update() request that
specifies the following fields:
customerId,campaignId,adGroupId, andcriterionId(the new Search Ads 360 IDs that identify the keyword)conversionIdconversionTimestamptypestate(only required if you want to change the state to REMOVED or ACTIVE)quantityMillis(only if specified in the original conversion)revenueMicros(only if specified in the original conversion)currencyCode(only if specified in the original conversion)
Keyword IDs are unique only within an ad group, so you need to specify all four IDs.
If a conversion specifies criterionId without customerId,
campaignId, or adGroupId, the update fails with error code
0x0000012E. You don't need to specify other IDs, such as the conversion's ad
ID.
Example
Here's an example of an existing conversion:
{ "kind": "doubleclicksearch#conversionList", "conversion" : [{ "customerId": "123-456-7890", "campaignId": "14660344555", "adGroupId": "105138634255", "criterionId": "948710340465", "conversionId": "test_1383157519886", "conversionTimestamp": "1378710000000", "type": "ACTION", "quantityMillis": "1000", "segmentationType": "FLOODLIGHT", "segmentationName": "Test" }] }
The following request updates the quantity of the conversion:
JSON
Note that a Conversion.update() request uses the PUT
HTTP method.
PUT https://www.googleapis.com/doubleclicksearch/v2/conversion Authorization: Bearer your OAuth 2.0 access token Content-type: application/json { "kind": "doubleclicksearch#conversionList", "conversion": [ { "customerId": "123-456-7890", // Replace with your ID "campaignId": "14660344555", // Replace with your ID "adGroupId": "105138634255", // Replace with your ID "criterionId": "948710340465", // Replace with your ID "conversionId": "test_1383157519886", "conversionTimestamp": "1378710000000", "type": "ACTION", "quantityMillis": "3000" } ] }
Java
// Send conversion data to updateConversion, which creates a conversion and adds it // to the conversion list. conversionList = updateConversionFromKeyword(conversionList, "123-456-7890", // customerId. Replace with your ID 14660344555L, // campaignId. Replace with your ID 105138634255L, // adGroupId. Replace with your ID 948710340465L, // criterionId. Replace with your ID "test_1383157519886", // conversionId 1378710000000L, // timeStamp "ACTION", // type "", // state 3000L, // quantityMillis -1L, // revenueMicros ""); // currencyCode private static List<Conversion> updateConversionFromKeyword(List<Conversion> conversions, String customerId, Long campaignId, Long adGroupId, Long criterionId, String conversionId, Long timeStamp, String type, String state, Long quantity, Long revenue, String currency ) { Conversion conversion = new Conversion() .setCustomerId(customerId) .setCampaignId(campaignId) .setAdGroupId(adGroupId) .setCriterionId(criterionId) .setConversionId(conversionId) .setConversionTimestamp(BigInteger.valueOf(timeStamp)) .setType(type); // Only add these fields if the value is not empty greater than -1. if(!state.isEmpty()) conversion.setState(state); if (quantity > -1L) { conversion.setQuantityMillis(quantity); } if (revenue > -1L) { conversion.setRevenueMicros(revenue); if (!currency.isEmpty()) { conversion.setCurrencyCode(currency); } else { System.err.println(String.format( "Can't add conversion %s. It specifies revenue but no currency.", conversion.getConversionId())); return conversions; } } conversions.add(conversion); return conversions; }
Python
def update_conversion(service): """Change the quantity of a conversion. Use the keyword's IDs (customerId, campaignId, adGroupId, and criterionId) to identify the conversion. Args: service: An authorized Doubleclicksearch service. See Set Up Your Application. """ request = service.conversion().update( body= { 'conversion': [{ 'customerId': '123-456-7890', // Replace with your ID 'campaignId': '14660344555', // Replace with your ID 'adGroupId': '105138634255', // Replace with your ID 'criterionId': '948710340465', // Replace with your ID 'conversionId': 'test_1383157519886', 'conversionTimestamp': '1378710000000', 'type': 'ACTION', 'quantityMillis': '3000' }] } ) pprint.pprint(request.execute())
Handle Search Ads 360 responses
The response for an update request is the same as the response for an insert request: Search Ads 360 indicates success only if all conversions in the request were successfully updated.
If the request succeeds, the response includes the full Search Ads 360 internal representation for each updated conversion, such as the new Search Ads 360 customer ID, campaign ID, ad group ID, and keyword (criterion) ID.
If one or more update fails to validate or upload, the response includes failure messages for each failed update. The response does not contain messages about conversions that successfully updated. For more information about these failure messages, see Handle Search Ads 360 responses for insert requests.