Advertising Advertising Editor Advertising Intelligence

How is the feed file organized?

Learn the details of each field that can be in your Microsoft Merchant Center feed file.
New to Microsoft Shopping Campaigns? Learn how to get started in this training course.

Your feed file is a text delimited file that has a different product item on each line. You create the text delimited file and then submit it to Microsoft Merchant Center.

You can find the rules for creating the feed file at How do I create a feed file? If you're using Google feed files, make it even easier to import by using the Google Merchant Center import tool. Learn more

Here are the required and optional fields you can include in the catalog feed:

Required Fields expando image
Field name Description What you need to know
id A unique identifier for the item.

Example:
ISI1

Requirements:
50 Unicode character limit
Recommended: ASCII only: alphanumeric, underscores (_), and dashes (-)

  • ID must be unique for each item in your catalog per market.
  • If you have multiple feeds, IDs of items across different feeds still need to be unique.
  • Special ASCII characters (e.g., asterisk (*), comma (,), backslash (\), ampersand (&), etc. are allowed.
  • The ID is the same as the merchant product ID (MPID).
title Title of the item

Example:
Women's shoes

Requirements:
Alphanumeric
150 character limit
Don't enclose in quotes

  • Use relevant titles that match with what users are searching for with key information first in the title (e.g., Women’s over the knee boots).
  • When applicable, we recommend you include gender, size, color, material, and pattern details in title (e.g., Women’s small red wool sweater).
  • Include characteristics like color to differentiate from other products.
  • Do not include promotional text (e.g., Free shipping) or use all caps (e.g., WOMEN’S SHOES).
  • Uploading an item for the first time will be pending review until the offer title has been successfully reviewed. Updating the offer title of an existing item will be reverted to the pending review status until it has been successfully reviewed again. The review process can take up to 3 business days.
  • The title of the item can be slightly different, but it must be for the same item.
  • For mobile devices or tablets, the price can be 0 when payment options with multiple installments are provided. For such items, you must include the product_category value of "Electronics > Communications > Telephony > Mobile Phones" (267) for mobile devices or "Electronics > Computers > Tablet Computers" (4745) for tablets.
link Direct URL of the item's page on your website

Example:
http://www.contoso.com/
product.asp?pn=ISI1

Requirements:
0-2000 characters
HTTP or HTTPs only and no redirects. For redirect URLs, use the ads_redirect field.

  • Link should point to the specific product instead of your store’s home page or pages with multiple products.
  • The Product URL domain must match the Store URL domain.
  • Must be a path under your store's destination URL. For aggregators, this must be a direct link to the seller's product page. Aggregators are third party sites that consolidate items to Microsoft Bing on behalf of individual merchants. In the catalog that an aggregator submits, the link attribute must be a direct link to the seller's product page and the seller-name attribute is required. Adding items submitted on behalf of the merchant must comply with our policies and Terms of Service.
  • Uploading an item for the first time will be pending review until the product URL has been successfully reviewed. Updating the product URL of an existing item will be reverted to the pending review status until it has been successfully reviewed again. The review process can take up to 3 business days.
  • Use as few redirects as possible and be sure that the redirects go to the same verified store domains to avoid offer rejections.
  • Do not require customers to register, sign in, or take other actions to view information about your product. Make sure customers see your final landing page immediately after clicking your ad.
price Base price, excluding tax and shipping, submitted in local currency.

Example:
23.99

Requirements:
Numeric
0.00 to 10000000.00 (10 million)

Use two decimal places and no symbols (e.g.. $)
  • The price from the landing page of your offer must be the same price as indicated in the feed.
  • For the United States, exclude tax in the price. For the United Kingdom, include any value added tax (VAT) in the price. See Microsoft Merchant Center catalog tax policy for more details.
  • Uploading an item for the first time will be pending review until the price has been successfully reviewed. Updating the price of an existing item will be reverted to the pending review status until it has been processed again. The pricing update can take up to 6 hours to process.
  • For mobile devices or tablets, the price can be 0 when payment options with multiple installments are provided. For such items, you must include the product_category value of "Electronics > Communications > Telephony > Mobile Phones" (267) for mobile devices or "Electronics > Computers > Tablet Computers" (4745) for tablets.
  • Auction price is not allowed. The price must be a fixed price for the product.
description Item description

Example:
Bright yellow 100% cotton dress shirt

Requirements:
Alphanumeric
10000 character limit
No HTML code and no promotional text
Do not enclose in quotes

  • The description from the landing page of your offer must be the same description as indicated in the feed.
  • We recommend that you include size, color, and pattern when applicable.
  • User relevant description with the most important data at the front.
  • Uploading an item for the first time will be pending review until the description has been successfully reviewed. Updating the description of an existing item will be reverted to the pending review status until it has been successfully reviewed. The review process can take up to 3 business days.
  • The description of the item can be slightly different, but it must be for the same item.
image_link URL of an image of the item

Example:
http://www.contoso.com/
images/ISI1.jpg

Requirements:
Alphanumeric
1000 character limit
Link must be HTTP or HTTPs only
Image must be: bmp, gif, exif, jpg, png, tiff
The recommended minimum size is 220px by 220px
The image size cannot exceed 3.9 MB
No watermarks or free shipping text
Only one image per item

  • Do not include any text within your images, including promotional messaging.
  • Use images with a white background for a “pop” effect.
  • Update robots.txt file to allow Microsoft Advertising to crawl your site. Your ad cannot be served if the crawling is incomplete. Learn more.
  • The image link URL is case-sensitive. Changing the casing on the URL will cause the URL to be re-crawled.
  • Uploading an item for the first time will be pending review until the image URL has been successfully crawled. Updating the image URL of an existing item will be reverted to the pending review status until it has been successfully re-crawled. The review process can take up to 3 business days.
  • If you have updated the image, be sure to update the image URL for the new image to be reflected in the ad.
  • If the images aren't displaying because the URL is missing an image or the image size is too large or small, update the URL for the offer so it can be reviewed in the next crawl.
shipping Cost of shipping, submitted in local currency. This is a required field for Austria and Germany only.

Shipping has multiple subfields and can have the following headers:

  • shipping(price)
  • shipping(country:price)
  • shipping(country:service:price)
  • shipping
Example:
12.99

Requirements:
Numeric
0.01 to 10000000.00 (10 million)
Use two decimal places and no symbols (e.g., €)
For free shipping, use 0

  • The shipping field is required for Austria and Germany only.
  • Multiple shipping prices for any item is accepted. For example, DE:Standard:10, DE:Express:20, and DE:Same Day:30 can be used for the same item.
  • The format depends on the attribute name in the header row of the feed file and the order of the values must match the order in the attribute name. For example, shipping(country:price) must be DE:6.49 or shipping(country:service:price) must be DE:Standard:12.99
  • Each sub-attribute needs to be separate with a colon and each delivery attribute group needs to be separated with a comma.
  • If a country is not included, the shipping price will apply to the target country of the item by default.
  • Uploading an item's shipping for the first time will be pending review until the shipping has been successfully reviewed. This can take up to 30 hours to process. Updating the shipping of an existing item will be reverted to the pending review status until it has been processed again. The shipping update can take up to 8 hours to process.
Required (if value is assigned by the manufacturer) - Item Identification expando image
Field name Description What you need to know
mpn Manufacturer Part Number

Example:
ADNK-5020

Requirements:
Alphanumeric
70 character limit

gtin Global Trade Item Number.
Up to 10 GTIN values can be provided, with a maximum of 14 digits per value. For multiple GTIN values, separate by a comma and space.

Example:
00012345600012

Requirements:
Numeric
14 digits max per value
Multi-value

Learn more about unique identifiers for your product ads.
brand Item’s manufacturer, brand or publisher

Example:
Contoso

Requirements:
Alphanumeric
70-character limit
10-word limit

  • Do not add your store name as the brand unless you manufacture the product.
  • We recommend to keep the brand character limit to 70, but it can be up to 1000 characters.
  • The maximum word limit is 10.
  • Uploading an item for the first time will be pending review until the brand has been successfully crawled. Updating the brand of an existing item will be reverted to the pending review status until it has been successfully re-crawled. The review process can take up to 3 business days.
  • Learn more about unique identifiers for your product ads.
identifier_exists (required for new products only when gtin and brand, or mpn and brand isn't available) Used to indicate that unique product identifiers (gtin, brand, and mpn) aren't available for a product.

Example:
FALSE

Requirements:
Boolean: TRUE or FALSE

  • Products that may not have an identifier_exists attribute include custom goods, like homemade products, or products that were made before gtins were created, like antiques.
  • Learn more about unique identifiers for your product ads.
Optional Fields - Apparel Products expando image
Field name Description What you need to know
gender Gender targeted by the item

Example:
male

Requirements:
Valid options: male, female, unisex. No other option will be accepted.

  • Required for all Apparel & Accessories products when targeting these countries: France, Germany, United Kingdom, and United States
  • Optional for products in the following Apparel & Accessories sub-categories: Pinback Buttons, Tie Clips, Cufflinks, Wristbands, Shoe Covers, Shoelaces, Spurs, Watch Bands, Keychains, Wallet Chains, Lanyards, Checkbook Covers, Badge & Pass Holder, Watch Winders, Watch Stickers & Decals, Handkerchiefs, and Decorative Fans.
  • We recommend including gender in the title for products where it's a distinguishing attribute.
age_group Age group targeted by the item

Example:
newborn

Requirements:
Valid Options: newborn, infant, toddler, kids, adult

  • Required for all Apparel & Accessories products when targeting these countries: France, Germany, United Kingdom, and United States
  • Optional for products in the following Apparel & Accessories sub-categories: Pinback Buttons, Tie Clips, Cufflinks, Wristbands, Shoe Covers, Shoelaces, Spurs, Watch Bands, Keychains, Wallet Chains, Lanyards, Checkbook Covers, Badge & Pass Holder, Watch Winders, Watch Stickers & Decals, Handkerchiefs, and Decorative Fans.
color The dominant color of the item

Example:
red/black/white

Requirements:
Text: Character limit 100
Supports up to 3 values separated by a slash [/] with most dominant color first
Color attributes, like "stainless steel" or "mahogany" are also accepted

  • Required for all Apparel & Accessories products when targeting these countries: France, Germany, United Kingdom, and United States
  • We recommend adding the dominant color in the title.
size Size of the item

Example:
small, medium, large

Requirements:
Alphanumeric
Max 100 characters
String/Unicode characters

  • Required for all Apparel & Accessories products when targeting these countries: France, Germany, United Kingdom, and United States
  • Indicate size values based on your target country.
  • Use consistent size values for the same items. (e.g., “small”, “medium”, and “large” and not “small,” “M,” and “Lg”).
size_type Size type of the item

Example:
regular, petite

Requirements:
Supported values: regular, petite, plus, big and tall, or maternity

size_type is recommended when the size attribute is provided.
size_system Size system of the item

Requirements: Single value
Supported values: DE, FR, AU, US, and UK

  • If size_system is not provided, the item will default to the size system of the target country.
  • size_system is recommended when the size attribute is provided.
Optional Fields - Product Variants expando image
Field name Description What you need to know
item_group_id Used to group items that may vary by color, material, pattern, size, age_group, or gender

Example:
XYZ123

Requirements:
Alphanumeric
Max 50 Unicode characters
Recommended:
ASCII only: alphanumeric, underscores (_), and dashes (-)

  • This ID is different from the "ID" attribute.
  • Values must be different for items, unless items are variants of the same item.
  • At least one of the variant attributes (size, color, material, pattern, age_group, or gender) must be provided and the same variant attribute must be provided for all items within the group.
material The material of the item

Example:
leather/suede/silk

Requirements:
Alphanumeric: Max 200 characters
Supports up to 3 values separated by a slash [/] with most dominant material first

Values may be displayed, so we recommend you use values that users can understand.
pattern The pattern or graphic print of the item

Example:
checkered

Requirements:
Alphanumeric: Max 100 characters

Values may be displayed, so we recommend you use values that users can understand.
additional_image_link The URLs of additional images

Example:
http://www.contoso.com/
images/ISI1.jpg

Requirements:
Alphanumeric
2000 character limit
Link must be HTTP or HTTPs only
Image must be: bmp, gif, exif, jpg, png, or tiff
The recommended minimum size is 220px by 220px
The image size cannot exceed 3.9 MB
No watermarks or free shipping text.

Values may be displayed, so we recommend you use values that users can understand.
Can have up to 10 images, separated by a comma (,) delimiter.
"%2C" value in the image URL should be considered as (,) and part of the image URL link (e.g., 2 image URLs that contain commas will look like: http://www.contoso.com/image2%2C3.jpg,http://
contoso.com/image2%2C4.jpg).
Optional Fields - Other expando image
Field name Description What you need to know
adult Microsoft Advertising does not support adult products.

Example:
FALSE

Requirements:
Boolean:TRUE or FALSE

Any adult products submitted in the feed will be rejected.
availability Availability of item

Example:
in stock
out of stock
preorder

Requirements:
Valid options: in stock, out of stock, preorder.
Default is "in stock."

  • If no values are provided, the availability will be set to "in stock" by default.
  • Uploading an item for the first time will be pending review until the availability has been successfully reviewed. Updating the availability of an existing item will be reverted to the pending review status until it has been processed again. The update can take up to 6 hours to process.
  • “in stock” products are available for sale and the advertiser is accepting and fulfilling orders.
  • “out of stock” products are either unavailable or the advertiser wants to exclude these products from being served temporarily.
  • “preorder” products haven’t been released yet but advertiser will accept orders and ship at the availability date.
  • Mapping details:
    in stock: InStock, LimitedAvailability
    out of stock: Discontinued, OutOfStock, SoldOut
    preorder: PreOrder, PreSale
product_category Predefined product category (equivalent to google_product_category)

Example:
Software > Computer Software

Requirements:
Alphanumeric
255 character limit
Delimiters: greater than symbol [>].
Only the greater than symbol > is a valid delimiter. Any other value is treated as invalid.
Full list of taxonomy values:

  • IDs, instead of string values, are now supported. View the updated taxonomy categories: Taxonomy and Taxonomy with IDs
  • For mobile devices or tablets, the price can be 0 when payment options with multiple installments are provided. For such items, you must include the product_category value of "Electronics > Communications > Telephony > Mobile Phones" (267) for mobile devices or "Electronics > Computers > Tablet Computers" (4745) for tablets.
condition Condition of item

Example:
new

Requirements:
Valid options: new; used; refurbished
Default is "new."

  • If no values are provided, the condition will be set to "new" by default.
  • 'New' products are brand new and have never been used, with the original packaging never opened.
  • 'Refurbished' products have been professionally restored, is free of defects, and comes with a warranty. It may or may not have the original packaging.
  • 'Used' products are anything other than 'new' or 'refurbished,' where the products have been used previously, with the original packaging opened or missing.
expiration_date The date the item will expire

Example:
2015-01-25

Requirements:
ISO 8601 standard format: YYYY-MM-DD
Maximum supported is 30 days from date of upload.
The default is 30 days.

If the expiration date isn't provided, items will expire after 30 days.
multipack Used when bundling multiple identical items into a single unit

Example:
10

Requirements:
Integer, greater than 1

When setting the price, it must be the total price of the multipack.
product_type Your category of the item

Example:
Home > Electronics > DVD Player

Requirements:
Alphanumeric
750 character limit
Delimiters: greater than [>]

You can have more than one product type if your item applies to more than one category.
mobile_link Mobile landing page URL

Example:
http://www.contosomobile.com/
product.asp

Requirements:
Alphanumeric
Max 2000 character limit
Same rules as the link attribute apply

Link should point to the specific product instead of your store’s home page.
unit_pricing_measure The measure and dimension of product as it is sold.

Example:
1.5 kg

Requirements:
Numeric, plus unit
Supported units:

  • Weight: oz, lb, mg, g, kg
  • Volume (US imperial): floz, pt, qt, gal
  • Volume: ml, cl, l, cbm
  • Length: in, ft, yd, cm, m
  • Area: sqft, sqm
  • Per unit: ct
  • Use the measure or dimension of the product without the packaging.
  • Use positive numbers only.
unit_pricing_base_measure The product’s base measure for pricing (e.g., 100ml means the price is calculated based on a 100ml unit).

Example:
100 g

Requirements:
Numeric, plus unit
Supported units:

  • Weight: oz, lb, mg, g, kg
  • Volume (US imperial): floz, pt, qt, gal
  • Volume: ml, cl, l, cbm
  • Length: in, ft, yd, cm, m
  • Area: sqft, sqm
  • Per unit: ct
  • This attribute is optional when you submit unit_pricing_measure.
  • Use the same unit of measure for both unit_pricing_measure and unit_pricing_base_measure attributes.
  • The price is used to calculate the unit price of the product. For example, if the price is 3 USD, unit_pricing_measure is 150ml, and unit_pricing_base_measure is 100ml, the unit price is 2 USD per 100ml.
installment The monthly installment plan for a product, displayed by the number of months

Example:
12:15 USD

Requirements:
months: The number of installments, displayed as an integer with a range from 1 to 1000.
amount: The amount paid per month, displayed as a number greater than 0 with two decimals in the local currency, with no symbols (for example, $).

  • The price attribute is the up-front payment and the installment attribute is the monthly installments.
  • The currency used in the installment attribute must match the currency used for the price attribute.
  • The installment amount must be greater than 0.00 USD.
  • The installment attribute is available only for mobile and tablet cateogry of products. For any other categories, the installment attribute will be ignored.
  • If you have a single product with both full price and installment price, add two rows for the same product in the feed.
    • One row will be for the full price to be submitted in the price field.
    • The other row will be for the installment price, with the upfront cost in the price field and the installment months and price in the installment field.
energy_efficiency_class
max_energy_efficiency_class
min_energy_efficiency_class
(EU and CH only. May be required by local laws or regulations.) 		The product's energy label

Example:
A+

Requirements:
Only the values below are supported:

  • G
  • F
  • E
  • D
  • C
  • B
  • A
  • A+
  • A++
  • A+++
  • For water heaters, include the energy efficiency class for:
    Conventional water heaters
    Solar water heaters
    Heat pump water heaters
    Water heater packages
  • For reversible air conditioners, include the energy efficiency class for heating during an average season.
Optional Fields - Microsoft Bing Attributes expando image
Field name Description What you need to know
seller_name Merchant/Store that provides this item

Example:
Contoso Shoes

Requirements:
Alphanumeric
255 character limit
Only required for aggregators - not applicable for direct merchants

  • For aggregators, the direct merchant name as SellerName must be sent per Microsoft policy. For direct merchants, this attribute is optional. Aggregators are third party sites that consolidate items to Microsoft Bing on behalf of individual merchants. In the catalog that an aggregator submits, the link attribute must be a direct link to the seller's product page and the seller-name attribute is required. Adding items submitted on behaf of the merchant must comply with our policies and Terms of Service.
  • seller_name and ads_redirect attributes are accepted via Google-formatted XML feed files.
ads_redirect Redirect URL that overrides the URL given in the "link" attribute. Ensure that this URL will redirect to the same URL as given in the "link" or "mobile_link" attribute.

Example:
http://www.contoso.com/shoe/

Requirements:
Max 2000 characters
HTTP, HTTPs, or Google-formatted XML only
Must redirect to a landing page
See accepted symbols in feed files

  • Uploading an item for the first time will be pending review until the ads redirect URL has been successfully crawled. Updating the ads redirect URL of an existing item will be reverted to the pending review status until it has been successfully re-crawled. The review process can take up to 3 business days.
  • Use as few redirects as possible and be sure that the redirects go to the same verified store domains to avoid offer rejections.
  • Use a value that will resolve into a valid URL after any parameters or tracking templates are replaced with their final values.
  • seller_name and ads_redirect attributes are accepted via Google-formatted XML feed files.
  • "bingads_redirect" is an accepted header.
custom_label_0
custom_label_1
custom_label_2
custom_label_3
custom_label_4 		Use to identify products for ad campaign filters

Example:
Best sellers, High ROAS, Winter

Requirements:
Alphanumeric
Max 200 characters
Single-value
Up to 1000 unique values for each custom label attribute (up to 5000 labels total)

Use custom labels to add a value to the label, such as seasonal or sale items.
Optional Fields- Sales and Promotions expando image
Field name Description What you need to know
sale_price Items’s sale price, excluding tax and shipping

Example:
20.99

Requirements:
Numeric
Range is 0.00 to 10000000.00 (10 million)
No symbols (e.g., $)

  • For the United States, exclude tax in the price. For the United Kingdom, include any value added tax (VAT) in the price. See Microsoft Merchant Center catalog tax policy for more details.
  • Uploading an item for the first time will be pending review until the price has been successfully reviewed. Updating the price of an existing item will be reverted to the pending review status until it has been processed again. The pricing update can take up to 6 hours to process.
  • For mobile devices or tablets, the price can be 0 when payment options with multiple installments are provided. For such items, you must include the product_category value of "Electronics > Communications > Telephony > Mobile Phones" (267) for mobile devices or "Electronics > Computers > Tablet Computers" (4745) for tablets.
sale_price_effective_date Sale’s start and end date and time

Example:
2013-11-05T08:15-05:00/2013-11-10T09:30-05:00

Requirements:
Alphanumeric
Start date must be earlier than end date.
Date and time format: YYYY-MM-DD followed by the letter 'T', the time of day followed by an expression for the time zone as defined by the ISO 8601 standard.

  • The end date needs to be in the same format.
  • For items on sale, submit both the sale price and sale effective date attributes. If you update the sale price attribute but not the sale price effective date, the sale price will continue to be used for your item.
promotion_ID Used to group items by promotion

Requirements:
Alphanumeric
Only underscore (_) and dash (-) symbols allowed
Max 60 character limit per promotion, with a total of 10 promotions accepted
Up to 10 promotion IDs can be mapped to an item and must be separated by commas

  • If the promotion doesn't apply to a product, you can leave this field blank.
  • If the promotion doesn't apply to all products, be sure to map the promotion ID to the correct set of products in the master feed.
  • The promotion's date and time is based on your local time zone. Keep this in mind if you want to have the promotion in any other time zone.

See more videos...