Campaign Data Object - Campaign Management

Defines a campaign.

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 minOccurs="0" name="ExperimentId" nillable="true" type="xs:long" />
    <xs:element minOccurs="0" name="FinalUrlSuffix" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="ForwardCompatibilityMap" nillable="true" type="q4:ArrayOfKeyValuePairOfstringstring" xmlns:q4="http://schemas.datacontract.org/2004/07/System.Collections.Generic" />
    <xs:element minOccurs="0" name="Id" nillable="true" type="xs:long" />
    <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 minOccurs="0" name="Languages" nillable="true" type="q5:ArrayOfstring" xmlns:q5="http://schemas.microsoft.com/2003/10/Serialization/Arrays" />
  </xs:sequence>
</xs:complexType>

Elements

Element Description Data Type
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.

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. A bid strategy type set at the AdGroup or Keyword level will take precedence over the campaign level bid strategy type.

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

IMPORTANT: If the campaign bid strategy type is set to MaxClicks, MaxConversions, or TargetCpa, the behavior of existing features will change unless you set an individual ad group's or keyword's bid strategy to ManualCpc.
- You can continue to set the ad group and keyword bids; however they will not be used by Bing Ads.
- Bing Ads will periodically change your stored ad group or keyword bid settings. You can continue to set new bids, however Bing Ads may change them at any time using this bid strategy type.
- You can continue to set bid adjustments e.g. for age, gender, or location; however, the multiplier will inform rather than directly modify or override the automated bid. For auto bidding the multiplier is used as a weighted percentage to inform Bing Ads about how much you value the criterion relative to other criteria. For example, a -50% bid multiplier for a mobile device criterion with the Max Conversions bid strategy to indicate that you value conversions from mobile traffic half as much as other device types. The same bid multiplier with the Max Clicks bid strategy would indicate that you value clicks on mobile half as much as other device types. The valid range of values that you can use to inform auto bidding is -100.00 through 30.00.

Also note that you must have conversion tracking (via Universal Event Tracking tag and a conversion goal) set up for the MaxConversions and TargetCpa bid strategy types to work. To set the MaxConversions or TargetCpa bid strategy types, the campaign must have at least 15 conversions in the last 30 days. If you try to add or update a campaign to use one of these strategy types, the requested operation will fail if there is not enough conversion history. If an active campaign uses one of these bid strategy types, and then ceases to meet the minimum conversion history requirement at any time, Bing Ads will stop auto bidding but will continue to use the DailyBudgetStandard budget type. For a new campaign we recommend that you start with EnhancedCpc and then when the campaign has enough conversion history, you can update it to use either the MaxConversions or TargetCpa bid strategy.

Tip: You can set your campaign's bid strategy to EnhancedCpcBiddingScheme, MaxClicksBiddingScheme, MaxConversionsBiddingScheme, or TargetCpaBiddingScheme and then, at any time, set an individual ad group's or keyword's bid strategy to Manual CPC (ManualCpcBiddingScheme).

Add: Optional. The default value for Search and DynamicSearchAds campaigns is EnhancedCpc. The default value for Shopping campaigns is ManualCpc. The only supported value for Audience campaigns is ManualCpc.
Update: Optional. If no value is set for the update, this setting is not changed.
BiddingScheme
BudgetId The unique Bing Ads 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.

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.

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.

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, or Shopping campaign.

Add: Required for Audience campaigns, and otherwise this element is optional. If not specified, then default value of Search is used and you cannot set Audience, Dynamic Search Ads, or Shopping campaign settings.
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. Bing Ads anticipates and automatically compensates for the fluctuations, and usually keeps overspend to less than 100% above your daily limit.

Also note that Bing Ads 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.

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
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 update the Budget, BudgetType, or TimeZone. The budget and time zone 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.

This feature is only available for customers in the Final URL Suffix Phase 1 pilot (GetCustomerPilotFeatures returns 533). If you are not in the pilot and attempt to set this property an error will be returned. During calendar year 2019 this feature will be enabled for all customers.

Add: Optional
Update: Optional. If no value is set for the update, this setting is not changed.
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
Id The unique Bing Ads identifier of the campaign.

Add: Read-only
Update: Required
long
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.

The supported language strings for Search and Shopping campaigns are: All, Danish, Dutch, English, Finnish, French, German, Italian, Norwegian, Portuguese, Spanish, Swedish, and TraditionalChinese. 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.

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

For Dynamic Search Ads campaigns, only English is supported.

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
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 settings will vary by campaign type.

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

If the CampaignType element is Search, then this element must be nil or empty. If the CampaignType element is Shopping, this list will include a ShoppingSetting object. If the CampaignType element is 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 element is DynamicSearchAds, this list will include a DynamicSearchAdsSetting object.

The TargetSetting can be used with any campaign type (for pilot customers only), 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 supporrted CriterionTypeGroup. The only criterion type value currently supported for the campaign level target setting is "Audience".

Add: 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.
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.

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.

This element is only applicable for campaigns of type Shopping, and will be nil for all other campaign types.

We are introducing Cooperative campaigns during calendar year 2018 as a sub type of Bing Shopping campaigns. More details about Cooperative campaigns are coming soon, and whether or not you plan to adopt Cooperative campaigns, you might need to make code changes if your application supports any Bing Shopping campaigns.

When you call GetCampaignsByAccountId or GetCampaignsByIds and if the CampaignType is set to Shopping, please also check the SubType of each campaign. If the SubType is not set then it is a standard Bing Shopping campaign. If the value is set to ShoppingCoOperative, the campaign is a Cooperative campaign with different requirements.

Add: Not applicable for most campaign types. For Cooperative campaigns you must set the sub type to ShoppingCoOperative.
Update: Read-only
string
TimeZone 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.

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 Bing Ads 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 Hierarchy and 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}.
- Bing Ads 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 http://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.
string
UrlCustomParameters Your custom collection of key and value parameters for URL tracking.

Bing Ads will accept the first 3 CustomParameter objects that you include within the CustomParameters object, and any additional custom parameters will be ignored. Each CustomParameter includes Key and Value elements. For customers in the Custom Parameters Limit Increase Phase 1 pilot (GetCustomerPilotFeatures returns 532), Bing Ads will accept the first 8 custom parameter key and value pairs that you include, and if you include more than 8 custom parameters an error will be returned. During calendar year 2019 the limit will be increased from 3 to 8 for all customers.

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