Content API for Shopping

Product Items Feed

This document describes the requirements for submitting product items using the Content API for Shopping.

Contents

  1. Using attributes
    1. Using namespaces
    2. Attribute definitions
    3. Attribute projections
  2. Managing data items
  3. Accessing Product Performance Data
  4. Item attributes
  5. Product XML tags
    1. Shipping rules
    2. Tax information
  6. AdWords-specific XML tags
  7. Destinations
  8. Region-specific attributes

Using attributes

The Content API for Shopping defines a set of attributes that should be used to describe product items. For information about the available attributes, see the Products Feed Specification Help Center article.

Using namespaces

In Atom feeds, attributes correspond to XML elements in one of the following namespaces:

  • atom: - Atom
  • app: - Atom Publishing Protocol
  • gd: - Google Data API
  • sc: - Content API for Shopping, general attributes
  • scp: - Content API for Shopping, product attributes

Specify the Google Data namespace, gd, like this:

xmlns:gd="http://schemas.google.com/g/2005"

Specify the Content API for Shopping namespaces, sc and scp, as follows:

xmlns:sc="http://schemas.google.com/structuredcontent/2009"
xmlns:scp="http://schemas.google.com/structuredcontent/2009/products"

The following attributes are encoded as XML elements in the Atom (atom:) namespace:

  • <title>
  • <link>
  • <entry>
  • <id>
  • <category>
  • <content>
  • <created>
  • <updated>

All other attributes use the Content API for Shopping namespaces.

  • The primary Content API for Shopping namespace (sc): http://schemas.google.com/structuredcontent/2009
  • The Content API for Shopping namespace for product items (scp): http://schemas.google.com/structuredcontent/2009/products

In the following example, the first element is an Atom Publishing Protocol tag, followed by several standard Atom attributes. The next set of attributes, using the sc: namespace, are generic Content API for Shopping attributes. The last set of attributes, using the scp: namespace, are product attributes.

<?xml version='1.0'?>
<entry xmlns="http://www.w3.org/2005/Atom"
    xmlns:app='http://www.w3.org/2007/app'
    xmlns:gd="http://schemas.google.com/g/2005"
    xmlns:sc="http://schemas.google.com/structuredcontent/2009"
    xmlns:scp="http://schemas.google.com/structuredcontent/2009/products" >
    <app:control>
        <sc:required_destination dest="ShoppingApi"/>
    </app:control>
    <title type="text">Cleopatra Child Costume</title>
    <link rel="alternate" type="text/html" href="http://www.replace-with-your-homepage.com/item2-info-page.html"/>
    <sc:id>123456</sc:id>
    <content type="text">
    Go as the Queen of the Nile in this beautiful Cleopatra costume. With beautiful details and shimmery fabric trims,
    you will have everything you need to complete a night of Halloween magic.
    </content>
    <sc:content_language>en</sc:content_language>
    <sc:target_country>US</sc:target_country>
    <scp:product_type>Clothing &amp; Accessories &gt; Clothing &gt; Costumes</scp:product_type>
    <scp:price unit="usd">20</scp:price>
    <scp:brand>Southern Dream</scp:brand>
    <scp:color>white</scp:color>
    <scp:condition>new</scp:condition>
</entry>

Attribute definitions

An attribute definition is an XML tag that specifies an attribute name and value. Product attributes can be specified in generic or simplified form. Simplified form can only be used for some known attributes, see Item attributes. To specify an attribute in generic form, use the following XML tag format:

<sc:attribute name="attribute_name" type="attribute_type" unit="unit"
>attribute_value</sc:attribute>

The parameters type and unit are optional. You can find a list of available attribute types in the Reference Guide. The default type is text.

The unit parameter is only used for attributes of type float and int. When an attribute describes a price, the unit must specify the currency.

For example, to specify the attribute of name price and unit of usd:

<sc:attribute name="price" unit="usd">9.99</sc:attribute>

To specify a known attribute in simplified form:

<scp:price unit='usd'>9.99</scp:price>
  

To specify multiple values for a single attribute name, you must include multiple attributes with the same name. For example, the data item shown above specifies multiple values for the scp:color attribute.

If an attribute name includes a space, you must replace the space with an underscore. For instance, a online only attribute can be specified using the XML element <scp:online_only>. The Products Feed Specification Help Center article contains a list of recognized attributes.

To specify an attribute group in generic form, use the following format:

<sc:group name="group_name">
    attributes
</sc:group>
  

For example:

<sc:group name="tax">
   <sc:attribute name="country">US</sc:attribute>
   <sc:attribute name="region">CA</sc:attribute>
   <sc:attribute name="rate">8.25</sc:attribute>
   <sc:attribute name="tax ship">true</sc:attribute>
</sc:group>
  

As with attributes, known attribute groups can also be specified in simplified form. For example:

<scp:tax>
   <scp:tax_country>US</scp:tax_country>
   <scp:tax_region>CA</scp:tax_region>
   <scp:tax_rate>8.25</scp:tax_rate>
   <scp:tax_ship>true</scp:tax_ship>
</scp:tax>
  

Back to top

Attribute projections

Projections are used to determine the format of attributes in the XML responses returned by the Content API for Shopping. The Content API for Shopping defines two projections, schema and generic. You can specify the projection to use by including the projection type in the URL of the request to the API.

When using the schema projection, known attributes are returned in the simplified format:

<sc:attribute_name>
    attribute value
</sc:attribute_name>

When using the generic projection, all attributes are returned in the generic format:

<sc:attribute name="attribute_name" type="attribute_type" unit="unit">
    attribute value
</sc:attribute>

Managing data items

You can use the Content API for Shopping to programmatically post new items, and edit or delete items you have posted. The following sections describe options you have for the items you submit, followed by instructions for inserting updating and deleting.

Using item identifiers

When you insert a new product item, it is required that you specify a unique alphanumeric identifier for the <sc:id> attribute. Item identifiers must be unique within your account. If you specify a value for the <sc:id> attribute that is already associated with one of your items, the data in that item is overwritten by the data in the new item.

If you sell the same product in multiple countries you have to insert one item for each target country, but the ID must be unique across all your items in all countries. To avoid items being overwritten a common approach is to append the target country to the ID.

Once an item is inserted using the Content API for Shopping, you cannot change the value of the <sc:id> attribute, or remove the attribute. If you attempt to do so, the server will return an error.

Back to top

Retrieving all your items

To retrieve the list of data items belonging to your account, you make a HTTP GET request to the items feed. For example the following URL forms a request for the items feed of the customer with id 12345, in a generic format (see Attribute projections):

https://content.googleapis.com/content/v1/12345/items/products/generic

You can specify the maximum number of data items to be returned by using the max-results URL parameter. If specified, must be less than 250. If not specified, the default value of 25 will be used. For example the following URL specifies that there should be no more than 10 items:

https://content.googleapis.com/content/v1/12345/items/products/generic?max-results=10

The response is a list of entries (as described above) inside a <feed>. If you have more than max-results items, the returned feed will contain a next link (atom:link element with a rel="next" attribute) that you can use to obtain the next set of items. This way, you can go through all your items. If such a link is not present, you have already retrieved all your items. For example if you have more than 10 items and you have executed the request above, the returned feed will contain a link element resembling:

<link rel="next" type="application/atom+xml"
  href="https://content.googleapis.com/content/v1/12345/items/products/generic?start-token=823427fa7184932af43&amp;max-results=10"/>

Retrieving a single item

You can retrieve data about only one item by executing a HTTP GET request to the item's unique URL. An item's unique URL is formed using the channel, language, target country and ID you submitted with the item. For example, to retrieve an online item you submitted with ID "id1234" for use in the US with English content language and retrieve the response in schema form, you'll execute a HTTP GET request to:

https://content.googleapis.com/content/v1/12345/items/products/schema/online:en:US:id1234

Inserting items

To insert a data item, you make a HTTP POST request to the items feed. The response will contain the data item you inserted formatted with the requested projection, or any errors that occurred.

For example, if your Account ID is 12345 and you wish to see the item returned in generic form as response, perform a POST to:

https://content.googleapis.com/content/v1/12345/items/products/generic

For more information about the attributes required for Product items, see the Product item requirements documentation.

Updating items

To update a data item, make a HTTP PUT request containing the updated data item to the item's unique URL. For example, to update an online item you submitted with ID "id1234" for use in the US with English content language and receive the response in generic form, you'll execute a HTTP PUT request to:

https://content.googleapis.com/content/v1/12345/items/products/generic/online:en:US:id1234

Deleting items

To delete a data item make a HTTP DELETE request to the item's unique URL.

Back to top

Accessing Product Performance Data

The Content API for Shopping allows users to view data on how often products have been clicked on Google (e.g., Google Shopping and Google Book Search) as well as through paid Product Listing Ad campaigns.

To access this data, add the query parameters performance.start and performance.end to the GET request URI when retrieving a list of products. Each of these parameters should be a date, one for the start, and one for the end of the required period of performance data. For example:

https://content.googleapis.com/content/v1/12345/items/products/schema?performance.start=2011-08-18&performance.end=2011-08-19
    

The resulting feed will have the additional sc:performance element containing the performance data as a list of sc:datapoint elements. For example:

<sc:performance>
  <sc:datapoint date="2011-08-18" paid_clicks="101" />
  <sc:datapoint date="2011-08-19" paid_clicks="109" />
</sc:performance>
    

This data can then be used to track relative performance of products over time as well as the performance of ad campaigns.

Item attributes

A data item is an XML construct that describes an item. Each data item starts with the <entry> tag, includes a set of attributes that describe the item in question, and ends with the </entry> tag.

The following is an example of a data item that describes a black camera for sale in the US:

<?xml version='1.0'?>
<entry xmlns="http://www.w3.org/2005/Atom"
    xmlns:app='http://www.w3.org/2007/app'
    xmlns:gd="http://schemas.google.com/g/2005"
    xmlns:sc="http://schemas.google.com/structuredcontent/2009"
    xmlns:scp="http://schemas.google.com/structuredcontent/2009/products" >
  <title>Camera</title>
  <content type="text">A great compact body to make it easy to get a great shot everytime.</content>
  <sc:id>123456</sc:id>
  <link rel="alternate" type="text/html" href="http://www.replace-with-your-homepage.com/item1-info-page.html"/>
  <sc:image_link>http://www.example.com/image1.jpg</sc:image_link>
  <sc:target_country>US</sc:target_country>
  <sc:content_language>en</sc:content_language>
  <scp:brand>Acme</scp:brand>
  <scp:condition>new</scp:condition>
  <scp:gtin>00013803105384</scp:gtin>
  <scp:price unit="usd">25</scp:price>
  <scp:product_type>Cameras & Optics &gt; Cameras &gt;&gt; Digital Cameras</scp:product_type>
  <scp:color>black</scp:color>
  <scp:availability>in stock</scp:availability>
  <scp:shipping_weight unit="lb">0.1</scp:shipping_weight>
  <scp:shipping>
     <scp:shipping_country>US</scp:shipping_country>
     <scp:shipping_region>MA</scp:shipping_region>
     <scp:shipping_service>Speedy Shipping - Ground</scp:shipping_service>
     <scp:shipping_price unit="usd">5.95</scp:shipping_price>
  </scp:shipping>
  <scp:shipping>
     <scp:shipping_country>US</scp:shipping_country>
     <scp:shipping_region>024*</scp:shipping_region>
     <scp:shipping_service>Speedy Shipping - Air</scp:shipping_service>
     <scp:shipping_price unit="usd">7.95</scp:shipping_price>
  </scp:shipping>
  <scp:tax>
     <scp:tax_country>US</scp:tax_country>
     <scp:tax_region>CA</scp:tax_region>
     <scp:tax_rate>8.25</scp:tax_rate>
     <scp:tax_ship>true</scp:tax_ship>
  </scp:tax>
  <scp:tax>
     <scp:tax_country>US</scp:tax_country>
     <scp:tax_region>926*</scp:tax_region>
     <scp:tax_rate>8.75</scp:tax_rate>
     <scp:tax_ship>false</scp:tax_ship>
  </scp:tax>
  <app:control>
    <sc:required_destination dest="ProductSearch"/>
  </app:control>
</entry>

In the GData representation of the item, supply the data described in the following table.

Data Required XML Element Description
ID Yes <sc:id> An <sc:id> attribute. See Using Item Identifiers for more information on this attribute.
Title Yes <title> The item's title in the standard Atom <title> element.
Description Yes <content>

The item's description in the standard Atom <content> element. Specify the type as text.
Example: <content type="text">My item description</content>

Include only information relevant to the item. We recommend you submit at least 500 characters, the maximum is 10,000 characters.

Link to item page Yes <link> A link to a page where the item can be purchased. For example, if you sell postcards using an e-commerce site, each item must contain a link to the HTML page on your site where a customer can buy the postcard represented by that item.

Use the standard Atom link element, as in the following example: <link rel='alternate' type='text/html' href='http://www.somehost.com/123456jsh9'/>

The link you provide must point to a page under your Website URL, as specified on the Settings page of your Google Merchant Center account. For example, if your Website URL is http://www.somehost.com, the item links must be under www.somehost.com.
Image link Yes (except Japan) <sc:image_link> The URL of an associated image for an item.

If you have multiple different images of the item, submit the main view using this attribute, and include all other views in the additional image link attribute.
  • Submit the largest, full-size image you have for the product, up to 4MB file size.
  • We recommend images at least 800 pixels in height or width.
  • Do not scale up images or submit thumbnails.
  • For apparel products we require images of at least 250 x 250 pixels.

Required for all items (For feeds targeting Japan, this is a recommended attribute, not a required attribute).

Example: <sc:image_link>http://www.exmpl.com/image1.jpg< /sc:image_link>

The URL must include the scheme portion, for example: http://.

Additional image link No <sc:additional_image_link>

The URLs of any additional images for the item. This tag may be repeated.

Example: <sc:additional_image_link> http://www.exmpl.com/image2.jpg </sc:additional_image_link>

Language used in the item content Yes <sc:content_language> The <sc:content_language> and the <sc:target_country> for the item as follows, for example:
  • United States
    <sc:content_language>en</sc:content_language>
    <sc:target_country>US</sc:target_country>
  • United Kingdom
    <sc:content_language>en</sc:content_language>
    <sc:target_country>GB</sc:target_country>
  • Germany
    <sc:content_language>de</sc:content_language>
    <sc:target_country>DE</sc:target_country>
Target country Yes <sc:target_country>
Channel No <sc:channel> The item's channel. Supported values are:
  • online, which is the default
  • local

Example: <sc:channel>online</sc:channel>

Expiration date No <sc:expiration_date> The date that item listing will expire.

Example: <sc:expiration_date>
2010-08-19</sc:expiration_date>


Note: If not provided, the default is 30 days from now. If a date is specified that is more than 30 days away, it's ignored and the default is applied.
Adult No <sc:adult> Set to true if the item is not family safe.

For more information about required and recommended attributes for items, see the Product XML tags.
The namespaces of the attributes refer to the following declarations: xmlns='http://www.w3.org/2005/Atom' and xmlns:sc='http://schemas.google.com/structuredcontent/2009'.

Product XML tags

Data Required XML Element Description
age group Yes, in some cases <scp:age_group> The item's target age group. Supported values are:
  • adult
  • kids

Example:
<scp:age_group>adult</scp:age_group>

Required in the United States, United Kingdom, France, Germany, and Japan if the Google product type is part of Apparel & Accessories with a small number of exceptions.

availability Yes, in some cases <scp:availability> The item's availability. Supported values are:
  • in stock
  • available for order
  • out of stock
  • preorder

Example:
<scp:availability>in stock</scp:availability>

Although required only for the United States, United Kingdom, France, Germany, and Japan, retailers from other locales should include this attribute if they want to submit out of stock items.

brand No (except United States) <scp:brand>

The item's brand. This should be clearly recognized by consumers. This is required if the Google product type is part of Apparel & Accessories

If no brand is available, as in the case of custom-made goods, this can be set to the designer's, or the store's, name.

Example:
<scp:brand>acme</scp:brand>

color Yes, in some cases <scp:color> The item's color. Google may or may not surface the same label in results.

Example:
<scp:color>red</scp:color>

Required in the United States, United Kingdom, France, Germany, and Japan if the Google product type is part of Apparel & Accessories with a small number of exceptions.

For more details on submitting product variant attributes, see Feed Specification.
condition Yes <scp:condition> The item's condition. This must be one of the following values:
  • new
  • used
  • refurbished

Example:
<scp:condition>refurbished</scp:condition>

energy efficiency class Yes, in some cases <scp:energy_efficiency_class> The item's energy efficiency class.

Example:
<scp:energy_efficiency_class>
  A+++
</scp:energy_efficiency_class>


Specify to comply with local, state, or federal laws applicable to the country your product listings are targeting.

Required for Germany, France, UK, Italy, Spain, Switzerland, Czech Republic, the Netherlands.
gender Yes, in some cases <scp:gender> The item's target gender. Supported values are:
  • unisex
  • female
  • male

Example:
<scp:gender>unisex</scp:gender>

This tag is required in the United States, United Kingdom, France, Germany, and Japan if the Google product type is part of Apparel & Accessories with a small number of exceptions.

google product category Yes <scp:google_product_category>

The item's Google category. Example:
<scp:google_product_category> Media &gt; Books </scp:google_product_category>

The value must be one of the categories listed in the Product type taxonomy. Note that & and > characters must be encoded as &amp; and &gt;

gtin No <scp:gtin>

The item's Global Trade Item Number. For example: the ISBN number for a book; or the Universal Product Code; or the International Article Number (formerly the European Article Number).

Example:
<scp:gtin>00013803105384</scp:gtin>

identifier exists Yes, in some cases <scp:identifier_exists> Specify as true if the item has no manufacturer part number or any other industry standard product identifier.

Must be false if the item is in a category where unique product identifiers are required.

Example:
<scp:identifier_exists>
  false
</scp:identifier_exists>
item group id No <scp:item_group_id>

An identifier for items with variants. This is used to link items that have different values for the color, material, pattern, or size fields, for example a shirt offered in different sizes.

This tag is required for all item variants. For more details on submitting item variant attributes, see Feed Specification.

Example:
<scp:item_group_id>R1726122</scp:item_group_id>

material No <scp:material>

The material of which the item is made. For more details on submitting item variant attributes, see Feed Specification.

Example:
<scp:material>cotton</scp:material>

multipack Yes, in some cases <scp:multipack> The number of products in a merchant-defined custom multipack. Example:
<scp:multipack>
  12
</scp:multipack>


You must also specify the brand, gtin, and mpn for the manufacturer-defined product that forms the basis of the multipack.
mpn No <scp:mpn> The Manufacturer's Part Number. This is a unique code determined by the item's manufacturer. Example:
<scp:mpn>X1234552334</scp:mpn>
online only Yes, in some cases <scp:online_only>

Accepted values:

  • 'y': if any item is not available in your store to purchase.
  • 'n': if a customer can buy the posted item at your physical location - this is the default.

Required if you've submitted your store locations, and you sell online only. Example:
<scp:online_only>y</scp:online_only>

pattern No <scp:pattern>

The item's pattern. Example:
<scp:pattern>polka dots</scp:pattern>

For more details on submitting item variant attributes, see Feed Specification.

price Yes <scp:price> The item's price. Requires a float and a unit. Example:
<scp:price unit="USD">25</scp:price>
product review average No <scp:product_review_average>

The average rating for the item based on a one to five scale, with 5 being the highest rating. The average should be based on the reviews and ratings that are displayed on your landing page and must be in between 1.0 and 5.0.

Example:
<scp:product_review_average>
  3.75
</scp:product_review_average>

product review count No <scp:product_review_count> The item's total number of reviews. Only count reviews and ratings that are displayed on your landing page. Example:
<scp:product_review_count>
  9
</scp:product_review_count>
product type No <scp:product_type>

The item's type. The example specifies an item in the category "Clothing & Accessories > Clothing > Outerwear > Sweaters". Note that & and > characters must be encoded as &amp; and &gt;.

Setting this attribute is strongly recommended, even if a Google Product Category is also submitted. For more information, see the Product Type Attribute Help Center article.

Example:
<scp:product_type>Clothing &amp; Accessories &gt; Clothing &gt; Outerwear &gt; Sweaters</scp:product_type>

sale price No <scp:sale_price>

The advertised sale price. For more information, see the Submit your sale information Help Center article.

Example:
<scp:sale_price unit="USD">9.99</scp:sale_price>

sale price effective date No <scp:sale_price_effective_date> The start and end date and time for the sale price. It's recommended you include a time zone relative to GMT. In the example:
  • start date is December 26, 2012
  • start time is 16:00
  • start time zone is GMT-8, which represents PST
  • end date is January 13, 2013
  • end time is 16:00
  • end time zone is GMT-8, which represents PST
Example:
<scp:sale_price_effective_date>
  2012-12-26T16:00-08:00/2013-01-13T16:00-08:00
</scp:sale_price_effective_date>


For more information, see the Submit your sale information Help Center article.

shipping No <scp:shipping> See Shipping rules.
shipping weight No <scp:shipping_weight> The item's shipping weight. Requires a float and a unit. Valid units are:
  • lb
  • pound
  • oz
  • ounce
  • g
  • gram
  • kg
  • kilogram

Example:
<scp:shipping_weight unit="kg">9</scp:shipping_weight>

size No <scp:size> Available size of an item. Such as: small, medium, large. You can include multiple values.

This tag is required if the google product type is part of Apparel & Accessories > Clothing or Apparel & Accessories > Shoes.

Example:
<scp:size>medium</scp:size>

For more details on submitting product variant attributes, see Feed Specification.

tax No <scp:tax> See Tax information.
unit pricing measure Yes, in some cases <scp:unit_pricing_measure>

The dimension by which the item is sold. Supported dimensions are weight, volume, length, and area.

The following units are supported:

  • weight: mg, g, kg
  • volume: ml, cl, l, cbm
  • length: cm, m
  • area: sqm

Required for Germany, France, UK, Italy, Spain, Switzerland, Czech Republic, Netherlands.

Example:
<scp:unit_pricing_measure unit="g">
  10
</scp:unit_pricing_measure>

unit pricing base measure Yes, in some cases <scp:unit_pricing_base_measure> Your preference of the denominator of the unit price. Google might show a different base measure to make the unit prices on a page more comparable.

The numerical value must be 1, 10, 100, 75cl, 50kg, or 1000kg. A unit without a numerical value is not accepted.

If this attribute is present you must also specify unit_pricing_measure.

Required for Germany, France, UK, Italy, Spain, Switzerland, Czech Republic, Netherlands.

Example:
<scp:unit_pricing_base_measure unit="g">
  100
</scp:unit_pricing_measure>

Exception: Both the age_group and gender tags are usually required within the Apparel & Accessories taxonomy, but are not for the following subcategories:

  • Apparel & Accessories > Clothing Accessories > Pinback Buttons
  • Apparel & Accessories > Clothing Accessories > Tie Clips
  • Apparel & Accessories > Clothing Accessories > Wristbands
  • Apparel & Accessories > Shoe Accessories > Shoe Covers
  • Apparel & Accessories > Shoe Accessories > Shoelaces
  • Apparel & Accessories > Shoe Accessories > Spurs
  • Apparel & Accessories > Watch Accessories > Watch Bands

For a list of all product-specific attributes, see the Feed Specification. Attributes that do not exist in the xmlns:scp='http://schemas.google.com/structuredcontent/2009/products namespace can be added as generic attributes.

Shipping rules

If you insert a product that includes shipping information, you must describe the shipping information using the <scp:shipping> element. The following table contains the sub-elements of the <scp:shipping> element.

Data Required XML Element Description
Price Yes <scp:shipping_price> Fixed shipping price, represented as a number. Specify currency as part of the attribute definition, using unit="XXX", where XXX represents the three-character currency code.
Country No <scp:shipping_country> The two-letter ISO 3166 country code for the country to which an item will ship.
Region No <scp:shipping_region> The geographic region to which a shipping rate applies, for example: in the US, the two-letter state abbreviation, ZIP code, or ZIP code range using * wildcard. When specifying a region, the <scp:tax_country> element is required.
Shipping service No <scp:shipping_service> A free-form description of the service class or delivery speed.

For example, the following shipping attribute states that the item can be shipped to California (CA). It will be sent by truck, and the additional cost for shipping is 20 USD.

<scp:shipping>
  <scp:shipping_country>US</scp:shipping_country>
  <scp:shipping_region>CA</scp:shipping_region>
  <scp:shipping_service>By truck</scp:shipping_service>
  <scp:shipping_price unit="USD">20</scp:shipping_price>
</scp:shipping>

If the country value isn't included, the rate applies to the target country of the item. If the region value is included, the country must also be included.

Each item may have a maximum of 100 shipping rules. Multiple shipping methods with the same region and shipping service are not allowed.

Back to top

Tax information

If you insert an item that includes tax information, you must describe it using the <scp:tax> element. The <scp:tax> element contains the following sub elements:

Data Required XML Element Description
Tax rate Yes <scp:tax_rate> The percentage of tax rate that applies to the item price, 5.3 for example.
Country No <scp:tax_country> The country within which the item is taxed, specified with a two-letter ISO 3166 country code.
Region No <scp:tax_region> The geographic region to which the tax rate applies. For example, in the US, the two-letter state abbreviation, ZIP code, or ZIP code range using * wildcard. When specifying a region, the <scp:tax_country> element is required.
Taxable shipping? No <scp:tax_ship> Set to true if you charge tax on shipping. The default is false.

The following example tax attribute states that the tax rate is 5.3% for all zip-codes in Naples, FL (341*). Shipping fees are subject to taxes.

<scp:tax>
    <scp:tax_country> US </scp:tax_country>
    <scp:tax_region> 341* </scp:tax_region>
    <scp:tax_rate> 5.3 </scp:tax_rate>
    <scp:tax_ship> yes </scp:tax_ship>
</scp:tax>

Rate is required, whereas country, region, and tax_ship are optional. If country is not included, we assume the rate is for the target country of the item. If the region value is included, the country must also be included. If tax_ship is not included, the default value is false.

Each item may have a maximum of 100 tax rules.

Back to top

AdWords-specific XML tags

Data Required Example Description
Grouping No <scp:adwords_grouping>
  comforters
</scp:adwords_grouping>
Used to group items in an arbitrary way. This can be used for Product Filters to limit a campaign to a group of items, or Product Targets to bid differently for a group of items. This is required if the advertiser wants to bid differently to different subsets of items in the CPC or CPA % version. It can only hold one value.

Please note that this attribute is not supported in Shopping campaigns. The row below on custom label attributes for Shopping campaigns has more information about the attributes you can use for additional categorization in these campaigns. Learn more about Shopping campaigns.
Labels No <scp:adwords_labels>
  clothing
</scp:adwords_labels>

<scp:adwords_labels>
  shoes
</scp:adwords_labels>
Similar to adwords_grouping, but only works on CPC. This can hold multiple values, allowing an item to be tagged with multiple labels.

Please note that this attribute is not supported in Shopping campaigns. The row below on custom label attributes for Shopping campaigns has more information about the attributes you can use for additional categorization in these campaigns. Learn more about Shopping campaigns.
Redirect No <scp:adwords_redirect>
  http://www.merchant.com/product.html
</scp:adwords_redirect>
Allows advertisers to override the item URL.

This attribute can be used in both Shopping campaigns and regular Product Listing Ads campaigns.
Custom label No <scp:custom_label_0>seasonal</scp:custom_label_0>
<scp:custom_label_1>clearance</scp:custom_label_1>
<scp:custom_label_2>holiday</scp:custom_label_2>
<scp:custom_label_3>sale</scp:custom_label_3>
<scp:custom_label_4>best seller</scp:custom_label_4>
A custom label can be used to group the items in a Shopping campaign by values of your choosing, such as seasonal or clearance.

You can create up to five custom labels, numbered 0 through 4, for each item in your feed. You may submit one value per item for each custom label attribute.

Back to top

Destinations

Available destinations are: Google Shopping, Shopping API, and Commerce Search.

For each item, you specify the destination(s) through the <app:control> element. If no destination is specified, the default is Shopping. To receive validation errors for destinations without explicitly requiring those destinations, you may request to validate them, in which case you must also enable warnings to receive the validation errors in the response. The following <app:control> element explicitly requires the Shopping destination, requests validation errors for the Shopping API and excludes Commerce Search.

<app:control>
    <sc:required_destination dest="Shopping"/>
    <sc:validate_destination dest="ShoppingApi"/>
    <sc:excluded_destination dest="CommerceSearch"/>
</app:control>

Different destinations imply different validation requirements. If the verification for any required destination fails, the item will not be inserted and an error will be reported. To make your item visible more broadly to end users, the API will always try to maximize the number of destinations for which your item is intended. If you don't want your item used in a certain destination, you must explicitly exclude that destination using the exclude_destination element.

The Atom Publishing Protocol namespace URI is 'http://www.w3.org/2007/app'. Supported destinations depend on your account and, outside the US, may include:

Destination Name API Name Description
Google Shopping Shopping Your items appear on Google Shopping by default.
Commerce Search CommerceSearch Your items appear on Google Commerce Search if you are a Google Commerce Search user. Learn more.
Back to top

Region-specific attributes

Some attributes only apply in certain regions. These attributes must be specified in generic form.

Multiple installments (Brazil only)

You can specify an additional option for users to pay in multiple installments using the <sc:group name="installment"> element. The following table contains the sub-elements of the <sc:group name="installment"> element.

Data Required XML Element Description
Amount Yes <sc:attribute name="amount"> The amount that the buyer has to pay per month, represented as a number. Specify currency as part of the attribute definition, using unit="XXX", where XXX represents the three-character currency code.
Months Yes <sc:attribute name="months"> The number of installments that the buyer has to pay.

For example, the following installment attribute says that the buyer must make 6 monthly payments of 5.99 BRL each.

<sc:group name="installment">
    <sc:attribute name="amount" type="float" unit="BRL">5.99</sc:attribute>
    <sc:attribute name="months" type="int">6</sc:attribute>
</sc:group>

Back to top

Loyalty points (Japan only)

Include details of any loyalty points the buyer receives using the <sc:group name="loyalty points"> element. Loyalty points have to be issued by you. The table summarizes the sub-elements of <sc:group name="loyalty points">.

Data Required XML Element Description
Name No <sc:attribute name="name"> Name of loyalty points program. It is recommended that you limit the name to 12 full-width characters or 24 Roman characters.
Points value Yes <sc:attribute name="points value"> The retailer's loyalty points in absolute value.
Ratio No <sc:attribute name="ratio"> The ratio of a point when converted to currency. Google assumes currency based on Merchant Center settings. If ratio is left out, it defaults to 1.0.

In this example the buyer will receive 200 points on the "Rewards Card" loyalty scheme. Each point is worth 1.5 units of the purchasing currency.

<sc:group name="loyalty points">
    <sc:attribute name="name">Rewards Card</sc:attribute>
    <sc:attribute name="points value">200</sc:attribute>
    <sc:attribute name="ratio">1.5</sc:attribute>
</sc:group>

Back to top

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.