add

Creates bid adjustments.

Learn more

Restrictions

Maximum of 1 mobile adjustment per campaign or ad group.

Maximum of 1 video extension adjustment per campaign or ad group.

Maximum of 1 smart ad adjustment per campaign or ad group.

Maximum of 12 gender and age adjustments per campaign or ad group.

Maximum of 100 target audience adjustments per campaign or ad group.

Mobile adjustments can't be created for mobile app advertising campaigns and ad groups.

Adjustments for computers, tablets, and Smart TVs can only be created for groups of display, Text & Image, and dynamic ads, and for groups of smart banners.

Video extension adjustments can only be created for campaigns and groups of Text & Image ads.

Smart ad adjustments can only be created for campaigns and groups of smart banners.

Group-level adjustments can only be created for unified performance groups.

To learn more about matching the types of bid adjustments to the types of campaigns and ad groups, see Acceptable types of bid adjustments by type of campaign and group.

Request

Request structure in JSON format:

{
  "method": "add",
  "params": { /* params */
    "BidModifiers": [{  /* BidModifierAddItem */
      "MobileAdjustment": {  /* MobileAdjustmentAdd */
        "BidModifier": (int), /* required */
        "OperatingSystemType": ( "IOS" | "ANDROID" )
      },
      "TabletAdjustment": {  /* MobileAdjustmentAdd */
        "BidModifier": (int), /* required */
        "OperatingSystemType": ( "IOS" | "ANDROID" )
      },
      "DesktopAdjustment": {  /* DesktopAdjustmentAdd */
        "BidModifier": (int) /* required */
      },
      "DesktopOnlyAdjustment": {  /* DesktopAdjustmentAdd */
        "BidModifier": (int) /* required */
      },
      "DemographicsAdjustments": [{  /* DemographicsAdjustmentAdd */
        "Gender": ( "GENDER_MALE" | "GENDER_FEMALE" ),
        "Age": ( "AGE_0_17" | "AGE_18_24" | "AGE_25_34" | "AGE_35_44" | "AGE_45" | "AGE_45_54" | "AGE_55" ),
        "BidModifier": (int) /* required */
      }, ... ],
      "RetargetingAdjustments": [{  /* RetargetingAdjustmentAdd */
        "RetargetingConditionId": (long), /* required */
        "BidModifier": (int) /* required */
      }, ... ],
      "RegionalAdjustments": [{    /* RegionalAdjustmentAdd */
        "RegionId": (long), /* required */
        "BidModifier": (int) /* required */
      }, ... ],
      "VideoAdjustment": { /* VideoAdjustmentAdd */
        "BidModifier": (int) /* required */
      },
      "SmartAdAdjustment" : { /* SmartAdAdjustmentAdd */
        "BidModifier": (int) /* required */
      },
      "SerpLayoutAdjustments": [{  /* SerpLayoutAdjustmentAdd */
        "SerpLayout": ( "ALONE" | "SUGGEST" ), /* required */
        "BidModifier": (int) /* required */
      }, ... ],
      "IncomeGradeAdjustments": [{  /* IncomeGradeAdjustmentAdd */
        "Grade": ( "VERY_HIGH" | "HIGH" | "ABOVE_AVERAGE" ), /* required */
        "BidModifier": (int) /* required */
      }, ... ],
      "AdGroupAdjustment" : {
        "BidModifier" : (int) /* required */
      }
      "CampaignId": (long),
      "AdGroupId": (long)
    }, ... ] /* required */
  }
}

Parameter

Type

Description

Mandatory

params structure (for JSON) / AddRequest structure (for SOAP)

BidModifiers

array of BidModifierAddItem

Adjustments to add. Maximum of 1000 items in the array.

Yes

BidModifierAddItem structure

CampaignId

long

The campaign ID. Specified when creating bid adjustments at the campaign level.

Use either CampaignId or AdGroupId

AdGroupId

long

ID of the ad group. Specified when creating bid adjustments at the group level.

MobileAdjustment

MobileAdjustmentAdd

Adjustment on mobile phones.

One of the following: MobileAdjustment, TabletAdjustment, DesktopAdjustment, DesktopOnlyAdjustment, DemographicsAdjustments, RetargetingAdjustments, RegionalAdjustments, VideoAdjustment, SmartAdAdjustment, SerpLayoutAdjustments, IncomeGradeAdjustments, AdGroupAdjustment.

TabletAdjustment

TabletAdjustmentAdd

Adjustment on tablets.

DesktopAdjustment

DesktopAdjustmentAdd

Adjustment on desktops and Smart TVs.

DesktopOnlyAdjustment

DesktopOnlyAdjustmentAdd

Adjustment only on desktops.

DemographicsAdjustments

array of DemographicsAdjustmentAdd

Adjustments for gender and age. Maximum of 12 items in the array.

RetargetingAdjustments

array of RetargetingAdjustmentAdd

Adjustments for the target audience. Maximum of 100 items in the array.

RegionalAdjustments

array of RegionalAdjustmentAdd

Regional bid adjustments.

VideoAdjustment

VideoAdjustmentAdd

Adjustment for video extensions.

SmartAdAdjustment

SmartAdAdjustmentAdd

Bid adjustment for smart ads.

SerpLayoutAdjustments

array of SerpLayoutAdjustmentAdd

Adjustments for exclusive placement.

IncomeGradeAdjustments

array of IncomeGradeAdjustmentAdd

Adjustments for income.

AdGroupAdjustment

array of AdGroupAdjustmentAdd

Group-level adjustments.

MobileAdjustmentAdd structure

BidModifier

int

Value of the bid coefficient for displaying ads on mobile phones.

Specified as a percent:

  • From 0 to 1300 for bid adjustments in all types of campaigns and ad groups.

The bid is multiplied by the value of BidModifier/100.

Yes

OperatingSystemType

OperatingSystemTypeEnum

The type of operating system.

If this parameter is omitted, any operating system is acceptable.

No

TabletAdjustmentAdd structure

BidModifier

int

The value of the bid coefficient for serving ads on tablets.

Specified as a percent:

  • From 0 to 1300 for bid adjustments in all types of campaigns and ad groups.

The bid is multiplied by the value of BidModifier/100.

Yes

OperatingSystemType

OperatingSystemTypeEnum

The type of operating system.

If this parameter is omitted, any operating system is acceptable.

No

DesktopAdjustmentAdd structure

BidModifier

int

The value of the bid coefficient for serving ads on desktops and Smart TVs.

Specified as a percent:

  • From 0 to 1300 for bid adjustments in all types of campaigns and ad groups.

The bid is multiplied by the value of BidModifier/100.

Within a single ad group, you can't set the coefficient to 0 for mobile phones without specifying the OS and simultaneously set it to 0 for computers, tablets, and Smart TVs.

Yes

DesktopOnlyAdjustmentAdd structure

BidModifier

int

The value of the bid coefficient for serving ads only on desktops.

Specified as a percent:

  • From 0 to 1300 for bid adjustments in all types of campaigns and ad groups.

The bid is multiplied by the value of BidModifier/100.

Within a single ad group, you can't set the coefficient to 0 for mobile phones without specifying the OS and simultaneously set it to 0 for desktops.

Yes

DemographicsAdjustmentAdd structure

Gender

GenderEnum

The user's gender: GENDER_MALE or GENDER_FEMALE.

If this parameter is omitted, any gender is assumed (in this case, the Age parameter must be specified).

At least one of the Gender or Age parameters.

Age

AgeRangeEnum

The user's age group: one of the values AGE_0_17, AGE_18_24, AGE_25_34, AGE_35_44, AGE_45_54 or AGE_55.

The value AGE_45 has been deprecated. We recommend creating separate adjustments for AGE_45_54 and AGE_55.

If this parameter is omitted, any age is assumed (in this case, the Gender parameter must be specified).

Alert

The audience segments that have bid adjustments set for them must not coincide with each other or overlap. For example, you can't set simultaneous adjustments for the AGE_25_34 and the GENDER_MALE+AGE_25_34 groups.

BidModifier

int

The value of the bid coefficient for displaying ads to users of the specified gender and/or age group.

Indicated as a percentage from 0 to 1300. The bid is multiplied by the value of BidModifier/100.

Yes

RetargetingAdjustmentAdd structure

RetargetingConditionId

long

ID of the retargeting list. The list must have the RETARGETING type. See the section Retargeting list (RetargetingList).

Yes

BidModifier

int

The value of the bid coefficient for serving ads to users who match the retargeting list.

Indicated as a percentage from 0 to 1300. The bid is multiplied by the value of BidModifier/100.

Yes

RegionalAdjustmentAdd structure

RegionId

long

ID of the region from the reference list of regions.

To get the list of regions, use the Dictionaries.get method.

Yes

BidModifier

int

Value of the bid coefficient for displaying ads in the specified region.

Indicated as a percentage from 10 to 1300. The bid is multiplied by the value of BidModifier/100.

Yes

VideoAdjustmentAdd structure

BidModifier

int

Value of the bid coefficient for displaying ads with video extensions.

Indicated as a percentage from 50 to 1300. The bid is multiplied by the value of BidModifier/100.

Yes

SmartAdAdjustmentAdd structure

BidModifier

int

Value of the bid coefficient for serving a smart ad with a single product offer.

Indicated as a percentage from 20 to 1300. The bid is multiplied by the value of BidModifier/100.

Yes

SerpLayoutAdjustmentAdd structure

SerpLayout

SerpLayoutEnum

The ad display place:

  • ALONE — Exclusive placement.
  • SUGGEST — Ads in autofill suggestions.

Yes

BidModifier

int

Value of the bid coefficient for serving ads in the specified placement.

It's specified as a percentage from 0 to 1300. The bid is multiplied by the value of BidModifier/100.

Yes

IncomeGradeAdjustmentAdd structure

Grade

IncomeGradeEnum

Income level:

  • VERY_HIGH
  • HIGH
  • ABOVE_AVERAGE

Yes

BidModifier

int

Value of the bid coefficient for serving ads for users with a specific income level.

It's specified as a percentage from 0 to 1300. The bid is multiplied by the value of BidModifier/100.

Yes

AdGroupAdjustmentAdd structure

BidModifier

int

The value of the bid coefficient for serving ads from a specific group.

It's specified as a percentage from 0 to 1300. The bid is multiplied by the value of BidModifier/100.

Yes

Response

Alert

  • Adding adjustments for gender and age for the same campaign or ad group is considered a single operation. If one of the coefficients has an error, none of them are created.

  • Adding target audience adjustments for the same campaign or ad group is considered a single operation. If one of the coefficients has an error, none of them are created.

  • Adding regional bid adjustments for the same campaign is considered a single operation. If one of the coefficients has an error, none of them are created.

Response structure in JSON format:

{
  "result": { /* result */
    "AddResults": [{  /* MultiIdsActionResult */
      "Ids": [(long), ... ],
      "Warnings": [{  /* ExceptionNotification */
        "Code": (int), /* required */
        "Message": (string), /* required */
        "Details": (string)
      }, ... ],
      "Errors": [{  /* ExceptionNotification */
        "Code": (int), /* required */
        "Message": (string), /* required */
        "Details": (string)
      }, ... ]
    }, ... ]
  }
}

Parameter

Type

Description

result structure (for JSON) / AddResponse structure (for SOAP)

AddResults

array of MultiIdsActionResult

Results of adding bid adjustments.

MultiIdsActionResult structure

Ids

array of long

IDs of the created adjustments. Returned if there aren't any errors. See the section Operations on object arrays. Returned in the same order as the adjustments were listed in the request.

Warnings

array of ExceptionNotification

Warnings that occurred during the operation.

Errors

array of ExceptionNotification

Errors that occurred during the operation.

Examples

Request example

    {
      "method": "add",
      "params": {
        "BidModifiers": [
          { // 1. Two bid adjustments, by gender and age
            "CampaignId": 10001,
            "DemographicsAdjustments": [
              {
                "Gender": "GENDER_MALE",
                "Age": "AGE_25_34",
                "BidModifier": 101
              },
              {
                "Age": "AGE_45_54",
                "BidModifier": 140
              }
            ]
          },
          { // 2. Bid adjustments with overlapping audience segments
            "CampaignId": 10002,
            "DemographicsAdjustments": [
              {
                "Gender": "GENDER_MALE",
                "Age": "AGE_25_34",
                "BidModifier": 120
              },
              {
                "Age": "AGE_25_34",
                "BidModifier": 170
              }
            ]
          },
          { // 3. Invalid coefficient value
            "CampaignId": 10003,
            "DemographicsAdjustments": [
              {
                "Gender": "GENDER_MALE",
                "Age": "AGE_25_34",
                "BidModifier": 120
              },
              {
                "Gender": "GENDER_FEMALE",
                "Age": "AGE_35_44",
                "BidModifier": 10000
              }
            ]
          },
          { // 4. Adjustment for target audience set at the ad group level
            "AdGroupId": 500001,
            "RetargetingAdjustments": [
              {
                "RetargetingConditionId": 2004,
                "BidModifier": 201
              }
            ]
          }
        ]
      }
    }

Response example

    {
      "result" : {
        "AddResults" : [
          { // 1. Two bid adjustments created: by gender and age
            "Ids": [ 1003, 1004 ]
          },
          { // 2. Overlapping segments: no adjustments were created
            "Errors": [
              {
                "Code": 6000,
                "Message": "Inconsistent object state",
                 "Details": "Overlapping bid adjustment criteria in the set"
              }
            ]
          },
          { // 3. Invalid value: no adjustments were created
            "Errors": [
              {
                "Code": 5005,
                "Message": "Field set incorrectly",
                "Details": "Coefficient can't be more than 1300"
              }
            ]
          },
          { // 4. Bid adjustment for target audience created at the ad group level
            "Ids": [ 1005 ]
          }
        ]
      }
    }