Edit

Products Resource

  • Article

The Products resource lets you manage product offerings in your Microsoft Merchant Center store (MMC). For information about using the Products resources, see Managing your Products. For examples that show how to add, delete, and get products, see Code Examples.

Base URI

The following is the base URI that you append the templates to.

https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/

Templates

To create the endpoints used to manage your product offerings, append the appropriate template to the base URI.

Template HTTP Verb Description Resource
{mmcMerchantId}/products/batch POST Use to perform multiple inserts (updates), gets, and deletes in a single request. The batch must not include multiple actions for the same product. For example, the request must not try to insert and delete the same product.

Set {mmcMerchantId} to the MMC store ID.		 Request: Batch
Response: Batch
{mmcMerchantId}/products/{productUniqueId} DELETE Use to delete a single product offering from the store.

Set {mmcMerchantId} to the MMC store ID.

Set {productUniqueId} to the fully qualified product ID (for example, Online:en:US:Sku123).

If you inserted a product with the same ID in multiple catalogs, it's deleted from all of them.

Deleted products can take up to 12 hours to stop delivering. We recommend updating the product availability to “out of stock” prior to deleting.		 Request: N/A
Response: N/A
{mmcMerchantId}/products/{productUniqueId} GET Use to get a single product offering from the store.

Set {mmcMerchantId} to the MMC store ID.

Set {productUniqueId} to the fully qualified product ID (for example, Online:en:US:Sku123).

If you inserted a product with the same ID in multiple catalogs, the service returns only one of them, and which one is undetermined.		 Request: N/A
Response: Product
{mmcMerchantId}/products GET Use to get a list of products in the store.

Set {mmcMerchantId} to the MMC store ID.		 Request: N/A
Response: Products
{mmcMerchantId}/products POST Use to insert (update) a single product offering in the store.

If the product doesn't exist, it's added; otherwise, the product is updated. Because updates overwrite the current offering, you must include all fields that make up the offer.

To insert the offer into a specific catalog, specify the bmc-catalog-id query parameter; otherwise, the product is inserted into the store's default catalog.

Set {mmcMerchantId} to the MMC store ID.

Note that because Get/List and Delete requests act against the store and not a specific catalog, you should not insert a product with the same channel, contentLanguage, targetCountry, and offerId into multiple catalogs.		 Request: Product
Response: Product

Query parameters

The endpoints may include the following query parameters.

Parameter Description
alt Optional. Use to specify the type of content that's used in the request and response. The possible values are json and xml. The default is json.
bmc-catalog-id Optional. Use to specify the catalog to insert (update) product offerings into.

Use this parameter if your store contains multiple catalogs. If you do not specify this parameter, the product is inserted into the store's default catalog.

This parameter is only used to insert product offerings. This parameter is ignored for Get, List, and Delete requests because they operate across catalogs.
dry-run Optional. Use when debugging your application to test calls. Calls that include this parameter won't affect production data (products are not inserted or deleted); however, the response will contain any errors that the call generates.

Consider the following limitations when using this parameter.
  • Insert operations don't return IDs.
  • The service doesn't generate or return secondary error messages such as data quality, editorial issues, and database-related validations.
For more information about testing your application, see Sandbox.
max-results Optional. Use to specify the maximum number of items to return in a List request. The maximum value that you may specify is 250. The default is 25.
start-token Optional. Use to page through a store's list of products. The token identifies the next page of products to return in a List request. Do not specify this parameter in the first List request. If the catalog contains more than the requested number of products (see the max-results query parameter), the response includes the nextPageToken field (see Products), which contains the token value that you use in the next List request.

Headers

The following are the request and response headers.

Header Description
AuthenticationToken Request header.

Set this header to an OAuth access token. For information about getting an access token, see Authenticating your credentials.
Content-Location Response header.

A URL that identifies the store that the product was inserted into. This header is included in the response of an Insert request.
Content-Type Request and response header.

The type of content in the body of the request or response. For POSTs, if you use JSON, set this header to application/json. Otherwise, if you use XML, set this header to application/xml.
CustomerAccountId Request header.

The account ID of any account that you manage on behalf of the customer specified in the CustomerId header. It doesn't matter which account you specify. Specify this header only if you manage an account on behalf of the customer.
CustomerId Request header.

The customer ID of the customer whose store you manage. Specify this header only if you manage the store on behalf of the customer. If you set this header, you must also set the CustomerAccountId header.
DeveloperToken Request header.

The client application's developer token. Each request must include this header. For information about getting a token, see Do you have your Microsoft Advertising credentials and developer token?
Location Response header.

A URL that identifies the store that the product was inserted into. This header is included in the response of an Insert request.
WebRequestActivityId Response header.

The ID of the log entry that contains details of the request. You should always capture this ID if an error occurs. If you are not able to determine and resolve the issue, include this ID along with the other information that you provide the Support team.

Request and response objects

The following are the request and response objects used by the API.

Each object defines the JSON key name and XML element name that you use depending on the content type that you specified for the request.

Object Description
Batch Defines the list of items to process in a batch request.
Error Defines an error.
ErrorResponse Defines the top-level error object for a single product insert.
BatchItemError Defines errors that occurred for an item during batch processing.
Item Defines an item in a batch request or response.
Product Defines a product.
ProductCustomAttribute Defines a custom attribute.
ProductCustomGroup Defines a group of custom attributes.
ProductDestination Defines a destination.
ProductPrice Defines a product's price.
ProductTax Defines the geographic location that determines the applicable taxes.
Products Defines a list of products.
ProductShipping Defines the shipping cost.
ProductShippingWeight Defines the item's shipping weight.
UnitPricing Defines the item's per unit price.
Warning Defines a warning message.

Batch

Defines the list of items to process in a batch request. Note that this object is used in a batch request and response.

Name Value Type XML element name
entries An array of items to process in a batch request.

The maximum number of items that you can specify is 12,000. However, the maximum request size is 4 MB, so the actual number of items depends upon the number of product attributes (for example, size, color, pattern) that you include and whether you compress the data. For example, if you compress the data you may be able to specify 12,000 items, but if you don't, you may be able to specify only 2,000 items.		 Item[] <batch>

BatchItemError

Defines errors that occurred for an item during batch processing.

Name Value Type XML element name
errors A list of errors that occurred while processing the item. Error[] <errors>
code The HTTP status code of the error. String
message A message associated with the error. String

Error

Defines an error.

Name Value Type XML element name
domain For internal use only. String <domain>
location Not used. String <location type="string">
locationType Not used. String See the type attribute of the <location> element
message A description of the error. String <internalReason>
reason The reason why the request failed. For example, the product failed validation. String <reason>

ErrorResponse

Defines the top-level error object for a single product insert.

Name Value Type XML element name
error A list of errors that occurred while processing the item. Errors[] <error>

Errors

Defines the list of errors and warnings for an offer.

Name Value Type XML element name
errors A list of errors that occurred while processing the item. Error[] <errors>
warnings A list of warnings that occurred while processing the item. The offer was accepted but you should address the issues at your earliest convenience. For example, MMC returns warnings if you do not specify the gtin, mpn, and brand identifiers if they should be known. Warning[] <warnings>
code The HTTP status code or the error. String
message A message associated with the error. String

Item

Defines an item in a batch request.

Name Value Type XML element name
batchId A user-defined ID that identifies this item in the batch request. For example, if the batch contains 10 items, you can assign them IDs 1 through 10. Unsigned Integer <entry batch_id="unsigned integer" method="string">
errors An error object that contains a list of validation errors that occurred. The response includes this field only when an error occurs. BatchItemError <errors>
merchantId The Merchant Center store ID. Unsigned Long <merchant_id>
method The action to apply to the item. The possible values are insert, get, and delete. If the item is adding or updating a product offering, set method to insert; if the item is deleting a product, set method to delete; and if the item is getting a product, set method to get. The strings are case insensitive. String See the method attribute of the <entry> element
product The product offering. Specify this field in a request only if inserting (updating) a product. The response will include this field for gets and inserts (updates) only. Product <product>
productId The fully qualified product ID (for example, Online:en:US:Sku123). Include this field only when getting or deleting a product offering.

Do not include multiple items with the same product ID in a batch request.		 String <product_id>

Product

Defines a product. For more information about the fields in this object, see How is the feed file organized?

JSON and XML Name Value Type Required for insert
additionalImageLinks

<additional_image_link>		 The URLs of additional images of the product that can be used in the product ad. To specify multiple images,

MMC does not use the additional images; this field is included for Google compatibility.		 String[] No
adult

<adult>		 A Boolean value that determines whether the item is an adult product. Set to true if the item's target market is adults. The default is false.

Note that adult products are not supported and will be rejected.		 Boolean No
adwordsGrouping

<adwords_grouping>		 A group of items for Cost-per-acquisition (CPA) bidding.

MMC does not use this field; it's included for Google compatibility.		 String No
adwordsLabels

<adwords_label>		 The labels for grouped items (see adwordsGrouping). Applies to Cost-per-click (CPC) only.

MMC does not use this field; it's included for Google compatibility.		 String[] No
adwordsRedirect

<adwords_redirect>		 The URL to use in the product ad. If specified, this URL must redirect to the URL specified in link. String No
ageGroup

<age_group>		 The target age group of the item. The following are the possible values.

  • adult
  • kids
  • toddler
  • infant
  • newborn
 String No
availability

<availability>		 The availability status of the product. The following are the possible values.

  • in stock
  • out of stock
  • preorder
The default is in stock.
 String Yes
availabilityDate

<availability_date>		 The UTC date that a pre-order product will be available for shipping (see the availability field). This field is optional but if you know the date that the pre-ordered product will be available for shipping, you should set this field. Specify the date in ISO 8601 format.

NOTE: MMC currently ignores the contents of this field.		 String No
brand

<brand>		 The item's brand, manufacturer, or publisher. The string may contain a maximum of 10 words and 1,000 characters. To ensure the string displays well in the UX, you should limit the brand name to no more than 70 characters. String Yes
channel

<channel>		 The sales channel for the product. The following are the possible case-insensitive values.

  • Local
  • Online
Because channel is used to create the product ID, you may not change this field after adding the product to the store.		 String Yes
color

<color>		 The product's dominant color. If the color is a blend of colors, you may specify a slash-delimited list of up to 3 colors (for example, red/green/blue).

If a dress is available in multiple colors, you would create a product for each color and use itemGroupId to group the product's variants.

The field is limited to 100 characters.

Recommended for apparel items.		 String No
condition

<condition>		 The condition of the product. The following are the possible values.

  • new
  • refurbished
  • used
The default is new.		 String Yes
contentLanguage

<content_language>		 The two-letter ISO 639-1 language code for the product. The following are the possible case-insensitive values:
  • Albanian (sq)
  • Bosnian (bs)
  • Bulgarian (bg)
  • Croatian (hr)
  • Czech (cs)
  • Dutch (nl)
  • English (en)
  • Estonian (et)
  • French (fr)
  • German (de)
  • Greek (el)
  • Hungarian (hu)
  • Icelandic (is)
  • Italian (it)
  • Latvian (lv)
  • Lithuanian (lt)
  • Macedonian (mk)
  • Maltese (mt)
  • Polish (pl)
  • Portuguese (pt)
  • Romanian (ro)
  • Serbian (sr)
  • Slovak (sk)
  • Slovenian (sl)
  • Spanish (es)
  • Swedish (sv)
  • Turkish (tr)
Because the language is used to create the product ID, you may not change this field after adding the product to the store.		 String Yes
customAttributes

<custom_attribute>		 A list of custom attributes used by the merchant. ProductCustomAttribute[] No
customGroups<custom_group> A list of custom groups used by the merchant. ProductCustomGroup[] No
customLabel0

<custom_label_0>		 Custom label 0, which is used to filter products for Microsoft Shopping campaigns. The label is limited to 100 characters. String No
customLabel1

<custom_label_1>		 Custom label 1, which is used to filter products for Microsoft Shopping campaigns. The label is limited to 100 characters. String No
customLabel2

<custom_label_2>		 Custom label 2, which is used to filter products for Microsoft Shopping campaigns. The label is limited to 100 characters. String No
customLabel3

<custom_label_3>		 Custom label 3, which is used to filter products for Microsoft Shopping campaigns. The label is limited to 100 characters. String No
customLabel4

<custom_label_4>		 Custom label 4, which is used to filter products for Microsoft Shopping campaigns. The label is limited to 100 characters. String No
description

<description>		 A description of the product. The description may not include promotional text. The description is limited to a maximum of 10,000 characters, and may include any Unicode characters.

The description will undergo editorial review.		 String No
destinations

<destination>		 The intended destinations of the product.

MMC does not use this field; it's included for Google compatibility.		 ProductDestination[] No
energyEfficiencyClass

<energy_efficiency_class>		 The energy efficiency class as defined in EU directive 2010/30/EU. The following are the possible values.

  • A
  • A+
  • A++
  • A+++
  • B
  • C
  • D
  • E
  • F
  • G
 String No
expirationDate

<expiration_date>		 The UTC date and time that specifies when the product will expire.

If you do not specify an expiration date, the product expires 30 days from the date and time that you add or update the product (the date and time are based on the Microsoft server's timezone).

Use this field to specify an expiration date that's less than 30 days from today.

Your expiration date should always include the time component and specify the timezone or offset information. If it doesn't, the API will try to determine the timezone by using targetCountry. For countries or regions with multiple time zones, the API determines the timezone to use. For example, if the country is US, the API will use pacific standard time (PST).

You should track products that are nearing expiration and before they expire either update their expiration date or simply update the product (you do not have to update any of the product's fields) which will automatically extend the expiration date another 30 days. If you explicitly set the expiration date, you must set a new expiration date yourself; updating the product will not automatically extend the expiration date another 30 days in this case.		 String No
gender

<gender>		 The gender that the product targets. The following are the possible values.

  • female
  • male
  • unisex
 String No
googleProductCategory

<google_product_category>		 The product category that the product is found in. You may specify either a category string (for example, Animals & Pet Supplies > Pet supplies > Bird Supplies) or a category ID (for example, 3). For a category string, the list of subcategories is delimited by the greater than symbol ('>'). The field is limited to 255 characters.

For a list of category strings and IDs, see Categories.		 String No
gtin

<gtin>		 The Global Trade Item Number (GTIN) assigned by the manufacturer. If the manufacturer assigns a GTIN, you must specify it. The following are types of GTINs.

  • EAN (European Article Number)
  • ISBN (International Standard Book Number)
  • JAN (Japanese Article Number)
  • UPC (Universal Product Code)
 String Yes
id

<id>		 The fully qualified product id. The ID is a composite of channel, contentLanguage, targetCountry, and offerId. The ID is case sensitive.

Use this ID to get or delete a product.		 String No
identifierExists

<identifier_exists>		 A Boolean value that determines whether the product offer specifies the gtin, mpn, or brand identifiers. The default is true. Set to false if you do not specify all three of the identifiers.

Unique product identifiers define a product in a global marketplace. Tagging your products with unique identifiers makes it easier for customers to find your products. You should specify all three identifiers, if known.		 Boolean No
imageLink

<image_link>		 The URL to an image of the product that can be used in the product ad. The URL is limited to 1,000 characters and may use the HTTP or HTTPS protocol. The allowed image types are bmp, gif, exif, jpg, png, and tiff. The recommended image size is 200x200 pixels. The image may not exceed 3.9 MB.

The image will undergo editorial review.		 String Yes
isBundle

<is_bundle>		 A Boolean value that determines whether the product is a merchant-defined bundle. The value is true if the product is a bundle. Boolean No
itemGroupId

<item_group_id>		 An ID that can be used to group all variants of the same product. For example, if the dress is available in 3 colors, you could create a product for each color and use this ID to group them. Typically, you group items that vary by color, material, pattern or size.

The ID must be unique within a catalog, and is limited to 50 characters.		 String No
kind

<kind>		 The object's type. This field is set to content#product. String No
link

<link>		 The URL to the product's page on your website. The URL is limited to 2,000 characters and may use the HTTP or HTTPS protocol. The domain must match the store's domain.

The link is used in the product ad. The URL may not be redirected. To use another URL in the product ad that may be redirected to this URL, see adwordsRedirect.

The webpage that this link points to will undergo editorial review.		 String Yes
material

<material>		 The product's dominant material. If the material is a blend of materials, you may specify a slash-delimited list of up to 3 materials (for example, leather/suede/silk).

If a dress is available in multiple materials, you would create a product for each material and use itemGroupId to group the product's variants.

The field is limited to 200 characters.

Recommended for apparel items.		 String No
mobileLink

<mobile_link>		 A URL to a mobile-optimized version of the webpage that contains information about the product (see link). String No
multipack

<multipack>		 The number of identical products being sold as a single unit (for example, 4 flashlights). When setting the price, it must be the total price of the multipack. Integer No
mpn

<mpn>		 The manufacturer part number (MPN) of the product. If the manufacturer assigns an MPN, you must specify it. The MPN is limited to 70 characters. String Yes
offerId

<offer_id>		 The user-defined ID of the product being offered. The offer ID is case insensitive and must be unique within a catalog, and is limited to a maximum of 50 characters.

Because the offer ID is used to create the product ID, you may not change this field after adding the product to the store.		 String Yes
onlineOnly

<online_only>		 A Boolean value that determines whether the product is only available for purchase online. The value is true if the product is available only online. The default is false. Boolean No
pattern

<pattern>		 The pattern or graphic print of the product (for example, plaid). The pattern is limited to 100 characters.

If a dress is available in multiple patterns, you would create a product for each pattern and use itemGroupId to group the product's variants.

Recommended for apparel items.		 String No
price

<price>		 The product's price. Specify the price in the currency of the target country. For information about whether to include tax in the price, see Microsoft Merchant Center catalog tax policy. The price must match the price shown on the product's webpage (see link), and must be in the range 0.01 (1 cent) through 10000000.00 (10 million).

However, if the following conditions are met, you may set the price to 0.0 (zero).

1. The googleProductCategory field is set to one of the following categories:
    - Electronics > Communications > Telephony > Mobile Phones
    - Electronics > Computers > Tablet Computers
2. The title field contains one of the following keywords:
    - contract
    - installment
    - lease
    - payment

The above keywords are shown in English; however, the title and keyword must be in the language of the specified market.

Typically, the title will contain phrasing such as "... with installment plan" or "... with contract only". The contract keyword may be used in all markets; however, installment, payment, and lease may be used only in the US market.		 ProductPrice Yes
productType

<product_type>		 The advertiser-defined product category, which may be different from googleProductCategory. For example, Animals & Pet Supplies > Pet supplies > Bird Supplies > Veterinary. The list of subcategories is delimited by the greater than symbol ('>'). The field is limited to 750 characters.

You may specify multiple category strings that are comma delimited. For example, Costumes & Accessories > Wig Accessories > Wig Caps, Costumes & Accessories > Wig Accessories > Wig Glue.		 String No
promotionId

<promotion_id>		 A comma-delimited list of IDs that identify promotions in your Promotions feed. You may specify a maximum of 10 promotion IDs.

The ID must contain a minimum of 1 character and a maximum of 60 characters. The allowed characters are any alphanumeric characters, a dash (-), and an underscore (_).

All IDs for a market (see contentLanguage and targetCountry) must be unique. For example, within a market, you may not use PROMO1 and promo1, but you could use PROMO1 in the en-US market and promo1 in the en-GB market. You may specify the same unique promotion ID on one or more products.

Microsoft promotes the product if the ID that you specify matches a promotion ID in your Promotions feed (for the same target country). The IDs match only if the casing is the same. For example, the IDs match if the product's ID is PROMO1 and the feed's ID is PROMO1, but they do not match if the feed's ID is Promo1.

To ensure that the product is not accidentally promoted in the future, you should remove the IDs of promotions that have ended. Although the ID cannot be used again in a Promotions feed for 6 months after the promotion ends, if the ID is reused in another promotion after that, the product will be promoted.		 String No
salePrice

<sale_price>		 The item's sale price. The sale price must be in the range 0.01 (1 cent) through 10000000.00 (10 million).

For sale items, set both the sale price and sale effective date (see salePriceEffectiveDate). If you set the sale price but not the sale price effective date, the sale price will continue to be used until the product expires or you set an effective date.

If the following conditions are met, you may set the sale price to 0.0 (zero).

1. The googleProductCategory field is set to one of the following categories:
    - Electronics > Communications > Telephony > Mobile Phones
    - Electronics > Computers > Tablet Computers
2. The title field contains one of the following keywords:
    - contract
    - installment
    - lease
    - payment

The above keywords are shown in English; however, the title and keyword must be in the language of the specified market.

Typically, the title will contain phrasing such as "... with installment plan" or "... with contract only". The contract keyword may be used in all markets; however, installment, payment, and lease may be used only in the US market.		 ProductPrice No
salePriceEffectiveDate

<sale_price_effective_date>		 The sale's UTC start and end date. Specify the dates in ISO 8601 format. For example, 2016-04-05T08:00-08:00/2016-04-10T19:30-08:00 (use a slash ('/') to separate the start and end dates). For more information, see salePrice. String No
sellerName

<seller_name>		 The name of the merchant that's selling the product. Used only by aggregators to identify the merchant. Aggregators are third party sites that behave on behalf of individual merchants. The products that an aggregator submits on behalf of the merchant must comply with Microsoft Advertising policies and Terms of Service.

Aggregators must set this field to the sellers name. If the caller is not an aggregator and this field is not set, it will default to the store name.

The name is limited to 255 characters.		 String No
shipping

<shipping>		 The price to ship the product based on location.

NOTE: Shipping is required if the target country is DE (Germany); otherwise, it's optional.		 ProductShipping[] Yes
shippingLabel

<shipping_label>		 The shipping label.

NOTE: Shipping information is required if the target country is DE (Germany); otherwise, it's optional.		 String Yes
shippingWeight

<shipping_weight>		 The weight of the product. The weight is used for shipping purposes.

NOTE: Shipping information is required if the target country is DE (Germany); otherwise, it's optional.		 ProductShippingWeight Yes
sizes

<size>		 The available sizes of the product. For example, small, medium, and large. Apply the sizing consistently. The size value is user-defined but should be based on your target country. This field is required for all Apparel & Accessories products when targeting: France, Germany, United Kingdom, and United States. String[] No
sizeSystem

<size_system>		 The measurement system used to size the product. For example, shoes may be sized using the US system or the UK system.

The following are the possible values.

  • AU
  • DE
  • FR
  • UK
  • US
Defaults to the system used by the target country. Recommended for apparel items.		 String No
sizeType

<size_type>		 The cut of the product. The following are the possible values.

  • regular
  • maternity
  • petite
  • plus
  • big and tall
Defaults to Regular. Recommended for apparel items.		 String No
targetCountry

<target_country>		 The two-letter ISO 3166 country code of the target country (the country where you want to advertise the product). The country must match the market specified by the catalog.

The following are the possible case-insensitive values:

  • AD (Andorra)
  • AL (Albania)
  • AR (Argentina)
  • AW (Aruba)
  • AT (Austria)
  • AU (Australia)
  • BS (Bahamas)
  • BD (Bangladesh)
  • BA (Bosnia and Herzegovina)
  • BE (Belgium)
  • BO (Bolivia)
  • BG (Bulgaria)
  • BR (Brazil)
  • BN (Brunei)
  • CA (Canada)
  • KY (Cayman Islands)
  • CH (Switzerland)
  • CL (Chile)
  • CO (Colombia)
  • CR (Costa Rica)
  • CY (Cyprus)
  • CZ (Czech Republic)
  • DE (Germany)
  • DK (Denmark)
  • DM (Dominica)
  • DO (Dominican Republic)
  • EC (Ecuador)
  • SV (El Salvador)
  • EE (Estonia)
  • ES (Spain)
  • FJ (Fiji)
  • FI (Finland)
  • FR (France)
  • GF (French Guiana)
  • PF (French Polynesia)
  • GB (Great Britain)
  • GR (Greece)
  • GU (Guam)
  • GT (Guatemala)
  • GY (Guyana)
  • HT (Haiti)
  • HN (Honduras)
  • HR (Croatia)
  • HU (Hungary)
  • ID (Indonesia)
  • IE (Ireland)
  • IN (India)
  • IS (Iceland)
  • IT (Italy)
  • LI (Liechtenstein)
  • LT (Lithuania)
  • LU (Luxembourg)
  • LV (Latvia)
  • MV (Maldives)
  • MC (Monaco)
  • ME (Montenegro)
  • MK (North Macedonia)
  • MT (Malta)
  • MQ (Martinique)
  • MY (Malaysia)
  • MX (Mexico)
  • MN (Mongolia)
  • MS (Montserrat)
  • NP (Nepal)
  • NL (Netherlands)
  • NC (New Caledonia)
  • NO (Norway)
  • NZ (New Zealand)
  • PA (Panama)
  • PG (Papua New Guinea)
  • PH (Philippines)
  • PY (Paraguay)
  • PE (Peru)
  • PL (Poland)
  • PT (Portugal)
  • PR (Puerto Rico)
  • RO (Romania)
  • RS (Serbia)
  • LK (Sri Lanka)
  • SE (Sweden)
  • SG (Singapore)
  • SI (Slovenia)
  • SK (Slovakia)
  • SM (San Marino)
  • TH (Thailand)
  • TT (Trinidad and Tobago)
  • TR (Türkiye)
  • US (United States)
  • UT (Uruguay)
  • VA (Vatican City)
  • VE (Venezuela)
  • VN (Vietnam)
  • ZA (South Africa)
Because the country is used to create the product ID, you may not change this field after adding the product to the store.		 String Yes
taxes

<tax>		 The tax information of the product.

MMC does not use this field; it's included for Google compatibility.		 ProductTax[] No
title

<title>		 The product's title (for example, Women's Shoes). The title may not include promotional text. The title is limited to a maximum of 150 characters, and may include any Unicode character.

The title will undergo editorial review.		 String Yes
unitPricingBaseMeasure

<unit_pricing_base_measure>		 The product's base measure for pricing (for example, 100ml means the price is calculated based on a 100ml unit).
  • 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

 UnitPricingBaseMeasure No
unitPricingMeasure

<unit_pricing_measure>		 The measure and dimension of product as it is sold.
  • 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

 UnitPricingMeasure No
validatedDestinations

<validated_destination>		 The read-only list of intended destinations that have passed validation.

MMC does not use this field; it's included for Google compatibility.		 String[] No
warnings A list of warnings about issues with the product offer. The offer was accepted but you should address the issues at your earliest convenience. For example, MMC returns warnings if you do not specify the gtin, mpn, and brand identifiers if they should be known.

The offer includes this field only in the response of an insert/update.		 Warning[] No

ProductCustomAttribute

Defines a custom attribute.

Name Value Type XML element name
name Gets or sets the attribute's name. String <name>
type Gets or sets the attribute's type. The following are the possible values.

  • boolean
  • datetimerange
  • float
  • group
  • int
  • price
  • text
  • time
  • url
 String <type>
unit Gets or sets the attribute's unit of measure. Used for values of type INT and FLOAT only. String <unit>
value Gets or sets the attribute's value. String <value>

ProductCustomGroup

Defines a group of customer attributes.

Name Value Type XML element name
attributes Gets or sets the attributes for the group. ProductCustomAttribute <attributes>
name Gets or sets the name of the group. String <name>

ProductDestination

Defines a destination.

Name Value Type XML element name
intention The following are the possible values.

  • default
  • excluded
  • optional
  • required
 String <intention>
destinationName Gets or sets the name of the destination. String <destination_name>

ProductPrice

Defines a product's price or sale price.

Name Value Type XML element name
currency Gets or sets the currency that the price is stated in. Specify the currency using ISO 4217 currency codes. The following are the possible values.

  • AUD (Australian dollar)
  • CHF (Swiss franc)
  • CAD (Canadian dollar)
  • EUR (Euro)
  • GBP (Great Britain pound)
  • IDR (Indonesian rupiah)
  • INR (Indian rupee)
  • MYR (Malaysian ringgit)
  • NZD (New Zealand dollar)
  • PHP (Philippine peso)
  • SEK (Swedish krona)
  • SGD (Singapore dollar)
  • THB (Thai baht)
  • USD (United States dollar)
  • VND (Vietnamese dong)
 String currency attribute.

For example, <price currency="USD">.
value Gets or sets the price of the item. Do not include currency symbols such as '$'. Double Text value.

For example, <price currency="USD">38.0<\price>.

Products

Defines a list of products. Note that this is the top-level object that the List request returns.

Name Value Type XML element name
kind Gets the object's type. This field is set to content#productsListResponse. String <kind>
nextPageToken Gets the token used to get the next page of results. If the object does not include this field, there are no more pages to get. See start-token. String <next_page_token>
resources Gets the list of products. If the catalog does not contain any offers, the array is empty. Product[] <products>

ProductShipping

Defines the shipping cost.

Name Value Type XML element name
country Gets or sets the two-letter ISO 3166 country code of the country where the item is being shipped to. String <country>
locationGroupName Gets or sets the location group name. String <location_group_name>
locationId Gets or sets the ID of the geographic location where the item is being shipped to. For a list of IDs, see Geographical Location Codes. String <location_id>
postalCode Gets or sets the postal code or postal code range of the location where the item is being shipped to. You may specify the postal code as follows:

  • A complete postal code: 94114

  • A postal code with a wildcard (suffix only): 94*

  • A range of codes: 94002-95460

  • A range of codes with wildcards (the postal code prefixes must be of equal length: 94*-95*
 String <postal_code>
price Gets or sets the fixed price to ship the item to the specified location. ProductPrice <price>
region Gets or sets geographical region where the item is being shipped to (for example, zip code). String <region>
service Gets or sets a text description that describes the service class or delivery speed. String <service>

ProductShippingWeight

Defines the item's shipping weight.

Name Value Type XML element name
unit Gets or sets the unit of measure. String unit attribute.

For example, <shipping_weight unit="oz">.
value Gets or sets the item's weight, which is used to calculate the item's shipping cost. String Text value.

For example, <shipping_weight unit="oz">20.3<shipping_weight>.

ProductTax

Defines the geographical location that determines the applicable taxes.

Name Value Type XML element name
country Gets or sets the country whose tax rate applies. Uses the two-letter ISO 3166 country code. String <country>
locationId Gets or sets the ID of the geographic location whose tax rate applies. For a list of IDs, see Geographical Location Codes. Long <location_id>
postalCode Gets or sets the postal code or range of postal codes whose tax rate applies. You may specify the postal code as follows:

  • A complete postal code: 94114

  • A postal code with a wildcard (suffix only): 94*

  • A range of codes: 94002-95460

  • A range of codes with wildcards (the postal code prefixes must be of equal length: 94*-95*
 String <postal_code>
rate Gets or sets the percentage tax rate to apply to the price of the item. To specify a 5% rate, set this field to 5. To specify a 9.8% rate, set this field to 9.8. Double <rate>
region Gets or sets a geographical region whose tax rate applies. String <region>
taxShip Gets or sets a Boolean value that determines whether to apply the tax to the cost of shipping. Set to true if tax is charged on shipping. Boolean <ship>

UnitPricing

Defines the item's per unit price.

Name Value Type XML element name
unit Gets or sets the unit of measure. For example, oz if the price is per ounce. String unit attribute.

For example, <unit_pricing_measure unit="oz">
value Gets or sets the price per unit. Double Text value.

For example, <unit_pricing_measure unit="oz">34.5<\unit_pricing_measure>

Warning

Defines a warning message.

Name Value Type XML element name
domain For internal use only. String <domain>
message A description of the warning. String <internalReason>
reason The reason why the offer generated a warning. For example, you did not provide an identifier (gtin, mpn, or brand) when the manufacturer is known to have assigned them. String <reason>

HTTP status codes

The requests may return the following HTTP status codes.

Status code Description
200 Success.
204 Successfully deleted the product.
400 Bad request. Either a query parameter value is not valid or something in the request body is not valid.

Batch: If an error occurs, the batch item that failed will include the errors.
401 Unauthorized. The user's credentials are not valid.
404 Not found.
409 Conflict. The operation could not be completed due to a conflict with the current state of the resource.
413 Request entity too large. The size of the request exceeds the maximum allowed.
500 Server error.