Product Item

Marketing API Version

v2.12

Reading

A Product Item object.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps

ads_management

Page management Apps

manage_pages
pages_show_list

Other Apps

No data

Parameters

Name	Description
`image_height` int64	Default value: `0` Height you'd like the image preview defined by `image_url` in
`image_width` int64	Default value: `0` Width you'd like the image preview defined by `image_url` in

Fields

Field	Description
`id` numeric string	A unique identifier for this item (which can be a variant for a product). If there are multiple instances of the same ID, all of those entries will be ignored. This maps to `retailer_id` after the product has been imported Default
`additional_image_urls` list<string>	More images. Include as many of these as you want
`additional_variant_attributes` list<KeyValue:string,string>	Additional attributes to distinguish the product in its variant group
`age_group` enum {adult, infant, kids, newborn, toddler}	Age group the product item is targeted towards
`applinks` AppLinks	App links for native platforms, e.g. Android, IOS and Windows Phone
`availability` enum {in stock, out of stock, preorder, available for order, discontinued}	Availability of the product item
`brand` string	Brand of the product Note: Either `gtin`, `mpn`, or `brand` are required
`category` string	Category of the product iteme.g., `Apparel & Accessories > Clothing > Dresses` Max size: 250
`color` string	Color of the product item
`commerce_insights` ProductItemCommerceInsights	Commerce insights for this product
`condition` enum {new, refurbished, used, cpo}	Condition of the product item
`currency` string	Currency for the product item
`custom_data` list<KeyValue:string,string>	Custom data key-value pairs
`custom_label_0` string	An optional custom label that can contain additional information about the item
`custom_label_1` string	An optional custom label that can contain additional information about the item
`custom_label_2` string	An optional custom label that can contain additional information about the item
`custom_label_3` string	An optional custom label that can contain additional information about the item
`custom_label_4` string	An optional custom label that can contain additional information about the item
`description` string	Description of the product item
`expiration_date` string	Date when the product expires
`gender` enum {female, male, unisex}	Gender the product item is targeted towards
`gtin` string	Global trade ID of the product item, one of: EAN, UPC, JAN, or ISBN Note: Either `gtin`, `mpn`, or `brand` are required
`image_url` string	Image URL of the product item This is the image used in the feed. Maintain aspect ratio 1.91:1. Images will be displayed at 1200x630px
`inventory` integer	inventory
`manufacturer_part_number` string	Manufacturer's ID for the product item Note: Either `gtin`, `mpn`, or `brand` are required
`material` string	Material of the product item Max size: 200
`name` string	Name of the product item Default
`ordering_index` int32	Index used for ordering items within a group
`pattern` string	Pattern of the product item
`price` string	Price of the product item, e.g. 5.99 USD
`product_catalog` ProductCatalog	Product catalog the product item is in
`product_feed` ProductFeed	Product feed the product item is in
`product_group` ProductGroup	Product group the product item is in, if applicable
`product_type` string	Retailer defined category of the product item. You can include more than one product type delimited by commas or include multiple `<product_type>` attributes. Max size: 750
`retailer_id` string	Retailer's ID for the product item. From the `id` field in the feed Default
`retailer_product_group_id` string	The parent ID for products that are variants of one another. e.g. the Red Polo Shirt is a variant of Polo Shirt. From the `item_group_id` field in the feed
`review_rejection_reasons` list<enum>	Reasons the product was rejected on review, if applicable
`review_status` enum {, pending, rejected, approved, outdated}	The internal review status of the product
`sale_price` string	Sale price of the product item, e.g. 3.99 USD
`sale_price_end_date` string	Date when the sale price ends
`sale_price_start_date` string	Date when the sale price starts
`shipping_weight_unit` enum {g, kg, oz, lb}	Shipping weight unit of the product item
`shipping_weight_value` float	Shipping weight value of the product item
`short_description` string	A brief description of the product
`size` string	Size of the product item
`start_date` string	Date when the product started to exist
`url` string	URL of the product item
`visibility` enum {staging, published}	Visibility of the product

Edges

Edge Description

Edge	Description
`product_sets`	Product sets that this item belongs to

product_sets

Product sets that this item belongs to

Validation Rules

Error	Description
100	Invalid parameter
200	Permissions error

Creating

Example TSV feed

Desktop only:

id  title   description google product category product type    link    image link  condition   availability    price   sale price  sale price effective date   gtin    brand   mpn item group id   gender  age group   color   size    shipping    shipping weight
DB_1    Dog Bowl In Blue    Solid plastic Dog Bowl in marine blue color Animals &gt; Pet Supplies   Bowls &amp; Dining &gt; Food &amp; Water Bowls  http://www.example.com/bowls/db-1.html  http://images.example.com/TV_123456.png new in stock    9.99 GBP                                                        UK::Standard:4.95 GBP

With Deep Links:

id  title   ios_url ios_app_store_id    ios_app_name    android_url android_class   android_package android_app_name    description google product category product type    link    image link  condition   availability    price   sale price  sale price effective date   gtin    brand   mpn item group id   gender  age group   color   size    shipping    shipping weight
DB_1    Dog Bowl In Blue    example-ios://electronic    42  Electronic Example iOS  example-android://electronic    com.electronic  com.electronic.Example  Electronic Example Android  Solid plastic Dog Bowl in marine blue color Animals &gt; Pet Supplies   Bowls &amp; Dining &gt; Food &amp; Water Bowls  http://www.example.com/bowls/db-1.html  http://images.example.com/TV_123456.png new in stock    9.99 GBP                                                        UK::Standard:4.95 GBP

XML Example RSS

<?xml version="1.0"?>
<rss xmlns:g="http://base.google.com/ns/1.0" version="2.0">
    <channel>
        <title>Test Store</title>
        <link>http://www.example.com</link>
        <description>An example item from the feed</description>

        <item>
            <g:id>DB_1</g:id>
            <g:title>Dog Bowl In Blue</g:title>
            <g:description>Solid plastic Dog Bowl in marine blue color</g:description>
            <g:link>http://www.example.com/bowls/db-1.html</g:link>
            <g:image_link>http://images.example.com/DB_1.png</g:image_link>
            <g:brand>Example</g:brand>
            <g:condition>new</g:condition>
            <g:availability>in stock</g:availability>
            <g:price>9.99 GBP</g:price>
            <g:shipping>
                <g:country>UK</g:country>
                <g:service>Standard</g:service>
                <g:price>4.95 GBP</g:price>
            </g:shipping>

            <g:google_product_category>Animals &gt; Pet Supplies</g:google_product_category>
        </item>
    </channel>
</rss>

XML Example ATOM

Desktop only:

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:g="http://base.google.com/ns/1.0">
    <title>Test Store</title>
    <link rel="self" href="http://www.example.com"/>

    <entry>
        <g:id>DB_1</g:id>
        <g:title>Dog Bowl In Blue</g:title>
        <g:description>Solid plastic Dog Bowl in marine blue color</g:description>
        <g:link>http://www.example.com/bowls/db-1.html</g:link>
        <g:image_link>http://images.example.com/DB_1.png</g:image_link>
        <g:brand>Example</g:brand>
        <g:condition>new</g:condition>
        <g:availability>in stock</g:availability>
        <g:price>9.99 GBP</g:price>
        <g:shipping>
            <g:country>UK</g:country>
            <g:service>Standard</g:service>
            <g:price>4.95 GBP</g:price>
        </g:shipping>

        <g:google_product_category>Animals &gt; Pet Supplies</g:google_product_category>
    </entry>
</feed>

With Deep Links:

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:g="http://base.google.com/ns/1.0">
    <title>Test Store</title>
    <link rel="self" href="http://www.example.com"/>

    <entry>
        <g:id>DB_1</g:id>
        <g:title>Dog Bowl In Blue</g:title>
        <g:description>Solid plastic Dog Bowl in marine blue color</g:description>
        <g:link>http://www.example.com/bowls/db-1.html</g:link>
        <g:image_link>http://images.example.com/DB_1.png</g:image_link>
        <g:brand>Example</g:brand>
        <g:condition>new</g:condition>
        <g:availability>in stock</g:availability>
        <g:price>9.99 GBP</g:price>
        <g:shipping>
            <g:country>UK</g:country>
            <g:service>Standard</g:service>
            <g:price>4.95 GBP</g:price>
        </g:shipping>
        <g:google_product_category>Animals &gt; Pet Supplies</g:google_product_category> 
        <applink property="ios_url" content="example-ios://electronic" />
        <applink property="ios_app_store_id" content="42" />
        <applink property="ios_app_name" content="Electronic Example iOS" />
        <applink property="iphone_url" content="example-iphone://electronic" />
        <applink property="iphone_app_store_id" content="43" />
        <applink property="iphone_app_name" content="Electronic Example iPhone" />
        <applink property="ipad_url" content="example-ipad://electronic" />
        <applink property="ipad_app_store_id" content="44" />
        <applink property="ipad_app_name" content="Electronic Example iPad" />
        <applink property="android_url" content="example-android://electronic" />
        <applink property="android_package" content="com.electronic" />
        <applink property="android_class" content="com.electronic.Example" />
        <applink property="android_app_name" content="Electronic Example Android" />
        <applink property="windows_phone_url" content="example-windows://electronic" />
        <applink property="windows_phone_app_id" content="64ec0d1b-5b3b-4c77-a86b-5e12d465edc0" />
        <applink property="windows_phone_app_name" content="Electronic Example Windows" />
    </entry>
</feed>

You can make a POST request to batch edge from the following paths:

/{product_catalog_id}/batch

When posting to this edge, a ProductItem will be created.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps

ads_management

Page management Apps

No data

Other Apps

Permissions are not usually requested.

Parameters

Name Description

Name	Description
`requests` list<JSON object>	Array of JSON objects containing batch requests. Each batch request consists of `retailer_id`, `method` and `data` fields. `retailer_id` - retailer's ID for a product. `method` - an operation of a batch request, either `CREATE`, `UPDATE` or `DELETE`. `data` - JSON object containing fields and values for a product. Learn more about these fields. Required

requests

list<JSON object>

Array of JSON objects containing batch requests. Each batch request consists of retailer_id, method and data fields.

retailer_id - retailer's ID for a product.

method - an operation of a batch request, either CREATE, UPDATE or DELETE.

data - JSON object containing fields and values for a product. Learn more about these fields.

Required

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.

Struct {

handles: List [

string

validation_status: List [

Struct {

errors: List [

Struct {

message: string,

}

retailer_id: string,

}

You can make a POST request to products edge from the following paths:

/{product_catalog_id}/products

When posting to this edge, a ProductItem will be created.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps

ads_management
business_management

Page management Apps

No data

Other Apps

No data

Parameters

Name	Description
`additional_image_urls` list<URL>	Additional product image URLs
`additional_variant_attributes` JSON object {string : string}	Additional attributes to distinguish the product in its variant group (ex: {"Scent" : "Fruity", "Style" : "Classic"})
`android_app_name` string	The name of the app (suitable for display)
`android_class` string	A fully-qualified Activity class name for intent generation
`android_package` string	A fully-qualified package name for intent generation
`android_url` string	A custom scheme for the Android app
`availability` enum{in stock, out of stock, preorder, available for order, discontinued}	Default value: `in stock` Availability of the product item
`brand` string	Brand of the product item
`category` string	Category of the product item. This is a required field
`checkout_url` URL	URL to add product item to cart and directly to checkout
`color` string	Color of the product item
`condition` enum{new, refurbished, used, cpo}	Default value: `new` The condition of the product item
`currency` ISO 4217 Currency Code	Currency for the product item Required
`custom_data` dictionary { string : <string> }	TBD
`custom_label_0` string	An optional custom label to associate with the product item. Max size: 100
`custom_label_1` string	An optional custom label to associate with the product item. Max size: 100
`custom_label_2` string	An optional custom label to associate with the product item. Max size: 100
`custom_label_3` string	An optional custom label to associate with the product item. Max size: 100
`custom_label_4` string	An optional custom label to associate with the product item. Max size: 100
`description` string	Description of the product item. Max size: 5000 RequiredSupports Emoji
`expiration_date` string	Item's expiration date (YYYY-MM-DD)
`gender` enum{female, male, unisex}	Gender the product item is targeted towards
`gtin` string	Global trade ID of the product item
`image_url` URI	URL of the product image
`inventory` int64	Inventory count for the product item
`ios_app_name` string	The name of the app (suitable for display)
`ios_app_store_id` int64	The app ID for the App Store
`ios_url` string	A custom scheme for the iOS app
`ipad_app_name` string	The name of the app (suitable for display)
`ipad_app_store_id` int64	The app ID for the App Store
`ipad_url` string	A custom scheme for the iPhone app
`iphone_app_name` string	The name of the app (suitable for display)
`iphone_app_store_id` int64	The app ID for the App Store
`iphone_url` string	A custom scheme for the iPhone app
`manufacturer_part_number` string	Manufacturer's ID for the product item
`material` string	Material of the product item Max size: 200
`name` string	Name/title of the product item RequiredSupports Emoji
`offer_price_amount` int64	Offer price of the item with 2 digits added for cents (ex: use "100" for 1 or "599" for 5.99)
`offer_price_end_date` datetime/timestamp	Date or unix timestamp when the offer price ends
`offer_price_start_date` datetime/timestamp	Date or unix timestamp when the offer price starts
`ordering_index` int64	Index used for ordering items within a group
`pattern` string	Pattern of the product item
`price` int64	Price of the item with 2 digits added for cents (ex: use "100" for 1 or "599" for 5.99) Required
`product_type` string	Retailer defined category of the product item. Max size: 750
`retailer_id` string	A unique identifier for this item (which can be a variant for a product). This field is required.
`retailer_product_group_id` string	Item group ID that this product is a variant of
`sale_price` int64	Sale price of the item with 2 digits added for cents (ex: use "100" for 1 or "599" for 5.99)
`sale_price_end_date` datetime	Date when the sale price ends
`sale_price_start_date` datetime	Date when the sale price starts
`short_description` string	A brief description of the product
`size` string	Size of the product item
`start_date` string	Date when the product started to exist
`url` URL	URL of the product item Required
`visibility` enum{staging, published}	Default value: `published` Visibility of the product item
`windows_phone_app_id` string	The app ID (a GUID) for app store
`windows_phone_app_name` string	The name of the app (suitable for display)
`windows_phone_url` string	A custom scheme for the Windows Phone app

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.

Struct {

id: numeric string,

}

You can make a POST request to products edge from the following paths:

/{product_group_id}/products

When posting to this edge, a ProductItem will be created.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps

manage_pages

Page management Apps

manage_pages
pages_show_list

Other Apps

No data

Parameters

Name	Description
`additional_image_urls` list<URL>	Additional product image URLs
`additional_variant_attributes` JSON object {string : string}	Additional attributes to distinguish the product in its variant group (ex: {"Scent" : "Fruity", "Style" : "Classic"})
`android_app_name` string	The name of the app (suitable for display)
`android_class` string	A fully-qualified Activity class name for intent generation
`android_package` string	A fully-qualified package name for intent generation
`android_url` string	A custom scheme for the Android app
`availability` enum{in stock, out of stock, preorder, available for order, discontinued}	Default value: `in stock` Availability of the product item
`brand` string	Brand of the product item
`category` string	Category of the product item. This is a required field
`checkout_url` URL	URL to add product item to cart and directly to checkout
`color` string	Color of the product item
`condition` enum{new, refurbished, used, cpo}	Default value: `new` The condition of the product item
`currency` ISO 4217 Currency Code	Currency for the product item Required
`custom_data` dictionary { string : <string> }	TBD
`custom_label_0` string	An optional custom label to associate with the product item. Max size: 100
`custom_label_1` string	An optional custom label to associate with the product item. Max size: 100
`custom_label_2` string	An optional custom label to associate with the product item. Max size: 100
`custom_label_3` string	An optional custom label to associate with the product item. Max size: 100
`custom_label_4` string	An optional custom label to associate with the product item. Max size: 100
`description` string	Description of the product item. Max size: 5000 RequiredSupports Emoji
`expiration_date` string	Item's expiration date (YYYY-MM-DD)
`gender` enum{female, male, unisex}	Gender the product item is targeted towards
`gtin` string	Global trade ID of the product item
`image_url` URL	URL of the product image Required
`inventory` int64	Inventory count for the product item
`ios_app_name` string	The name of the app (suitable for display)
`ios_app_store_id` int64	The app ID for the App Store
`ios_url` string	A custom scheme for the iOS app
`ipad_app_name` string	The name of the app (suitable for display)
`ipad_app_store_id` int64	The app ID for the App Store
`ipad_url` string	A custom scheme for the iPhone app
`iphone_app_name` string	The name of the app (suitable for display)
`iphone_app_store_id` int64	The app ID for the App Store
`iphone_url` string	A custom scheme for the iPhone app
`manufacturer_part_number` string	Manufacturer's ID for the product item
`material` string	Material of the product item Max size: 200
`name` string	Name/title of the product item RequiredSupports Emoji
`offer_price_amount` int64	Offer price of the item with 2 digits added for cents (ex: use "100" for 1 or "599" for 5.99)
`offer_price_end_date` datetime/timestamp	Date or unix timestamp when the offer price ends
`offer_price_start_date` datetime/timestamp	Date or unix timestamp when the offer price starts
`ordering_index` int64	Index used for ordering items within a group
`pattern` string	Pattern of the product item
`price` int64	Price of the item with 2 digits added for cents (ex: use "100" for 1 or "599" for 5.99) Required
`product_type` string	Retailer defined category of the product item. Max size: 750
`retailer_id` string	A unique identifier for this item (which can be a variant for a product) Required
`sale_price` int64	Sale price of the item with 2 digits added for cents (ex: use "100" for 1 or "599" for 5.99)
`sale_price_end_date` datetime	Date when the sale price ends
`sale_price_start_date` datetime	Date when the sale price starts
`short_description` string	A brief description of the product
`size` string	Size of the product item
`start_date` string	Date when the product started to exist
`url` URL	URL of the product item Required
`visibility` enum{staging, published}	Default value: `published` Visibility of the product item
`windows_phone_app_id` string	The app ID (a GUID) for app store
`windows_phone_app_name` string	The name of the app (suitable for display)
`windows_phone_url` string	A custom scheme for the Windows Phone app

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.

Struct {

id: numeric string,

}

Validation Rules

Error	Description
100	Invalid parameter
200	Permissions error

Updating

You can update a ProductItem by making a POST request to /{product_item_id}.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps

ads_management
business_management

Page management Apps

manage_pages

Other Apps

No data

Parameters

Name	Description
`additional_image_urls` list<URL>	Additional product image URLs
`additional_variant_attributes` JSON object {string : string}	Additional attributes to distinguish the product in its variant group (ex: {"Scent" : "Fruity", "Style" : "Classic"})
`android_app_name` string	The name of the app (suitable for display)
`android_class` string	A fully-qualified Activity class name for intent generation
`android_package` string	A fully-qualified package name for intent generation
`android_url` string	A custom scheme for the Android app
`availability` enum{in stock, out of stock, preorder, available for order, discontinued}	Availability of the product item
`brand` string	Brand of the product item
`category` string	Category of the product item
`checkout_url` URL	URL to add product item to cart and directly to checkout
`color` string	Color of the product item
`condition` enum{new, refurbished, used, cpo}	The condition of the product item
`currency` ISO 4217 Currency Code	Currency for the product item
`custom_data` dictionary { string : <string> }	TBD
`custom_label_0` string	An optional custom label to associate with the product item. Max size: 100
`custom_label_1` string	An optional custom label to associate with the product item. Max size: 100
`custom_label_2` string	An optional custom label to associate with the product item. Max size: 100
`custom_label_3` string	An optional custom label to associate with the product item. Max size: 100
`custom_label_4` string	An optional custom label to associate with the product item. Max size: 100
`description` string	Description of the product item. Max size: 5000 Supports Emoji
`expiration_date` string	Item's expiration date (YYYY-MM-DD)
`gender` enum{female, male, unisex}	Gender the product item is targeted towards
`gtin` string	Global trade ID of the product item
`image_url` URL	URL of the product image
`inventory` int64	Inventory count for the product item
`ios_app_name` string	The name of the app (suitable for display)
`ios_app_store_id` int64	The app ID for the App Store
`ios_url` string	A custom scheme for the iOS app
`ipad_app_name` string	The name of the app (suitable for display)
`ipad_app_store_id` int64	The app ID for the App Store
`ipad_url` string	A custom scheme for the iPhone app
`iphone_app_name` string	The name of the app (suitable for display)
`iphone_app_store_id` int64	The app ID for the App Store
`iphone_url` string	A custom scheme for the iPhone app
`manufacturer_part_number` string	Manufacturer's ID for the product item
`material` string	Material of the product item Max size: 200
`name` string	Name/title of the product item Supports Emoji
`offer_price_amount` int64	Offer price of the item with 2 digits added for cents (ex: use "100" for 1 or "599" for 5.99)
`offer_price_end_date` datetime/timestamp	Date or unix timestamp when the offer price ends
`offer_price_start_date` datetime/timestamp	Date or unix timestamp when the offer price starts
`ordering_index` int64	Index used for ordering items within a group
`pattern` string	Pattern of the product item
`price` int64	Price of the item with 2 digits added for cents (ex: use "100" for 1 or "599" for 5.99)
`product_type` string	Retailer defined category of the product item. Max size: 750
`sale_price` int64	Sale price of the item with 2 digits added for cents (ex: use "100" for 1 or "599" for 5.99)
`sale_price_end_date` datetime	Date when the sale price ends
`sale_price_start_date` datetime	Date when the sale price starts
`short_description` string	A brief description of the product
`size` string	Size of the product item
`start_date` string	Date when the product started to exist
`url` URL	URL of the product item
`visibility` enum{staging, published}	Visibility of the product item
`windows_phone_app_id` string	The app ID (a GUID) for app store
`windows_phone_app_name` string	The name of the app (suitable for display)
`windows_phone_url` string	A custom scheme for the Windows Phone app

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.

Struct {

success: bool,

}

Validation Rules

Error	Description
100	Invalid parameter
200	Permissions error

Deleting

You can delete a ProductItem by making a DELETE request to /{product_item_id}.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps

ads_management
manage_pages
business_management

Page management Apps

manage_pages
pages_show_list

Other Apps

No data

Parameters

This endpoint doesn't have any parameters.

Return Type

Struct {

success: bool,

}

Validation Rules

Error	Description
100	Invalid parameter
801	Invalid operation
200	Permissions error