eBay Trading APIVersion 1005

ProductListingDetailsType

Type used by the ProductListingDetails container, which is used by a seller in an add/revise/relist call to identify a product through a Global Trade Item Number (EAN, ISBN, UPC, etc.) or EPID. If that product identifier is matched to a product in the eBay catalog, some of the details for the product listing, such as item title, listing description, item specifics, and stock photo are prefilled.

Note: The NameValueList container was added in Version 997, but it is not yet available for use in Sandbox or Production environments. Ultimately, specifying product identifiers through the NameValueList container will replace the process of specifying product identifiers through the BrandMPN container, or through the EAN, ISBN, or UPC fields. See the documentation for the NameValueList container for more information on how product identifiers are specified through this container. For more information on effective dates on this feature change and transition, see the Required Product Identifiers Mandate.

Type that uses ProductListingDetailsType:

Calls that use ProductListingDetailsType:

Fields



BrandMPN ( BrandMPNType ) [0..1]
The combination of Brand and MPN (manufacturer part number) can be used as a unique identifier for a product. If this container is used, both Brand and MPN must be specified.

It is a best practice to also specify the Brand/MPN values in two separate ItemSpecifics.NameValueList containers. The values in the BrandMPN container are used to look for an eBay catalog product match, but if a match is not found, these Brand and MPN values are dropped from the listing. By also specifying these Brand and MPN values in Item Specifics, these values are retained in the listing. If the Brand and MPN values in the BrandMPN container and ItemSpecifics.NameValueList containers differ, the values in the ItemSpecifics.NameValueList containers will overwrite the values of the BrandMPN container.

Note: The BrandMPN container (and eBay catalog product lookup) is not supported for multiple-variation listings. For multiple-variation listings that use MPNs, the Brand value should be specified through an ItemSpecifics.NameValueList container, and the Manufacturer Part Numbers (MPNs) for each product variation should be specified through a VariationSpecifics.NameValueList container.
Note: Currently, the BrandMPN container, and/or the EAN, ISBN, or UPC fields are used to specify a Global Trade Item Number (GTIN), and the GetCategoryFeatures call is used to see if particular product identifier types are supported/required. Starting later in 2017 ( dates will be announced as we approach second half of year), the NameValueList container can start being used to specify any and all GTINs, and the GetCategorySpecifics call will be the better option of retrieving the product identifier types that are supported/required. See the Required Product Identifiers Mandate (Current Phase) topic for more information on how product identifiers are currently used/specified in the Trading API, and see the Required Product Identifiers Mandate (Future Phase) topic for more information on how product identifiers will be used/specified in the Trading API beginning later in 2017. Note that the BrandMPN container, and the EAN, ISBN, and UPC fields will still be supported well into 2018.
See the Field Index to learn which calls use BrandMPN.

Copyright ( string ) [0..*]
Copyright statement indicating the source of the product information. This information will be included in the listing with Pre-filled Item Information. Your application should also display the copyright statement when rendering the Pre-filled Item Information. If more than one copyright statement is applicable, they can be presented to the user in alphabetical order. Returned as HTML. Output only.
See the Field Index to learn which calls use Copyright.

DetailsURL ( anyURI ) [0..1]
Not used by any call.

This field is deprecated.
See the Field Index to learn which calls use DetailsURL.

EAN ( string ) [0..1]
This field is used if the seller wishes to identify each product variation within a multi-variation listing by an EAN (European Article Number) value. An EAN is a unique 8 or 13-digit identifier that many industries (such as book publishers) use to identify products. Unlike single-variation listings where the EAN is specified in the ProductListingDetails container, eBay will attempt to match this EAN value to a product in the eBay catalog, but the product's item title, item description, item specifics, and stock photos are not automatically picked up for multiple-variation listings. If a secondary category is used, and the primary and secondary categories are both catalog-enabled, this EAN value should correspond to the primary category (not the secondary category).

Note: If the listing is being posted to a category that expects an EAN value, but one doesn't exist for the product, the seller must pass in the text that can be found in the ProductDetails.ProductIdentifierUnavailableText field of the GeteBayDetails response. To get the ProductDetails container to return in the GeteBayDetails response, 'ProductDetails' should be included as a DetailName value in the call request.
Note: Currently, the BrandMPN container, and/or the EAN, ISBN, or UPC fields are used to specify a Global Trade Item Number (GTIN), and the GetCategoryFeatures call is used to see if particular product identifier types are supported/required. Starting later in 2017 ( dates will be announced as we approach second half of year), the NameValueList container can start being used to specify any and all GTINs, and the GetCategorySpecifics call will be the better option of retrieving the product identifier types that are supported/required. See the Required Product Identifiers Mandate (Current Phase) topic for more information on how product identifiers are currently used/specified in the Trading API, and see the Required Product Identifiers Mandate (Future Phase) topic for more information on how product identifiers will be used/specified in the Trading API beginning later in 2017. Note that the BrandMPN container, and the EAN, ISBN, and UPC fields will still be supported well into 2018.
See the Field Index to learn which calls use EAN.

IncludeeBayProductDetails ( boolean ) [0..1]
This boolean field controls whether or not an eBay catalog product is used to help create or revise an item listing. If a product identifier value is provided through the ProductListingDetails container when adding, revising, or relisting an item, the default behavior is for eBay to try and find a match for the product in the eBay product catalog, and then automatically create the listing title, item specifics, item description, pictures (for "New" condition items), and assign a category.

If the seller wants to use the eBay product catalog to help create or revise the listing, the seller can include this field and set its value to true, or just omit this field, as it default value is true. If a seller doesn't want the eBay product catalog information in their listing, that seller would have to include this field and set its value to false. If the seller does this, they will also be required to pass in their own listing title and description, item specifics, and pictures, and select a listing category.

See the Field Index to learn which calls use IncludeeBayProductDetails.

IncludeStockPhotoURL ( boolean ) [0..1]
If true, indicates that the item listing includes the stock photo. To use an eBay stock photo in an item listing, set IncludeStockPhotoURL to true. If a stock photo is available, it is used at the top of the View Item page and in the Item Specifics section of the listing. If you also include Item.PictureDetails.PictureURL, the stock photo only appears in the Item Specifics section of the listing. Other pictures you specify by using Item.PictureDetails.PictureURL appear in a separate section of the listing. In GetItem, the URL of the stock photo will be returned in StockPhotoURL. If you set IncludeStockPhotoURL to false, the stock photo does not appear in the listing at all.

Note: The following sites offer free Gallery: US (site ID 0), the Parts & Accessories Category on US Motors (site ID 100), CA (site ID 2), CAFR (site ID 210), ES (site ID 186), FR (site ID 71), IT (site ID 101),and NL (site ID 146).

On these sites, eBay selects a Gallery thumbnail from image URLs included in the request, using selection rules that consider which of these URLs has been specified and whether an eBay stock photo exists for the item. A Gallery fee will only apply if you have set GalleryType to Plus or Featured (as basic Gallery is free).

Along with these changes, IncludeStockPhotoURL will be used in the request. In some cases, if IncludeStockPhotoURL is set to false, no image will be generated for the Gallery. A common example of this occurrence is when no PictureURL elements are defined in request. In this case, eBay will not use a stock photo, even if it is available.

Not applicable to Half.com.
See the Field Index to learn which calls use IncludeStockPhotoURL.

ISBN ( string ) [0..1]
This field is used if the seller wishes to identify each product variation within a multi-variation listing by an ISBN (International Standard Book Number) value. An ISBN is a unique identifer for books. Both 10 and 13-character ISBNs are supported. When specifying a 13-character ISBN, the value must begin with either '978' or '979'. Unlike single-variation listings where the ISBN is specified in the ProductListingDetails container, eBay will attempt to match this ISBN value to a product in the eBay catalog, but the product's item title, item description, item specifics, and stock photos are not automatically picked up for multiple-variation listings. If a secondary category is used, and the primary and secondary categories are both catalog-enabled, this ISBN value should correspond to the primary category (not the secondary category).

Note: If the listing is being posted to a category that expects an ISBN value, but one doesn't exist for the product, the seller must pass in the text that can be found in the ProductDetails.ProductIdentifierUnavailableText field of the GeteBayDetails response. To get the ProductDetails container to return in the GeteBayDetails response, ProductDetails should be included as a DetailName value in the call request.
Note: Currently, the BrandMPN container, and/or the EAN, ISBN, or UPC fields are used to specify a Global Trade Item Number (GTIN), and the GetCategoryFeatures call is used to see if particular product identifier types are supported/required. Starting later in 2017 ( dates will be announced as we approach second half of year), the NameValueList container can start being used to specify any and all GTINs, and the GetCategorySpecifics call will be the better option of retrieving the product identifier types that are supported/required. See the Required Product Identifiers Mandate (Current Phase) topic for more information on how product identifiers are currently used/specified in the Trading API, and see the Required Product Identifiers Mandate (Future Phase) topic for more information on how product identifiers will be used/specified in the Trading API beginning later in 2017. Note that the BrandMPN container, and the EAN, ISBN, and UPC fields will still be supported well into 2018.
See the Field Index to learn which calls use ISBN.

NameValueList ( NameValueListType ) [0..*]
Note: The NameValueList container was added in Version 997, but it is not yet available for use in Sandbox or Production environments. Currently, the BrandMPN container, and/or the EAN, ISBN, or UPC fields are used to specify a Global Trade Item Number (GTIN), and the GetCategoryFeatures call is used to see if particular product identifier types are supported/required. Starting later in 2017 ( dates will be announced as we approach second half of year), the NameValueList container can start being used to specify any and all GTINs, and the GetCategorySpecifics call will be the better option of retrieving the product identifier types that are supported/required. See the Required Product Identifiers Mandate (Current Phase) topic for more information on how product identifiers are currently used/specified in the Trading API, and see the Required Product Identifiers Mandate (Future Phase) topic for more information on how product identifiers will be used/specified in the Trading API beginning later in 2017. Note that the BrandMPN container, and the EAN, ISBN, and UPC fields will still be supported well into 2018. This container is used to pass in a name-value pair that will identify the type of product identifier being used and its value. This product identifier, such as EAN, ISBN, or UPC, is then used by eBay to try and match the identifier to a product in the eBay catalog. If a Brand/MPN pair is going to be used to identify a product, the brand is specified in one NameValueList container, and its Manufacturer Part Number (MPN) is specified in another NameValueList container. Also, if a product has more than one product identifier, each can be specified through separate NameValueList containers.

The GetCategorySpecifics call can be used to see the product identifier type(s) that are required/supported for a particular eBay category. Each required/supported product identifier type will be shown in a separate ProductIdentifiers.NameRecommendation container in the GetCategorySpecifics call response. The product identifier type name will be shown in the NameRecommendation.Name field. By looking at the value in the corresponding ProductIdentifiers.ValidationRules.MinRequired field, the seller will know if one or more product identifiers are required at listing time. If two product identifier types are returned, and the MinRequired value is '2', the seller will be required to use both product identifier types at listing time. If the MinRequired value is '1', only one of the two product identifier types would be required, but the seller could use them both if they wanted. If the MinRequired value is 0, one or both of those product identifier types could be used, but they would not be required.

It is a best practice to also specify the Brand/MPN values in two separate ItemSpecifics.NameValueList containers. The values in the BrandMPN container are used to look for an eBay catalog product match, but if a match is not found, these Brand and MPN values are dropped from the listing. By also specifying these Brand and MPN values in Item Specifics, these values are retained in the listing. If the Brand and MPN values in the BrandMPN container and ItemSpecifics.NameValueList containers differ, the values in the ItemSpecifics.NameValueList containers will overwrite the values of the BrandMPN container.
See the Field Index to learn which calls use NameValueList.

ProductDetailsURL ( anyURI ) [0..1]
Not used by any call.

This field is deprecated.
See the Field Index to learn which calls use ProductDetailsURL.

ProductReferenceID ( string ) [0..1]
eBay's short global reference ID for a catalog product. On the eBay Web site, this is known as the "ePID" or "Product ID". This type of product ID is a fixed reference to a product (regardless of version). Multiple (versioned) ProductID values can be associated with a single product reference ID. You can find product reference IDs for products by using FindProducts in the Shopping API. You can also find the product ID on eBay's Web site (a numeric value prefixed with "EPID"). You can pass the value with or without the "EPID" prefix; for example "EPID228742" or "228742" (without quotes).

If the primary and secondary categories are both catalog-enabled, this ID should correspond to the primary category (not the secondary category).

Some sites (such as eBay US, Germany, Austria, and Switzerland) are updating, replacing, deleting, or merging some products (as a result of migrating from one catalog data provider to another). If you specify one of these products in a request, the call may return the product with a warning, or it may return an error if the product has been deleted.
See the Field Index to learn which calls use ProductReferenceID.

ReturnSearchResultOnDuplicates ( boolean ) [0..1]
Applicable for listing use cases only (not buy-side searching). Indicates what eBay should do if more than one product matches the external product ID (ISBN, UPC, EAN, Brand-MPN combination) or event specified through TicketListingDetails . Also see UseFirstProduct as an alternative.

If true and more than one match is found, the call fails and the response returns an error and all matching Product ID values. This lets you choose one of the Product IDs to pass in instead. If false and more than one match is found, the call fails and the response includes an error but does not return the matching Product ID values. (This flag has no effect when only one match is found.)
See the Field Index to learn which calls use ReturnSearchResultOnDuplicates.

StockPhotoURL ( anyURI ) [0..1]
Fully qualified URL for a standard image (if any) that is associated with the product. A seller includes the stock photo in the listing by setting IncludeStockPhotoURL.
See the Field Index to learn which calls use StockPhotoURL.

TicketListingDetails ( TicketListingDetailsType ) [0..1]
Applicable for listing use cases only (not buy-side searching). Only applicable when you are listing event tickets. Please note that the US eBay site and other sites may also require you to specify additional Item Specifics by using AttributeSetArray. This may depend on the location of the event. See the eBay Features Guide for more information about how to specify and troubleshoot these values.
See the Field Index to learn which calls use TicketListingDetails.

UPC ( string ) [0..1]
This field is used if the seller wishes to identify each product variation within a multi-variation listing by a UPC (Universal Product Code) value. A UPC is a commonly used identifer for many different products. Unlike single-variation listings where the UPC is specified in the ProductListingDetails container, eBay will attempt to match this UPC value to a product in the eBay catalog, but the product's item title, item description, item specifics, and stock photos are not automatically picked up for multiple-variation listings. If a secondary category is used, and the primary and secondary categories are both catalog-enabled, this UPC value should correspond to the primary category (not the secondary category).

Note: If the listing is being posted to a category that expects a UPC value, but one doesn't exist for the product, the seller must pass in the text that can be found in the ProductDetails.ProductIdentifierUnavailableText field of the GeteBayDetails response. To get the ProductDetails container to return in the GeteBayDetails response, 'ProductDetails' should be included as a DetailName value in the call request.
Note: Currently, the BrandMPN container, and/or the EAN, ISBN, or UPC fields are used to specify a Global Trade Item Number (GTIN), and the GetCategoryFeatures call is used to see if particular product identifier types are supported/required. Starting later in 2017 ( dates will be announced as we approach second half of year), the NameValueList container can start being used to specify any and all GTINs, and the GetCategorySpecifics call will be the better option of retrieving the product identifier types that are supported/required. See the Required Product Identifiers Mandate (Current Phase) topic for more information on how product identifiers are currently used/specified in the Trading API, and see the Required Product Identifiers Mandate (Future Phase) topic for more information on how product identifiers will be used/specified in the Trading API beginning later in 2017. Note that the BrandMPN container, and the EAN, ISBN, and UPC fields will still be supported well into 2018.
See the Field Index to learn which calls use UPC.

UseFirstProduct ( boolean ) [0..1]
Applicable for listing use cases only (not buy-side searching). Indicates what eBay should do if more than one product matches the external product ID (ISBN, UPC, EAN, BrandMPN, or TicketListingDetails). Also see ReturnSearchResultOnDuplicates as an alternative. If more than one product match was found and UseFirstProduct is true, item will be listed with first product information. If false, the rules for ReturnSearchResultOnDuplicates are used.
See the Field Index to learn which calls use UseFirstProduct.

UseStockPhotoURLAsGallery ( boolean ) [0..1]
If true, indicates that the stock photo for an item (if available) is used as the gallery thumbnail. When listing an item, IncludeStockPhotoURL must also be true and Item.PictureDetails.GalleryType must be passed in with a value of Gallery or Gallery Featured (but not both).

Note: The following sites offer free Gallery: US (site ID 0), the Parts & Accessories Category on US Motors (site ID 100), CA (site ID 2), CAFR (site ID 210), ES (site ID 186), FR (site ID 71), IT (site ID 101),and NL (site ID 146).

On these sites, eBay selects a Gallery thumbnail from image URLs included in the request, using selection rules that consider which of these URLs has been specified and whether an eBay stock photo exists for the item. A Gallery fee will only apply if you have set GalleryType to Plus or Featured (as basic Gallery is free).

Along with these changes, UseStockPhotoURLAsGallery will be used in the request. In some cases, if UseStockPhotoURLAsGallery is set to false, no image will be generated for the Gallery. A common example of this occurrence is when no PictureURL elements are defined in request. In this case, eBay will not use a stock photo, even if it is available.

See the Field Index to learn which calls use UseStockPhotoURLAsGallery.