Graph API Version

Product Item

Reading

A Product Item object.

Example

GET /v8.0/{product-item-id} HTTP/1.1
Host: graph.facebook.com

/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/{product-item-id}',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */

/* make the API call */
FB.api(
    "/{product-item-id}",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{product-item-id}",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();

// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{product-item-id}"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

Parameter Description

Parameter	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

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_cdn_urls` list<list<KeyValue:string,string>>	CDN URLs of the additional product images
`additional_image_urls` list<string>	URLs of the additional product images
`additional_variant_attributes` list<KeyValue:string,string>	Additional attributes to distinguish the product in its variant group
`age_group` enum {adult, all ages, infant, kids, newborn, teen, toddler}	Age group the product item is targeted towards
`applinks` CatalogItemAppLinks	App links for native platforms, e.g. Android, IOS and Windows Phone
`availability` enum {in stock, out of stock, preorder, available for order, discontinued, pending}	Availability of the product item
`brand` string	Brand of the product Note: Either `gtin`, `mpn`, or `brand` are required
`capability_to_review_status` list<KeyValue:enum {SHOPS, US_MARKETPLACE, UNIVERSAL_CHECKOUT, TEST_CAPABILITY},enum {NO_REVIEW, PENDING, REJECTED, APPROVED, OUTDATED}>	Status of the product as a result of review on a specific capability represented by capability parameter, works for WhatsApp only
`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, used_like_new, used_good, used_fair, cpo, open_box_new}	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
`fb_product_category` string	Seller-provided Facebook product category of the item
`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_cdn_urls` list<KeyValue:string,string>	CDN URL of the primary product image
`image_url` string	URL of the primary product image
`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
`mobile_link` string	Link to a mobile-optimized external product page
`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
80004	There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.
368	The action attempted has been deemed abusive or is otherwise disallowed
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.

Parameters

Parameter Description

Parameter	Description
`allow_upsert` boolean	Default value: `true` Parameters specifying whether non existing items that are being updated should be inserted or should throw the error
`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. See [Catalog Batch API](https://developers.facebook.com/docs/marketing-api/catalog-batch) to learn more the list of fields and values for the data object. Required

allow_upsert

boolean

Default value: true

Parameters specifying whether non existing items that are being updated should be inserted or should throw the error

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. See [Catalog Batch API](https://developers.facebook.com/docs/marketing-api/catalog-batch) to learn more the list of fields and values for the data object.

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,

warnings: List [

Struct {

message: string,

}

Validation Rules

Error	Description
100	Invalid parameter
80004	There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.
200	Permissions error

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.

Parameters

Parameter	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, pending}	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
`commerce_tax_category` enum{FB_ANIMAL, FB_ANIMAL_SUPP, FB_APRL, FB_APRL_ACCESSORIES, FB_APRL_ATHL_UNIF, FB_APRL_CASES, FB_APRL_CLOTHING, FB_APRL_COSTUME, FB_APRL_CSTM, FB_APRL_HANDBAG, FB_APRL_JEWELRY, FB_APRL_SHOE, FB_APRL_SHOE_ACC, FB_APRL_SWIM, FB_APRL_SWIM_CHIL, FB_APRL_SWIM_CVR, FB_ARTS, FB_ARTS_HOBBY, FB_ARTS_PARTY, FB_ARTS_PARTY_GIFT_CARD, FB_ARTS_TICKET, FB_BABY, FB_BABY_BATH, FB_BABY_BLANKET, FB_BABY_DIAPER, FB_BABY_GIFT_SET, FB_BABY_HEALTH, FB_BABY_NURSING, FB_BABY_POTTY_TRN, FB_BABY_SAFE, FB_BABY_TOYS, FB_BABY_TRANSPORT, FB_BABY_TRANSPORT_ACC, FB_BAGS, FB_BAGS_BKPK, FB_BAGS_BOXES, FB_BAGS_BRFCS, FB_BAGS_CSMT_BAG, FB_BAGS_DFFL, FB_BAGS_DIPR, FB_BAGS_FNNY, FB_BAGS_GRMT, FB_BAGS_LUG_ACC, FB_BAGS_LUGG, FB_BAGS_MSGR, FB_BAGS_TOTE, FB_BAGS_TRN_CAS, FB_BLDG, FB_BLDG_ACC, FB_BLDG_CNSMB, FB_BLDG_FENCE, FB_BLDG_FUEL_TNK, FB_BLDG_HT_VNT, FB_BLDG_LOCK, FB_BLDG_MATRL, FB_BLDG_PLMB, FB_BLDG_PUMP, FB_BLDG_PWRS, FB_BLDG_S_ENG, FB_BLDG_STR_TANK, FB_BLDG_TL_ACC, FB_BLDG_TOOL, FB_BUSIND, FB_BUSIND_ADVERTISING, FB_BUSIND_AGRICULTURE, FB_BUSIND_AUTOMATION, FB_BUSIND_HEAVY_MACH, FB_BUSIND_LAB, FB_BUSIND_MEDICAL, FB_BUSIND_RETAIL, FB_BUSIND_SANITARY_CT, FB_BUSIND_SIGN, FB_BUSIND_STORAGE, FB_BUSIND_STORAGE_ACC, FB_BUSIND_WORK_GEAR, FB_CAMERA_ACC, FB_CAMERA_CAMERA, FB_CAMERA_OPTIC, FB_CAMERA_OPTICS, FB_CAMERA_PHOTO, FB_ELEC, FB_ELEC_ACC, FB_ELEC_ARCDADE, FB_ELEC_AUDIO, FB_ELEC_CIRCUIT, FB_ELEC_COMM, FB_ELEC_COMPUTER, FB_ELEC_GPS_ACC, FB_ELEC_GPS_NAV, FB_ELEC_GPS_TRK, FB_ELEC_MARINE, FB_ELEC_NETWORK, FB_ELEC_PART, FB_ELEC_PRINT, FB_ELEC_RADAR, FB_ELEC_SPEED_RDR, FB_ELEC_TOLL, FB_ELEC_VID_GM_ACC, FB_ELEC_VID_GM_CNSL, FB_ELEC_VIDEO, FB_FOOD, FB_FURN, FB_FURN_BABY, FB_FURN_BENCH, FB_FURN_CART, FB_FURN_CHAIR, FB_FURN_CHAIR_ACC, FB_FURN_DIVIDE, FB_FURN_DIVIDE_ACC, FB_FURN_ENT_CTR, FB_FURN_FUTN, FB_FURN_FUTN_PAD, FB_FURN_OFFICE, FB_FURN_OFFICE_ACC, FB_FURN_OTTO, FB_FURN_OUTDOOR, FB_FURN_OUTDOOR_ACC, FB_FURN_SETS, FB_FURN_SHELVE_ACC, FB_FURN_SHLF, FB_FURN_SOFA, FB_FURN_SOFA_ACC, FB_FURN_STORAGE, FB_FURN_TABL, FB_FURN_TABL_ACC, FB_GENERIC_TAXABLE, FB_HLTH, FB_HLTH_HLTH, FB_HLTH_JWL_CR, FB_HLTH_LILP_BLM, FB_HLTH_LTN_SPF, FB_HLTH_PRSL_CR, FB_HLTH_SKN_CR, FB_HMGN, FB_HMGN_BATH, FB_HMGN_DCOR, FB_HMGN_EMGY, FB_HMGN_FPLC, FB_HMGN_FPLC_ACC, FB_HMGN_GS_SFT, FB_HMGN_HS_ACC, FB_HMGN_HS_APP, FB_HMGN_HS_SPL, FB_HMGN_KTCN, FB_HMGN_LAWN, FB_HMGN_LGHT, FB_HMGN_LINN, FB_HMGN_LT_ACC, FB_HMGN_OTDR, FB_HMGN_POOL, FB_HMGN_SCTY, FB_HMGN_SMK_ACC, FB_HMGN_UMBR, FB_HMGN_UMBR_ACC, FB_MDIA, FB_MDIA_BOOK, FB_MDIA_DVDS, FB_MDIA_MAG, FB_MDIA_MANL, FB_MDIA_MUSC, FB_MDIA_PRJ_PLN, FB_MDIA_SHT_MUS, FB_OFFC, FB_OFFC_BKAC, FB_OFFC_CRTS, FB_OFFC_DSKP, FB_OFFC_EQIP, FB_OFFC_FLNG, FB_OFFC_GNRL, FB_OFFC_INSTM, FB_OFFC_LP_DSK, FB_OFFC_MATS, FB_OFFC_NM_PLT, FB_OFFC_PPR_HNDL, FB_OFFC_PRSNT_SPL, FB_OFFC_SEALR, FB_OFFC_SHIP_SPL, FB_RLGN, FB_RLGN_CMNY, FB_RLGN_ITEM, FB_RLGN_WEDD, FB_SFTWR, FB_SFWR_CMPTR, FB_SFWR_DGTL_GD, FB_SFWR_GAME, FB_SHIPPING, FB_SPOR, FB_SPORT_ATHL, FB_SPORT_ATHL_CLTH, FB_SPORT_ATHL_SHOE, FB_SPORT_ATHL_SPRT, FB_SPORT_EXRCS, FB_SPORT_INDR_GM, FB_SPORT_OTDR_GM, FB_TOYS, FB_TOYS_EQIP, FB_TOYS_GAME, FB_TOYS_PZZL, FB_TOYS_TMRS, FB_TOYS_TOYS, FB_VEHI, FB_VEHI_PART}	commerce_tax_category
`condition` enum{new, refurbished, used, used_like_new, used_good, used_fair, cpo, open_box_new}	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 Supports Emoji
`expiration_date` string	Item's expiration date (YYYY-MM-DD)
`fb_product_category` string	The facebook product category specified by the seller.
`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 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
`launch_date` string	launch_date
`manufacturer_part_number` string	Manufacturer's ID for the product item
`material` string	Material of the product item Max size: 200
`mobile_link` URI	Link to a mobile-optimized external product page
`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
`return_policy_days` int64	Return Policy Days
`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` URI	URL of the product item
`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
10800	Duplicate retailer_id when attempting to create a store collection
200	Permissions error

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.

Parameters

Parameter	Description
`additional_image_files` array<file>	additional_image_files
`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, pending}	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
`category_specific_fields` JSON object	JSON object containing category specific fields
`item_sub_type` enum {APPLIANCES, BABY_FEEDING, BABY_TRANSPORT, BEAUTY, BEDDING, CAMERAS, CELL_PHONES_AND_SMART_WATCHES, CLEANING_SUPPLIES, CLOTHING, CLOTHING_ACCESSORIES, COMPUTERS_AND_TABLETS, DIAPERING_AND_POTTY_TRAINING, ELECTRONICS_ACCESSORIES, FURNITURE, HEALTH, HOME_GOODS, JEWELRY, NURSERY, PRINTERS_AND_SCANNERS, PROJECTORS, SHOES_AND_FOOTWEAR, SOFTWARE, TOYS, TVS_AND_MONITORS, VIDEO_GAME_CONSOLES_AND_VIDEO_GAMES, WATCHES}	item_sub_type Required
`checkout_url` URL	URL to add product item to cart and directly to checkout
`color` string	Color of the product item
`commerce_tax_category` enum{FB_ANIMAL, FB_ANIMAL_SUPP, FB_APRL, FB_APRL_ACCESSORIES, FB_APRL_ATHL_UNIF, FB_APRL_CASES, FB_APRL_CLOTHING, FB_APRL_COSTUME, FB_APRL_CSTM, FB_APRL_HANDBAG, FB_APRL_JEWELRY, FB_APRL_SHOE, FB_APRL_SHOE_ACC, FB_APRL_SWIM, FB_APRL_SWIM_CHIL, FB_APRL_SWIM_CVR, FB_ARTS, FB_ARTS_HOBBY, FB_ARTS_PARTY, FB_ARTS_PARTY_GIFT_CARD, FB_ARTS_TICKET, FB_BABY, FB_BABY_BATH, FB_BABY_BLANKET, FB_BABY_DIAPER, FB_BABY_GIFT_SET, FB_BABY_HEALTH, FB_BABY_NURSING, FB_BABY_POTTY_TRN, FB_BABY_SAFE, FB_BABY_TOYS, FB_BABY_TRANSPORT, FB_BABY_TRANSPORT_ACC, FB_BAGS, FB_BAGS_BKPK, FB_BAGS_BOXES, FB_BAGS_BRFCS, FB_BAGS_CSMT_BAG, FB_BAGS_DFFL, FB_BAGS_DIPR, FB_BAGS_FNNY, FB_BAGS_GRMT, FB_BAGS_LUG_ACC, FB_BAGS_LUGG, FB_BAGS_MSGR, FB_BAGS_TOTE, FB_BAGS_TRN_CAS, FB_BLDG, FB_BLDG_ACC, FB_BLDG_CNSMB, FB_BLDG_FENCE, FB_BLDG_FUEL_TNK, FB_BLDG_HT_VNT, FB_BLDG_LOCK, FB_BLDG_MATRL, FB_BLDG_PLMB, FB_BLDG_PUMP, FB_BLDG_PWRS, FB_BLDG_S_ENG, FB_BLDG_STR_TANK, FB_BLDG_TL_ACC, FB_BLDG_TOOL, FB_BUSIND, FB_BUSIND_ADVERTISING, FB_BUSIND_AGRICULTURE, FB_BUSIND_AUTOMATION, FB_BUSIND_HEAVY_MACH, FB_BUSIND_LAB, FB_BUSIND_MEDICAL, FB_BUSIND_RETAIL, FB_BUSIND_SANITARY_CT, FB_BUSIND_SIGN, FB_BUSIND_STORAGE, FB_BUSIND_STORAGE_ACC, FB_BUSIND_WORK_GEAR, FB_CAMERA_ACC, FB_CAMERA_CAMERA, FB_CAMERA_OPTIC, FB_CAMERA_OPTICS, FB_CAMERA_PHOTO, FB_ELEC, FB_ELEC_ACC, FB_ELEC_ARCDADE, FB_ELEC_AUDIO, FB_ELEC_CIRCUIT, FB_ELEC_COMM, FB_ELEC_COMPUTER, FB_ELEC_GPS_ACC, FB_ELEC_GPS_NAV, FB_ELEC_GPS_TRK, FB_ELEC_MARINE, FB_ELEC_NETWORK, FB_ELEC_PART, FB_ELEC_PRINT, FB_ELEC_RADAR, FB_ELEC_SPEED_RDR, FB_ELEC_TOLL, FB_ELEC_VID_GM_ACC, FB_ELEC_VID_GM_CNSL, FB_ELEC_VIDEO, FB_FOOD, FB_FURN, FB_FURN_BABY, FB_FURN_BENCH, FB_FURN_CART, FB_FURN_CHAIR, FB_FURN_CHAIR_ACC, FB_FURN_DIVIDE, FB_FURN_DIVIDE_ACC, FB_FURN_ENT_CTR, FB_FURN_FUTN, FB_FURN_FUTN_PAD, FB_FURN_OFFICE, FB_FURN_OFFICE_ACC, FB_FURN_OTTO, FB_FURN_OUTDOOR, FB_FURN_OUTDOOR_ACC, FB_FURN_SETS, FB_FURN_SHELVE_ACC, FB_FURN_SHLF, FB_FURN_SOFA, FB_FURN_SOFA_ACC, FB_FURN_STORAGE, FB_FURN_TABL, FB_FURN_TABL_ACC, FB_GENERIC_TAXABLE, FB_HLTH, FB_HLTH_HLTH, FB_HLTH_JWL_CR, FB_HLTH_LILP_BLM, FB_HLTH_LTN_SPF, FB_HLTH_PRSL_CR, FB_HLTH_SKN_CR, FB_HMGN, FB_HMGN_BATH, FB_HMGN_DCOR, FB_HMGN_EMGY, FB_HMGN_FPLC, FB_HMGN_FPLC_ACC, FB_HMGN_GS_SFT, FB_HMGN_HS_ACC, FB_HMGN_HS_APP, FB_HMGN_HS_SPL, FB_HMGN_KTCN, FB_HMGN_LAWN, FB_HMGN_LGHT, FB_HMGN_LINN, FB_HMGN_LT_ACC, FB_HMGN_OTDR, FB_HMGN_POOL, FB_HMGN_SCTY, FB_HMGN_SMK_ACC, FB_HMGN_UMBR, FB_HMGN_UMBR_ACC, FB_MDIA, FB_MDIA_BOOK, FB_MDIA_DVDS, FB_MDIA_MAG, FB_MDIA_MANL, FB_MDIA_MUSC, FB_MDIA_PRJ_PLN, FB_MDIA_SHT_MUS, FB_OFFC, FB_OFFC_BKAC, FB_OFFC_CRTS, FB_OFFC_DSKP, FB_OFFC_EQIP, FB_OFFC_FLNG, FB_OFFC_GNRL, FB_OFFC_INSTM, FB_OFFC_LP_DSK, FB_OFFC_MATS, FB_OFFC_NM_PLT, FB_OFFC_PPR_HNDL, FB_OFFC_PRSNT_SPL, FB_OFFC_SEALR, FB_OFFC_SHIP_SPL, FB_RLGN, FB_RLGN_CMNY, FB_RLGN_ITEM, FB_RLGN_WEDD, FB_SFTWR, FB_SFWR_CMPTR, FB_SFWR_DGTL_GD, FB_SFWR_GAME, FB_SHIPPING, FB_SPOR, FB_SPORT_ATHL, FB_SPORT_ATHL_CLTH, FB_SPORT_ATHL_SHOE, FB_SPORT_ATHL_SPRT, FB_SPORT_EXRCS, FB_SPORT_INDR_GM, FB_SPORT_OTDR_GM, FB_TOYS, FB_TOYS_EQIP, FB_TOYS_GAME, FB_TOYS_PZZL, FB_TOYS_TMRS, FB_TOYS_TOYS, FB_VEHI, FB_VEHI_PART}	Commerce tax category
`condition` enum{new, refurbished, used, used_like_new, used_good, used_fair, cpo, open_box_new}	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 Supports Emoji
`expiration_date` string	Item's expiration date (YYYY-MM-DD)
`fb_product_category` string	Facebook product category for the item
`gender` enum{female, male, unisex}	Gender the product item is targeted towards
`gtin` string	Global trade ID of the product item
`image_url` URI	Required. 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
`mobile_link` URI	Link to a mobile-optimized external product page
`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
`return_policy_days` int64	return_policy_days
`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` URI	URL of the product item
`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
10800	Duplicate retailer_id when attempting to create a store collection
10801	Either "file" or "url" must be specified
200	Permissions error

Updating

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

Parameters

Parameter	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, pending}	Availability of the product item
`brand` string	Brand of the product item
`category` string	Category of the product item
`category_specific_fields` JSON object	JSON object containing category specific fields
`item_sub_type` enum {APPLIANCES, BABY_FEEDING, BABY_TRANSPORT, BEAUTY, BEDDING, CAMERAS, CELL_PHONES_AND_SMART_WATCHES, CLEANING_SUPPLIES, CLOTHING, CLOTHING_ACCESSORIES, COMPUTERS_AND_TABLETS, DIAPERING_AND_POTTY_TRAINING, ELECTRONICS_ACCESSORIES, FURNITURE, HEALTH, HOME_GOODS, JEWELRY, NURSERY, PRINTERS_AND_SCANNERS, PROJECTORS, SHOES_AND_FOOTWEAR, SOFTWARE, TOYS, TVS_AND_MONITORS, VIDEO_GAME_CONSOLES_AND_VIDEO_GAMES, WATCHES}	item_sub_type Required
`checkout_url` URL	URL to add product item to cart and directly to checkout
`color` string	Color of the product item
`commerce_tax_category` enum{FB_ANIMAL, FB_ANIMAL_SUPP, FB_APRL, FB_APRL_ACCESSORIES, FB_APRL_ATHL_UNIF, FB_APRL_CASES, FB_APRL_CLOTHING, FB_APRL_COSTUME, FB_APRL_CSTM, FB_APRL_HANDBAG, FB_APRL_JEWELRY, FB_APRL_SHOE, FB_APRL_SHOE_ACC, FB_APRL_SWIM, FB_APRL_SWIM_CHIL, FB_APRL_SWIM_CVR, FB_ARTS, FB_ARTS_HOBBY, FB_ARTS_PARTY, FB_ARTS_PARTY_GIFT_CARD, FB_ARTS_TICKET, FB_BABY, FB_BABY_BATH, FB_BABY_BLANKET, FB_BABY_DIAPER, FB_BABY_GIFT_SET, FB_BABY_HEALTH, FB_BABY_NURSING, FB_BABY_POTTY_TRN, FB_BABY_SAFE, FB_BABY_TOYS, FB_BABY_TRANSPORT, FB_BABY_TRANSPORT_ACC, FB_BAGS, FB_BAGS_BKPK, FB_BAGS_BOXES, FB_BAGS_BRFCS, FB_BAGS_CSMT_BAG, FB_BAGS_DFFL, FB_BAGS_DIPR, FB_BAGS_FNNY, FB_BAGS_GRMT, FB_BAGS_LUG_ACC, FB_BAGS_LUGG, FB_BAGS_MSGR, FB_BAGS_TOTE, FB_BAGS_TRN_CAS, FB_BLDG, FB_BLDG_ACC, FB_BLDG_CNSMB, FB_BLDG_FENCE, FB_BLDG_FUEL_TNK, FB_BLDG_HT_VNT, FB_BLDG_LOCK, FB_BLDG_MATRL, FB_BLDG_PLMB, FB_BLDG_PUMP, FB_BLDG_PWRS, FB_BLDG_S_ENG, FB_BLDG_STR_TANK, FB_BLDG_TL_ACC, FB_BLDG_TOOL, FB_BUSIND, FB_BUSIND_ADVERTISING, FB_BUSIND_AGRICULTURE, FB_BUSIND_AUTOMATION, FB_BUSIND_HEAVY_MACH, FB_BUSIND_LAB, FB_BUSIND_MEDICAL, FB_BUSIND_RETAIL, FB_BUSIND_SANITARY_CT, FB_BUSIND_SIGN, FB_BUSIND_STORAGE, FB_BUSIND_STORAGE_ACC, FB_BUSIND_WORK_GEAR, FB_CAMERA_ACC, FB_CAMERA_CAMERA, FB_CAMERA_OPTIC, FB_CAMERA_OPTICS, FB_CAMERA_PHOTO, FB_ELEC, FB_ELEC_ACC, FB_ELEC_ARCDADE, FB_ELEC_AUDIO, FB_ELEC_CIRCUIT, FB_ELEC_COMM, FB_ELEC_COMPUTER, FB_ELEC_GPS_ACC, FB_ELEC_GPS_NAV, FB_ELEC_GPS_TRK, FB_ELEC_MARINE, FB_ELEC_NETWORK, FB_ELEC_PART, FB_ELEC_PRINT, FB_ELEC_RADAR, FB_ELEC_SPEED_RDR, FB_ELEC_TOLL, FB_ELEC_VID_GM_ACC, FB_ELEC_VID_GM_CNSL, FB_ELEC_VIDEO, FB_FOOD, FB_FURN, FB_FURN_BABY, FB_FURN_BENCH, FB_FURN_CART, FB_FURN_CHAIR, FB_FURN_CHAIR_ACC, FB_FURN_DIVIDE, FB_FURN_DIVIDE_ACC, FB_FURN_ENT_CTR, FB_FURN_FUTN, FB_FURN_FUTN_PAD, FB_FURN_OFFICE, FB_FURN_OFFICE_ACC, FB_FURN_OTTO, FB_FURN_OUTDOOR, FB_FURN_OUTDOOR_ACC, FB_FURN_SETS, FB_FURN_SHELVE_ACC, FB_FURN_SHLF, FB_FURN_SOFA, FB_FURN_SOFA_ACC, FB_FURN_STORAGE, FB_FURN_TABL, FB_FURN_TABL_ACC, FB_GENERIC_TAXABLE, FB_HLTH, FB_HLTH_HLTH, FB_HLTH_JWL_CR, FB_HLTH_LILP_BLM, FB_HLTH_LTN_SPF, FB_HLTH_PRSL_CR, FB_HLTH_SKN_CR, FB_HMGN, FB_HMGN_BATH, FB_HMGN_DCOR, FB_HMGN_EMGY, FB_HMGN_FPLC, FB_HMGN_FPLC_ACC, FB_HMGN_GS_SFT, FB_HMGN_HS_ACC, FB_HMGN_HS_APP, FB_HMGN_HS_SPL, FB_HMGN_KTCN, FB_HMGN_LAWN, FB_HMGN_LGHT, FB_HMGN_LINN, FB_HMGN_LT_ACC, FB_HMGN_OTDR, FB_HMGN_POOL, FB_HMGN_SCTY, FB_HMGN_SMK_ACC, FB_HMGN_UMBR, FB_HMGN_UMBR_ACC, FB_MDIA, FB_MDIA_BOOK, FB_MDIA_DVDS, FB_MDIA_MAG, FB_MDIA_MANL, FB_MDIA_MUSC, FB_MDIA_PRJ_PLN, FB_MDIA_SHT_MUS, FB_OFFC, FB_OFFC_BKAC, FB_OFFC_CRTS, FB_OFFC_DSKP, FB_OFFC_EQIP, FB_OFFC_FLNG, FB_OFFC_GNRL, FB_OFFC_INSTM, FB_OFFC_LP_DSK, FB_OFFC_MATS, FB_OFFC_NM_PLT, FB_OFFC_PPR_HNDL, FB_OFFC_PRSNT_SPL, FB_OFFC_SEALR, FB_OFFC_SHIP_SPL, FB_RLGN, FB_RLGN_CMNY, FB_RLGN_ITEM, FB_RLGN_WEDD, FB_SFTWR, FB_SFWR_CMPTR, FB_SFWR_DGTL_GD, FB_SFWR_GAME, FB_SHIPPING, FB_SPOR, FB_SPORT_ATHL, FB_SPORT_ATHL_CLTH, FB_SPORT_ATHL_SHOE, FB_SPORT_ATHL_SPRT, FB_SPORT_EXRCS, FB_SPORT_INDR_GM, FB_SPORT_OTDR_GM, FB_TOYS, FB_TOYS_EQIP, FB_TOYS_GAME, FB_TOYS_PZZL, FB_TOYS_TMRS, FB_TOYS_TOYS, FB_VEHI, FB_VEHI_PART}	Commerce tax category
`condition` enum{new, refurbished, used, used_like_new, used_good, used_fair, cpo, open_box_new}	The condition of the product item
`currency` ISO 4217 Currency Code	Currency for the product item
`custom_data` dictionary { string : <string> }	Key value pair used to store extra data to differentiate variants. Example {"Scent" : "Fruity", "Style" : "Classic"}
`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)
`fb_product_category` string	Facebook product category for the item
`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
`launch_date` string	Launch Date of product in ISO 8061 format (YYYY-MM-DDTHH:MM:SS+HH:MM)
`manufacturer_part_number` string	Manufacturer's ID for the product item
`material` string	Material of the product item Max size: 200
`mobile_link` URI	Link to a mobile-optimized external product page
`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
`retailer_id` string	Retailer ID for a product item. (Internal only)
`return_policy_days` int64	Return policy days
`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` URI	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
10800	Duplicate retailer_id when attempting to create a store collection
10801	Either "file" or "url" must be specified

Deleting

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

Parameters

This endpoint doesn't have any parameters.

Return Type

Struct {

success: bool,

}

Validation Rules

Error	Description
100	Invalid parameter
200	Permissions error
801	Invalid operation