Edit

Share via

Campaign Data Object - Campaign Management

  • Article

Defines a campaign.

Note

You can no longer add, update, or retrieve campaigns that only support dynamic search ads. The campaign type of your existing campaigns has been updated from "DynamicSearchAds" to "Search". The ad groups are now considered "dynamic" ad groups, but there are no structural changes i.e., they contain the same auto targets and dynamic search ads as before.

Note

As of April 2021, the manual CPC bid strategy can only be used with audience campaigns and Lodging campaigns (formerly Hotel campaigns). If you attempt to set manual CPC for any other campaign type, the request will be ignored without error and the bid strategy will be set to enhanced CPC.

As of April 2021, you cannot set any bid strategies for ad groups or keywords. Bid strategies can only be set at the campaign level. If you attempt to set bid strategies for ad groups or keywords, the request will be ignored without error. Ad groups and keywords will inherit their campaign's bid strategy.

Syntax

<xs:complexType name="Campaign" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:sequence>
    <xs:element minOccurs="0" name="AudienceAdsBidAdjustment" nillable="true" type="xs:int" />
    <xs:element minOccurs="0" name="BiddingScheme" nillable="true" type="tns:BiddingScheme" />
    <xs:element minOccurs="0" name="BudgetType" nillable="true" type="tns:BudgetLimitType" />
    <xs:element minOccurs="0" name="DailyBudget" nillable="true" type="xs:double" />
    <xs:element xmlns:q8="http://schemas.microsoft.com/2003/10/Serialization/Arrays" minOccurs="0" name="DealIds" nillable="true" type="q8:ArrayOflong">
      <xs:annotation>
        <xs:appinfo>
          <DefaultValue EmitDefaultValue="false" xmlns="http://schemas.microsoft.com/2003/10/Serialization/" />
        </xs:appinfo>
      </xs:annotation>
    </xs:element>
    <xs:element minOccurs="0" name="ExperimentId" nillable="true" type="xs:long" />
    <xs:element minOccurs="0" name="FinalUrlSuffix" nillable="true" type="xs:string" />
    <xs:element xmlns:q9="http://schemas.datacontract.org/2004/07/System.Collections.Generic" minOccurs="0" name="ForwardCompatibilityMap" nillable="true" type="q9:ArrayOfKeyValuePairOfstringstring" />
    <xs:element xmlns:q10="http://schemas.microsoft.com/2003/10/Serialization/Arrays" minOccurs="0" name="GoalIds" nillable="true" type="q10:ArrayOflong">
      <xs:annotation>
        <xs:appinfo>
          <DefaultValue EmitDefaultValue="false" xmlns="http://schemas.microsoft.com/2003/10/Serialization/" />
        </xs:appinfo>
      </xs:annotation>
    </xs:element>
    <xs:element minOccurs="0" name="Id" nillable="true" type="xs:long" />
    <xs:element minOccurs="0" name="IsDealCampaign" nillable="true" type="xs:boolean">
      <xs:annotation>
        <xs:appinfo>
          <DefaultValue EmitDefaultValue="false" xmlns="http://schemas.microsoft.com/2003/10/Serialization/" />
        </xs:appinfo>
      </xs:annotation>
    </xs:element>
    <xs:element minOccurs="0" name="MultimediaAdsBidAdjustment" nillable="true" type="xs:int">
      <xs:annotation>
        <xs:appinfo>
          <DefaultValue EmitDefaultValue="false" xmlns="http://schemas.microsoft.com/2003/10/Serialization/" />
        </xs:appinfo>
      </xs:annotation>
    </xs:element>
    <xs:element minOccurs="0" name="Name" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="Status" nillable="true" type="tns:CampaignStatus" />
    <xs:element minOccurs="0" name="SubType" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="TimeZone" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="TrackingUrlTemplate" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="UrlCustomParameters" nillable="true" type="tns:CustomParameters" />
    <xs:element minOccurs="0" name="CampaignType" nillable="true" type="tns:CampaignType" />
    <xs:element minOccurs="0" name="Settings" nillable="true" type="tns:ArrayOfSetting" />
    <xs:element minOccurs="0" name="BudgetId" nillable="true" type="xs:long" />
    <xs:element xmlns:q11="http://schemas.microsoft.com/2003/10/Serialization/Arrays" minOccurs="0" name="Languages" nillable="true" type="q11:ArrayOfstring" />
    <xs:element minOccurs="0" name="AdScheduleUseSearcherTimeZone" nillable="true" type="xs:boolean">
      <xs:annotation>
        <xs:appinfo>
          <DefaultValue EmitDefaultValue="false" xmlns="http://schemas.microsoft.com/2003/10/Serialization/" />
        </xs:appinfo>
      </xs:annotation>
    </xs:element>
    <xs:element minOccurs="0" name="BidStrategyId" nillable="true" type="xs:long">
      <xs:annotation>
        <xs:appinfo>
          <DefaultValue EmitDefaultValue="false" xmlns="http://schemas.microsoft.com/2003/10/Serialization/" />
        </xs:appinfo>
      </xs:annotation>
    </xs:element>
  </xs:sequence>
</xs:complexType>

Elements

The Campaign object has the following elements: AdScheduleUseSearcherTimeZone, AudienceAdsBidAdjustment, BiddingScheme, BidStrategyId, BudgetId, BudgetType, CampaignType, DailyBudget, DealIds, ExperimentId, FinalUrlSuffix, ForwardCompatibilityMap, GoalIds, Id, IsDealCampaign, Languages, MultimediaAdsBidAdjustment, Name, Settings, Status, SubType, TimeZone, TrackingUrlTemplate, UrlCustomParameters.

Element Description Data Type
AdScheduleUseSearcherTimeZone Determines whether to use the account time zone or the time zone of the search user where the ads could be delivered.

Set this property to true if you want the ads to be shown in the search user's time zone, and otherwise set it to false.

This element is not returned by default. To get this element, include the AdScheduleUseSearcherTimeZone value in the ReturnAdditionalFields element when you call the GetCampaignsByAccountId and GetCampaignsByIds service operations.

Add: Optional. If you do not specify this element or leave it empty, the default value of false will be set and the account time zone will be used.
Update: Optional. If no value is set for the update, this setting is not changed.		 boolean
AudienceAdsBidAdjustment The percent amount by which to adjust your bid for audience ads above or below the base ad group or keyword bid.

This property is available in Search campaigns if the customer is enabled for the Microsoft Audience Network. This property is not available with smart shopping campaigns.

Supported values are negative one hundred (-100) through positive nine hundred (900). Setting the bid adjustment to -100 will prevent audience ads from showing for this campaign.

Set this element to zero (0) if you want to use the base ad group or keyword bid instead of specifying any bid adjustment for audience ads.

As a best practice you should always specify a bid adjustment value. If you set this element to null the system default bid adjustment will be used. The system default bid adjustment is currently zero (0), and is subject to change.

Add: Optional
Update: Optional. If no value is set for the update, this setting is not changed.		 int
BiddingScheme The bid strategy type for how you want to manage your bids.

For details about supported bid strategies per campaign type, see Budget and Bid Strategies.

IMPORTANT: For some bid strategy types your bid and ad rotation settings are ignored and conversion tracking (via Universal Event Tracking tag and a conversion goal) is required. For more information including supported locations, see Let Microsoft Advertising manage your bids with bid strategies.

This element will be nil or empty by default if the campaign uses the MaxConversionValueBiddingScheme or TargetImpressionShareBiddingScheme bid strategy. To get the MaxConversionValueBiddingScheme or TargetImpressionShareBiddingScheme objects, include the respective MaxConversionValueBiddingScheme and TargetImpressionShareBiddingScheme values in the ReturnAdditionalFields element when you call the GetCampaignsByAccountId and GetCampaignsByIds service operations.

Add: Optional. The default bid strategy type for Search and DynamicSearchAds campaigns is EnhancedCpcBiddingScheme. The default bid strategy type for most Shopping campaigns is EnhancedCpcBiddingScheme; however, the only supported bid strategy types for smart shopping campaigns are MaxConversionsBiddingScheme and MaxConversionValueBiddingScheme. The supported bid strategy types for Audience campaigns are EnhancedCpcBiddingScheme, ManualCpcBiddingScheme, ManualCpmBiddingScheme, and TargetCpaBiddingScheme. The supported bid strategy types for lodging campaigns are CommissionBiddingScheme, ManualCpcBiddingScheme, and PercentCpcBiddingScheme. The supported bid strategies for Performance Max campaigns are MaxConversionsBiddingScheme (with optional TCPA) and MaxConversionValueBiddingScheme (with optional TROAS). The supported bid strategies for new Video campaigns are ManualCpmBiddingScheme and ManualCpvBiddingScheme. NOTE: As of May 2024, you can no longer use the manual CPC bid strategy for audience native campaigns. You can only use manual CPC for audience display and video campaigns, and for lodging campaigns. We will automatically convert any existing manual CPC audience native campaigns to enhanced CPC. If you attempt to set manual CPC for any other campaign type, the request will be ignored without error and the bid strategy will be set to enhanced CPC. As of April 2021, you cannot set any bid strategies for ad groups or keywords. Bid strategies can only be set at the campaign level. If you attempt to set bid strategies for ad groups or keywords, the request will be ignored without error. Ad groups and keywords will inherit their campaign's bid strategy.
Update: Optional. If no value is set for the update, this setting is not changed.		 BiddingScheme
BidStrategyId The system-generated identifier of the BidStrategy that this campaign shares with other campaigns in the account.

If the field is empty, then the campaign is not using a portfolio bid strategy. If the field is not empty and the value is greater than zero, then the campaign is using a portfolio bid strategy. If the campaign is using a portfolio bid strategy, and you prefer that it use its own bid strategy, set this field to '0' (zero).

Note: Portfolio bid strategies are not supported with smart shopping campaigns or Performance Max campaigns.

Add: Optional
Update: Optional. If no value is set for the update, this setting is not changed.		 long
BudgetId The unique Microsoft Advertising identifier of the Budget that this campaign shares with other campaigns in the account.

If the value is not null and greater than zero, then the campaign is using a shared budget. If the value is null, then the campaign is not using a shared budget. If the campaign is using a shared budget, and you prefer that it use its own budget e.g. DailyBudget amount, set this element to '0' (zero) and set DailyBudget to a valid budget amount.

Note: Shared budgets are not supported with smart shopping campaigns or Performance Max campaigns. With smart shopping campaigns, you must set the DailyBudget amount.

Add: Optional
Update: Optional. If no value is set for the update, this setting is not changed.		 long
BudgetType The budget type determines how the budget is spent.

The possible values are DailyBudgetAccelerated and DailyBudgetStandard. The DailyBudgetAccelerated budget type is only available for Audience campaigns that use unshared campaign-level budgets.

In the context of shared budgets, the budget type is a read-only property that is always returned regardless of whether or not the campaign uses a shared budget. To determine whether the campaign uses a shared budget, check the value of the BudgetId element as described above.

With experiment campaigns you cannot set the Budget, BudgetType, or Status. The budget, and status of an experiment campaign are always inherited from the base campaign settings.

Add: Required if the BudgetId is not set. Read-only if the campaign uses a shared budget.
Update: Optional if the BudgetId is not set. If no value is set for the update, this setting is not changed. Not allowed if the campaign uses a shared budget. If you try to update the budget type of a campaign that has a shared budget, the service will return the CampaignServiceCannotUpdateSharedBudget error code.		 BudgetLimitType
CampaignType The campaign type determines whether the campaign is an Audience, Dynamic Search Ads, Search, Shopping campaign, Hotel Ads, or Performance Max.

Add: Optional. If not specified, then default value of Search is used.
Update: Not allowed.		 CampaignType
DailyBudget The amount to spend daily on the campaign.

You must set the daily budget amount if BudgetId is not set.

Your budget is a target; your actual spend might be higher or lower. Variations are caused by a number of factors, such as different traffic volumes in different days of the week, or automatic detection and refunding of fraud clicks that can give money back to a campaign within a few hours of the click. Microsoft Advertising anticipates and automatically compensates for the fluctuations, and usually keeps overspend to less than 100% above your daily limit.

Also note that Microsoft Advertising does not require your campaign budget to be higher than the ad group and keyword bids. In other words ad group and keyword bids are validated independently of the campaign budget.

In the context of shared budgets, the budget amount is a read-only property that is always returned regardless of whether or not the campaign uses a shared budget. When a campaign is associated to a shared budget the amount returned is that of the shared budget. To determine whether the campaign uses a shared budget, check the value of the BudgetId element as described above.

With experiment campaigns you cannot set the Budget, BudgetType, or Status. The budget, and status of an experiment campaign are always inherited from the base campaign settings.

Add: Required if the BudgetId is not set. Read-only if the campaign uses a shared budget.
Update: Optional if the BudgetId is not set. If no value is set for the update, this setting is not changed. Not allowed if the campaign uses a shared budget. If you try to update the budget amount of a campaign that has a shared budget, the service will return the CampaignServiceCannotUpdateSharedBudget error code.		 double
DealIds A list of unique system identifiers corresponding to the deals that were added.

The list of identifiers corresponds directly to the list of deals in the request. Items of the list may be returned as null. For each list index where a deal was not added, the corresponding element will be null.		 long array
ExperimentId The system-generated identifier of the Experiment.

This element is only set for experiment campaigns i.e., campaigns that have been created for A/B testing based on another Search campaign.

Base campaigns will not contain an experiment ID. Likewise, after an experiment has been Graduated to an independent campaign, this element will be empty, even though the campaign was previously an experiment campaign.

With experiment campaigns you cannot set the Budget, BudgetType, or Status. The budget, and status of an experiment campaign are always inherited from the base campaign settings. If you want to change an experiment's budget, you will need to change the base campaign's budget. The change in value will then be split based on your experiment TrafficSplitPercent setting.

Add: Read-only
Update: Read-only		 long
FinalUrlSuffix The final URL suffix can include tracking parameters that will be appended to the end of your landing page URL. We recommend placing tracking parameters that your landing page requires in a final URL suffix so that your customers are always sent to your landing page. For more details and validation rules see Final URL Suffix in the technical guides.

Add: Optional
Update: Optional. If no value is set for the update, this setting is not changed. If you set this element to an empty string (""), the previous setting will be deleted.		 string
ForwardCompatibilityMap The list of key and value strings for forward compatibility to avoid otherwise breaking changes when new elements are added in the current API version.

Forward compatibility changes will be noted here in future releases. There are currently no forward compatibility changes for this object.		 KeyValuePairOfstringstring array
GoalIds A list of goal IDs. long array
Id The unique Microsoft Advertising identifier of the campaign.

Add: Read-only
Update: Required		 long
IsDealCampaign The campaign is a deal campaign if true. boolean
Languages Your ad language setting determines the language you will use when you write your ads and should be the language of your customers.

IMPORTANT: If languages are set at both the ad group and campaign level, the ad group level language will override the campaign level language.

You can specify multiple languages individually in the list, or only include one list item set to All if you want to target all languages.

The supported language strings for Search and Shopping campaigns are: Albanian, Bulgarian, Croatian, Czech, Danish, Dutch, English, Estonian, Finnish, French, German, Greek, Hungarian, Italian, Japanese, Latvian, Lithuanian, Maltese, Norwegian, Polish, Portuguese, Romanian, Slovak, Slovenian, Spanish, Swedish, and TraditionalChinese.

NOTE: The following languages are not yet available for everyone: Bulgarian, Croatian, Czech, Estonian, Greek, Hungarian, Japanese, Latvian, Lithuanian, Maltese, Polish, Romanian, Slovak, Slovenian.

For Audience campaigns you must include all languages i.e., set this element to All.

For Dynamic Search Ads campaigns, the campaign and ad group level language settings are ignored in favor of the website domain language. You should set campaign languages to "All" and leave the ad group level language empty.

Add: Required for Audience campaigns, and otherwise this element is optional. If there is no campaign language set, then the language of each ad group within the campaign will be required.
Update: Optional. If no value is set for the update, this setting is not changed. Once campaign languages are set, you cannot delete all of them. The list of languages that you specify during update replaces the previous settings i.e. does not append to the existing set of languages.		 string array
MultimediaAdsBidAdjustment The percent amount by which to adjust your bid for multimedia ads above or below the base ad group or keyword bid int
Name The name of the campaign. The name must be unique among all active or paused campaigns within the account. The name can contain a maximum of 128 characters.

The service performs a case-insensitive comparison when it compares the name to existing campaign names.

Add: Required
Update: Optional. If no value is set for the update, this setting is not changed.		 string
Settings The supported settings that vary by campaign type.

Note: VerifiedTrackingSetting is not currently available.

You can include a maximum of one object per setting type in the list of settings e.g., one TargetSetting.

If the CampaignType is set to Search and if the ExperimentId element is not set, this list can optionally include a DynamicSearchAdsSetting object. Experiment campaigns and base campaigns of experiments cannot include dynamic search ads settings. If you intend to use this campaign for experiments, do not include dynamic search ads settings. If an existing experiment is already based on this campaign, you cannot update the campaign to include dynamic search ads settings.

If the CampaignType is set to Shopping, this list must include a ShoppingSetting object.

If the CampaignType is set to Audience, this list may or may not include a ShoppingSetting object, depending on whether or not the Audience campaign supports product ads.

If the CampaignType is set to DynamicSearchAds, this list must include a DynamicSearchAdsSetting object.

If the CampaignType is set to Hotel, this list must include a HotelSetting object.

If the CampaignType is set to PerformanceMax, this list must include a PerformanceMaxSetting object. If the Performance Max campaign associates to a store, it also supports a ShoppingSetting.

The TargetSetting can be used with any campaign type except Performace Max, and determines whether the Audience criterions associated with this campaign use the "target and bid" option or the "bid only" target option. Within the TargetSetting you can have one TargetSettingDetail objects i.e., one per supported CriterionTypeGroup. The only criterion type value currently supported for the campaign level target setting is "Audience". The TargetSetting object is not returned by default. To get this object, include the TargetSetting value in the ReturnAdditionalFields element when you call the GetCampaignsByAccountId and GetCampaignsByIds service operations.

Add: Required if the CampaignType is set to DynamicSearchAds or Shopping, and otherwise this element is optional. If this element does not include a TargetSetting object, the default bid option for all criterion type groups is effectively "bid only".
Update: Optional. If no value is set for the update, this setting is not changed. The DynamicSearchAdsSetting and ShoppingSetting objects cannot be removed during update.		 Setting array
Status The status of the campaign.

Possible values are Active and Paused.

The service will automatically pause the campaign if the budget is depleted.

With experiment campaigns you cannot set the Budget, BudgetType, or Status The budget, and status of an experiment campaign are always inherited from the base campaign settings.

Add: Optional. The default value is Paused.
Update: Optional. If no value is set for the update, this setting is not changed.		 CampaignStatus
SubType The campaign sub type.

If the sub type is not set, the campaign is created according to the campaign type.

If the sub type is set to AudienceVideoAds and the campaign type is Audience, the campaign is a video audience campaign.

If the sub type is set to ShoppingSmartAds, the campaign is a Microsoft Smart Shopping campaign.

If the sub type is set to ShoppingSponsoredProductAd, the campaign is a Microsoft shopping campaigns for brands.

Add: Optional and not applicable for most campaign types. For Microsoft smart shopping campaigns you must set the sub type to ShoppingSmartAds. For Microsoft shopping campaigns for brands you must set the sub type to ShoppingSponsoredProductAd.
Update: Read-only		 string
TimeZone This column is deprecated.

The time zone where the campaign operates.

The time zone is used for reporting and applying the start and end date of an ad group.

For possible values, see Time Zones.

With experiment campaigns you cannot set the Budget, BudgetType, Status, or TimeZone. The budget, status, and time zone of an experiment campaign are always inherited from the base campaign settings.

Add: Required
Update: Optional. If no value is set for the update, this setting is not changed. You may not update the time zone if the campaign contains or has ever contained ad groups in the Active or Paused state.		 string
TrackingUrlTemplate The tracking template to use as a default for all URLs in your campaign.

The following validation rules apply to tracking templates. For more details about supported templates and parameters, see the Microsoft Advertising help article What tracking or URL parameters can I use?
- Tracking templates defined for lower level entities e.g. ads override those set for higher level entities e.g. campaign. For more information, see Entity Limits.
- The length of the tracking template is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit.
- The tracking template must be a well-formed URL beginning with one of the following: http://, https://, {lpurl}, or {unescapedlpurl}.
- Microsoft Advertising does not validate whether custom parameters exist. If you use custom parameters in your tracking template and they do not exist, then the landing page URL will include the key and value placeholders of your custom parameters without substitution. For example, if your tracking template is https://tracker.example.com/?season={_season}&promocode={_promocode}&u={lpurl} and neither {_season} or {_promocode} are defined at the campaign, ad group, criterion, keyword, or ad level, then the landing page URL will be the same.

Add: Optional
Update: Optional. If no value is set for the update, this setting is not changed. If you set this element to an empty string (""), the previous setting will be deleted.		 string
UrlCustomParameters Your custom collection of key and value parameters for URL tracking.

Microsoft Advertising will accept the first 8 CustomParameter objects that you include within the CustomParameters object, and if you include more than 8 custom parameters an error will be returned. Each CustomParameter includes Key and Value elements.

Add: Optional
Update: Optional. If no value is set for the update, this setting is not changed. Set the UrlCustomParameters element to null or empty to retain any existing custom parameters. To remove all custom parameters, set the Parameters element of the CustomParameters object to null or empty. To remove a subset of custom parameters, specify the custom parameters that you want to keep in the Parameters element of the CustomParameters object.		 CustomParameters

Requirements

Service: CampaignManagementService.svc v13
Namespace: https://bingads.microsoft.com/CampaignManagement/v13

Used By

AddCampaigns
GetCampaignsByAccountId
GetCampaignsByIds
UpdateCampaigns