Edit

Share via

PromotionAdExtension Data Object - Campaign Management

  • Article

Promotion Extensions highlight special sales and offers in your text ads. By making offers stand out, potential customers are more likely to click on your ad, helping to generate more sales for you.

You can associate a promotion ad extension with the account or with campaigns and ad groups in the account. Each entity (account, campaign, or ad group) can be associated with up to 20 promotion ad extensions.

Note

Promotion Extensions are available for customers in AU, CA, DE, FR, US and UK.

Syntax

<xs:complexType name="PromotionAdExtension" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:complexContent mixed="false">
    <xs:extension base="tns:AdExtension">
      <xs:sequence>
        <xs:element minOccurs="0" name="CurrencyCode" nillable="true" type="xs:string" />
        <xs:element minOccurs="0" name="DiscountModifier" nillable="true" type="tns:PromotionDiscountModifier" />
        <xs:element minOccurs="0" name="FinalAppUrls" nillable="true" type="tns:ArrayOfAppUrl" />
        <xs:element xmlns:q56="http://schemas.microsoft.com/2003/10/Serialization/Arrays" minOccurs="0" name="FinalMobileUrls" nillable="true" type="q56:ArrayOfstring" />
        <xs:element minOccurs="0" name="FinalUrlSuffix" nillable="true" type="xs:string" />
        <xs:element xmlns:q57="http://schemas.microsoft.com/2003/10/Serialization/Arrays" minOccurs="0" name="FinalUrls" nillable="true" type="q57:ArrayOfstring" />
        <xs:element minOccurs="0" name="Language" nillable="true" type="xs:string" />
        <xs:element minOccurs="0" name="MoneyAmountOff" nillable="true" type="xs:double" />
        <xs:element minOccurs="0" name="OrdersOverAmount" nillable="true" type="xs:double" />
        <xs:element minOccurs="0" name="PercentOff" nillable="true" type="xs:double" />
        <xs:element minOccurs="0" name="PromotionCode" nillable="true" type="xs:string" />
        <xs:element minOccurs="0" name="PromotionEndDate" nillable="true" type="tns:Date" />
        <xs:element minOccurs="0" name="PromotionItem" nillable="true" type="xs:string" />
        <xs:element minOccurs="0" name="PromotionOccasion" nillable="true" type="tns:PromotionOccasion" />
        <xs:element minOccurs="0" name="PromotionStartDate" nillable="true" type="tns:Date" />
        <xs:element minOccurs="0" name="TrackingUrlTemplate" nillable="true" type="xs:string" />
        <xs:element minOccurs="0" name="UrlCustomParameters" nillable="true" type="tns:CustomParameters" />
      </xs:sequence>
    </xs:extension>
  </xs:complexContent>
</xs:complexType>

Elements

The PromotionAdExtension object has the following elements: CurrencyCode, DiscountModifier, FinalAppUrls, FinalMobileUrls, FinalUrls, FinalUrlSuffix, Language, MoneyAmountOff, OrdersOverAmount, PercentOff, PromotionCode, PromotionEndDate, PromotionItem, PromotionOccasion, PromotionStartDate, TrackingUrlTemplate, UrlCustomParameters.

Element Description Data Type
CurrencyCode The currency code for the promotion price or discount.

This field is only applicable if you set MoneyAmountOff or OrdersOverAmount.

The supported currency codes are ARS, AUD, BRL, CAD, CHF, CLP, CNY, COP, DKK, EUR, GBP, HKD, INR, MXN, NZD, PEN, PHP, PLN, SEK, SGD, USD, TWD, and VEF.

Add: Required if MoneyAmountOff or OrdersOverAmount are set.
Update: Optional. If no value is set for the update, this setting is not changed. If you set either PercentOff or PromotionCode, this setting is no longer applicable and will be deleted.		 string
DiscountModifier The promotion discount modifier.

For example, let's say the discount modifier is set to UpTo. Then, if the unmodified promotion discount would be "$20 off shoes", the modified promotion is "Up to $20 off shoes."

Add: Optional. If you do not specify this element or leave it empty, the default value of None will be set.
Update: Optional. If no value is set for the update, this setting is not changed.		 PromotionDiscountModifier
FinalAppUrls For future use. AppUrl array
FinalMobileUrls The landing page URL for mobile devices.

The following validation rules apply to Final URLs and Final Mobile URLs.
- The length of the URL is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit.
- You may specify up to 10 list items for both FinalUrls and FinalMobileUrls; however, only the first item in each list is used for delivery. The service allows up to 10 list items for potential forward compatibility.
- Usage of '{' and '}' is only allowed to delineate tags, for example {lpurl}.
- Final URLs must each be a well-formed URL starting with either http:// or https://.
- If you specify FinalMobileUrls, you must also specify FinalUrls.

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 list, the previous setting will be deleted.		 string array
FinalUrls The landing page URL.

The following validation rules apply to Final URLs and Final Mobile URLs.
- The length of the URL is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit.
- You may specify up to 10 list items for both FinalUrls and FinalMobileUrls; however, only the first item in each list is used for delivery. The service allows up to 10 list items for potential forward compatibility.
- Usage of '{' and '}' is only allowed to delineate tags, for example {lpurl}.
- Final URLs must each be a well-formed URL starting with either http:// or https://.
- If you specify FinalMobileUrls, you must also specify FinalUrls.

Add: Required
Update: Optional. If no value is set for the update, this setting is not changed.		 string array
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 3 pilot (GetCustomerPilotFeatures returns 636). If you are not in the pilot this property will be ignored and no error will be returned.

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
Language The language that the ad extension will be served in.

The extension will always be served in this language, regardless of the campaign or ad group's language settings.

The supported language strings are: Danish, Dutch, English, Finnish, French, German, Italian, Norwegian, Portuguese, Spanish, Swedish, and TraditionalChinese.

Add: Required
Update: Optional. If no value is set for the update, this setting is not changed.		 string
MoneyAmountOff The money off promotion value.

For example, to promote "$20 off shoes - On orders over $100", set the PromotionItem to "shoes", set CurrencyCode to "USD", set MoneyAmountOff to 20, and set OrdersOverAmount to 100.

Add: Required. You must set either MoneyAmountOff or PercentOff, but you cannot set both.
Update: Optional. You can set either MoneyAmountOff or PercentOff, but you cannot set both.		 double
OrdersOverAmount The orders over amount value appended to the promotion target.

For example, to promote "$20 off shoes - On orders over $100", set the PromotionItem to "shoes", set CurrencyCode to "USD", set MoneyAmountOff to 20, and set OrdersOverAmount to 100.

Add: Optional. You cannot set both OrdersOverAmount and PromotionCode.
Update: Optional. You cannot set both OrdersOverAmount and PromotionCode. If no value is set for the update, this setting is not changed. If you set this element to '0' (zero), the previous setting will be deleted.		 double
PercentOff The percent off promotion value.

For example, 10.0 represents a 10% discount.

Add: Required. You must set either MoneyAmountOff or PercentOff, but you cannot set both.
Update: Optional. You can set either MoneyAmountOff or PercentOff, but you cannot set both. If you set this property, then the CurrencyCode setting is no longer applicable and will be deleted if it was previously set.		 double
PromotionCode The promotion code appended to the promotion target.

For example, to promote "$20 off shoes - Promocode SAVE20", set the PromotionItem to "shoes", set CurrencyCode to "USD", set MoneyAmountOff to 20, and set PromotionCode to "SAVE20".

The string can contain a maximum of 15 characters.

Add: Optional. You cannot set both OrdersOverAmount and PromotionCode.
Update: Optional. You cannot set both OrdersOverAmount and PromotionCode. 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. If you set this property, then the CurrencyCode setting is no longer applicable and will be deleted if it was previously set.		 string
PromotionEndDate The end date helps to inform the promotion date or dates that will be displayed in the ad.

For example if the PromotionStartDate and PromotionEndDate dates are both set to February 14th, the text "Valid Feb 14" could be included in the displayed promotion.

The PromotionStartDate date must be earlier than, or equal to, the PromotionEndDate date.

This property does not override the inherent delivery range for a promotion. Both the promotion PromotionOccasion and Scheduling determine when the promotion is eligible to be shown in ads.

If the end date has already passed for the current year, then each start and end date must be set for dates during the following year.

Add: Optional
Update: Optional. If no value is set for the update, this setting is not changed. To delete the current end date and effectively set no end date, set the Day, Month, and Year each to '0' (zero). When you retrieve the promotion ad extension next time, this element will not be set.		 Date
PromotionItem The promotion target or item.

For example, you might run a promotion for "shoes" at either $20 or 20% discount. To run a promotion for "Up to $20 off shoes", set the PromotionItem to "shoes", set the DiscountModifier to UpTo, set CurrencyCode to "USD", and set MoneyAmountOff to 20.

The string can contain a maximum of 20 characters.

Add: Required
Update: Optional. If no value is set for the update, this setting is not changed.		 string
PromotionOccasion The promotion occasion.

Both the PromotionOccasion and Scheduling elements determine when the promotion is eligible to be shown in ads.

The PromotionOccasion determines the time period or seasonality e.g., WomensDay from February 15 through March 31 each year. The promotion will only run within the dates corresponding to the occasion that you set. See PromotionOccasion for details about the defined date range for each occasion.

The Scheduling can limit the promotion to a shorter timeframe within the occasion's date range e.g., limit the promotion to run from February 20 through March 8. The Scheduling can also be used to run the same promotion multiple years e.g., run the WomensDay promotion every year from February 15 through March 31.

Add: Optional. If you do not specify this element or leave it empty, the default value of None will be set.
Update: Optional. If no value is set for the update, this setting is not changed. If you set this element, then PromotionStartDate and PromotionEndDate must also be set to retain or update the previous settings.		 PromotionOccasion
PromotionStartDate The start date helps to inform the promotion date or dates that will be displayed in the ad.

For example if the PromotionStartDate and PromotionEndDate dates are both set to February 14th, the text "Valid Feb 14" could be included in the displayed promotion.

The PromotionStartDate date must be earlier than, or equal to, the PromotionEndDate date.

This property does not override the inherent delivery range for a promotion. Both the promotion PromotionOccasion and Scheduling determine when the promotion is eligible to be shown in ads.

If the end date has already passed for the current year, then each start and end date must be set for dates during the following year.

Add: Optional
Update: Optional. If no value is set for the update, this setting is not changed. To delete the current end date and effectively set no end date, set the Day, Month, and Year each to '0' (zero). When you retrieve the promotion ad extension next time, this element will not be set.		 Date
TrackingUrlTemplate The tracking template to use as a default for all FinalUrls and FinalMobileUrls.

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 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 3 pilot (GetCustomerPilotFeatures returns 635), Microsoft Advertising 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.

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

The PromotionAdExtension object has Inherited Elements.

Inherited Elements

Inherited Elements from AdExtension

The PromotionAdExtension object derives from the AdExtension object, and inherits the following elements: DevicePreference, ForwardCompatibilityMap, Id, Scheduling, Status, Type, Version. The descriptions below are specific to PromotionAdExtension, and might not apply to other objects that inherit the same elements from the AdExtension object.

Element Description Data Type
DevicePreference Not supported for this ad extension type. long
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.

There are currently no forward compatibility changes for the AdExtension object.

Add: Read-only
Update: Read-only		 KeyValuePairOfstringstring array
Id The unique Microsoft Advertising identifier of the ad extension.

Add: Read-only
Update: Read-only and Required		 long
Scheduling Determines the calendar day and time ranges when the ad extension is eligible to be shown in ads.

Add: Optional
Update: Optional. If you set this element null, any existing scheduling set for the ad extension will remain unchanged. If you set this to any non-null Schedule object, you are effectively replacing existing scheduling settings for the ad extension. To remove all scheduling set this element to an empty Schedule object.		 Schedule
Status The status of the ad extension. The value will always be Active because the Campaign Management service does not return deleted ad extensions.

Add: Read-only
Update: Read-only		 AdExtensionStatus
Type The type of the ad extension. This value is PromotionAdExtension when you retrieve a promotion ad extension.

Add: Read-only
Update: Read-only

For more information about ad extension types, see the Ad Extension Data Object Remarks.		 string
Version Tracks the number of times the ad extension has been updated.

The version is set to 1 when the ad extension is created, and increments by one after each update.

Add: Not allowed
Update: Not allowed		 int

Requirements

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