Marketing API Version

Product Item

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
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

NameDescription
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

FieldDescription

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.

additional_image_urls

list<string>

More images. Include as many of these as you want.

age_group

enum {adult, infant, kids, newborn, toddler}

Age group the product item is targeted towards.

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}

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

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

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

Product catalog the product item is in

product_feed

Product feed the product item is in

product_group

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

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

EdgeDescription

product_sets

Product sets that this item belongs to

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions 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:
When posting to this edge, a ProductItem will be created.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
No data
Page management Apps
No data
Other Apps
Permissions are not usually requested.

Parameters

NameDescription
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:
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

NameDescription
additional_image_urls
list<URL>

Additional product image URLs

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

Required
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}
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
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
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:
When posting to this edge, a ProductItem will be created.

Parameters

NameDescription
additional_image_urls
list<URL>

Additional product image URLs

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

Required
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}
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
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

ErrorDescription
100Invalid parameter
200Permissions 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
Page management Apps
No data
Other Apps
No data

Parameters

NameDescription
additional_image_urls
list<URL>

Additional product image URLs

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}

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
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

ErrorDescription
100Invalid parameter
200Permissions 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
Page management Apps
No data
Other Apps
No data

Parameters

This endpoint doesn't have any parameters.

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
801Invalid operation
200Permissions error