Skip to main content

Note: Due to the rollback of the Product-Based Shopping Experience mandate for all eBay categories (and brands within those categories), sellers will no longer be required to associate an eBay catalog product to the listing in any categories. Although the mandate has been rolled back, it can still be very useful to sellers (and buyers searching for their items) if a listing is associated with an eBay catalog product, if one is available for their product. Sellers can use the search operation in the Catalog API or the FindProducts call in the Shopping API to search for matching eBay catalog products.

This page provides details on the recommended workflows to use if you prefer to use the Trading API to make new and existing listings compliant with Product-Based Shopping Experience. If you prefer to use the Inventory API to make new and existing listings compliant with Product-Based Shopping Experience, see the Phase 1 recommended workflows using Inventory API topic.

Note: If you created an active listing using the Inventory API, you must use the Inventory API to revise that listing.

Table of Contents

Discovering non-compliant listings and revising with catalog product

Note: The procedures covered in this section assume that a non-compliant listing is in the Trading API model. If you created an active listing using the Inventory API, you must use the Inventory API to revise the listing with the product details defined in the eBay Catalog product. Once a listing is in the Inventory API model, the Revise/Relist/Verify item calls of Trading API cannot be used.

The following flow diagram provides an overview of the steps required to find and revise existing listings that require a revision with an eBay Catalog product.

Phase 1 Revising Listings

Figure 1: Phase 1 Workflow for revising non-compliant listings with catalog product

Finding a matching product for non-compliant listings

Note: If you created the active listing using the Inventory API, you must use the Inventory API to revise the listing with the product details defined in the eBay Catalog product. Once a listing is in the Inventory API model, the Revise/Relist/Verify item calls of Trading API cannot be used.

Below are the detailed steps of discovering non-compliant listings and then finding a matching catalog product for that listing.

  1. Use the getListingViolations operation in the Compliance API to get a list of non-compliant listings. See the getListingViolations call reference documentation for more details on using this operation, but please note that the call URI for this operation will require the compliance_type query parameter, with its value set to PRODUCT_ADOPTION.

    https://api.ebay.com/sell/compliance/v1/listing_violation?compliance_type=PRODUCT_ADOPTION

    The response payload will include all non-compliant listings with detailed information on each listing violation. Some key response fields are shown in the sample below. The listingId value, sku value (if defined), and offerId value (if listing is in the Inventory model) are shown for each non-compliant listing, and the reasonCode value is shown for each violation. The following code sample shows one violation for a single-variation listing, and one violation for a specific variation in a multiple-variation listing.

    {
        "complianceType": "PRODUCT_ADOPTION",
        "listingId": "200008552422",
        “sku”: “1234567”,
        “offerId”: “36445435465”,
        "violations": [
            {
             "reasonCode": "EPID_MISSING",
             "message": "EPID missing for listing with specific
     category and brand. Provide EPID value."
            }
        ]
     },
     {
        "complianceType": "PRODUCT_ADOPTION",
        "listingId": "200008552424",
        "violations": [
            {
              "reasonCode": "SAME_GTIN_ACROSS_VARIANTS",
              "message": "Please enter unique UPC for each of the
     listing variations.",
              "variation": {
                 "variationAspects": [
                  {
                    "name": "Size Type",
                    "value": "Regular"
                  },
                  {
                    "name": "Size (Men's)",
                    "value": "M"
                  },
                  {
                    "name": "Color",
                    "value": "Blue"
                  },
                  {
                    "name": "UPC",
                    "value": "640520099063"
                  }
                ],
                "sku": "AXT10034_R_M_B_1asd6"
             }
          }
       ...
    }

    Each reasonCode value for the PRODUCT_ADOPTION compliance type will require that the seller update the existing listing with an ePID or product identifier. If you want more detail on the most common reasonCode values that are returned, and the subsequent actions to take to make the listings compliant, see the Using Compliance API reason codes to revise listings section in this document.

    If the seller does not have any existing listings that are in violation of the PRODUCT_ADOPTION compliance type, the total field will be returned with a value of 0.

    Note: The getListingViolations call of the Compliance API returns recommended catalog products (if available) for the listings that are non-compliant with the PRODUCT_ADOPTION compliance type. Any recommended catalog product that is returned has the corresponding ePID value, so this makes it much easier for sellers to get these listings revised and associated with a catalog product. Instead of using the search operation of the Catalog API, they will be able to use the getProduct operation of the Catalog API to see if eBay’s recommended product is indeed the correct product. If the correct product is found, the seller will be able to grab the ePID for the product and then proceed to Step 4. Note that the getListingViolations call only returns a canned response (not the seller's real data) in Sandbox.

  2. Use the GetItem call of the Trading API to see detailed product information on the listing (or variation), as this information may help you when you do a search for a catalog product in Step 3. In a GetItem call, you’ll need the unique identifier of the listing (Item ID). For a multiple-variation listing, the product information for each variation can be found under the Variations.Variation container in the response.

  3. Use the search operation in the Catalog API to search the eBay Catalog for your product. The operation supports search by GTIN and search by keywords. There are also other search refinements available. If you are already integrated with the FindProducts call of the Shopping API, you can still use that call, but this call only allows a keyword search. Below are examples of a GTIN (UPC) search and a query search. Full call samples and an explanation of each supported query parameter can be viewed in the Catalog API Call Reference documentation.

    Search by GTIN (UPC)

    GET

    https://sandbox.api.ebay.com/commerce/catalog/v1_beta/product_summary/search?gtin%3D0813917020203

    Query Search

    GET

    https://sandbox.api.ebay.com/commerce/catalog/v1_beta/product_summary/search?q%3DNest%2520Thermostat

    All Phase 1 products should be in the eBay Catalog, so if you don’t find a matching product, either revise your search query and try again, or call customer service,

  4. As soon as your product is found, capture the eBay Product ID (ePID), follow one of the processes below to use the Trading API to revise your single or multiple-variation listing.

Revising a single-variation listing with a catalog product using the Trading API

To revise a single-variation listing with a catalog product using the Trading API, follow the procedure below. This procedure assumes that the listing is in the Trading API listing model.

  1. Before updating an active listing using the Trading API, it is a good idea to use the GetItem call to retrieve the listing details just in case the seller wants to update other details of the listing beside the catalog product details. The Item ID value is needed when making a GetItem call.

  2. Use the ReviseItem or ReviseFixedPriceItem call to revise the single-variation listing with the product details of the catalog product. The following fields are required:

    Assuming that you do not want to make any other changes to the listing, the ProductListingDetails.ProductReferenceID field may be only new data that you will be adding to the listing. However, if the product is used or modified, you will still want to pass in the URLs to each of your item's images through a separate PicturesDetails.PictureURL field. A successful ReviseItem or ReviseFixedPriceItem call will automatically update the active listing with the catalog product data. See the ReviseItem or ReviseFixedPriceItem call reference documentation for more detailed information on using these calls.

Revising a multiple-variation listing with a catalog product using the Trading API

To revise a multiple-variation listing with a catalog product using the Trading API, follow the procedure below. This procedure assumes that the listing is in the Trading API listing model.

  1. Before updating an active listing using the Trading API, it is a good idea to use the GetItem call to retrieve the listing details just in case the seller wants to update other details of the listing beside the catalog product details. The Item ID value is needed when making a GetItem call. The product information for each variation can be found under the Variations.Variation container in the response.

  2. Use the ReviseFixedPriceItem call to revise the multiple-variation listing with the product details of the catalog product. The following fields are required:

    A successful ReviseFixedPriceItem call will update the active listing with the product data that is passed in for each variation. See the ReviseFixedPriceItem call reference documentation for more detailed information on using this call.

    Note: Please note that in Phase 2, the seller will be required to pass in an ePID value for each variation instead of a GTIN value.

Creating new listings with catalog product

The following flow diagram provides an overview of the steps required to find a matching eBay Catalog product, and then create a new product-based listing.

Phase 1 New Listings

Figure 2: Phase 1 Workflow for creating new product-based listings

Finding a matching product for new listings

Below are the detailed steps of finding a matching eBay Catalog product before creating a new listing based on that catalog product.

  1. Use the search operation in the Catalog API to search the eBay Catalog for your product. The operation supports search by GTIN and search by keywords. There are also other search refinements available. If you are already integrated with the FindProducts call of the Shopping API, you can still use that call, but this call only allows a keyword search. Below are examples of a GTIN (UPC) search and a query search. Full call samples and an explanation of each supported query parameter can be viewed in the Catalog API Call Reference documentation.

    Search by GTIN (UPC)

    GET
    https://sandbox.api.ebay.com/commerce/ catalog/v1_beta/product_summary/search?gtin%3D0813917020203

    Query Search

    GET
    https://sandbox.api.ebay.com/commerce/catalog/v1_beta/product_summary/search?q%3DNest%2520Thermostat

    If your product is found, capture the eBay Product ID (ePID), and then go to Step 4. If your product is not found, go to Step 2.

    Note: If multiple products are returned with the search operation, and you are unable to decide which is the correct product based on the data that is returned, you can use the productWebUrl field in the response to view the product details on the eBay site. You can also use the getProduct operation of the Catalog API to return full details on a catalog product. With the getProduct operation, you pass in the ePID value at the end of the call URI.

  2. If you don't know the eBay category ID for your item, call GetSuggestedCategories in the Trading API to find the appropriate category for your listing. Be sure to capture the SuggestedCategory.Category.CategoryID value in the response, as this value will be needed in the next step in the workflow. In the GetSuggestedCategories call, the supported eBay categories are returned in the response and they are sorted by relevance (most to least relevant). Once you have the SuggestedCategory.Category.CategoryID value, you can continue to Step 3.

  3. Call GetCategorySpecifics in the Trading API to see if your listing category and brand require a catalog product. In the output, first you want to locate brand in one of the NameRecommendation.Name fields. Once you find the brand node, you want to locate your brand in one of the corresponding NameRecommendation.ValueRecommendation containers. If the category/brand combination requires a catalog product when listing, the NameRecommendation.ValidationRules container should have a ValidationRules.ProductRequired field, and its value should be Enabled.

    If your brand does require association with a catalog product, return to Step 1 and refine your product search to find the matching product in the eBay Catalog. All Phase 1 products should be in the eBay Catalog, so if you don’t find a matching product, either revise your search query and try again, or call customer service.

    If your category/brand does not require association with a catalog product, you can create your listing with seller-defined aspects via the Trading API or Inventory API, as described in the documentation for those APIs.

  4. As soon as your product is found, capture the eBay Product ID (ePID), and then follow one of the processes below to create your product-based listing using the Trading API.

 

Creating a single-variation listing with a catalog product using the Trading API

To create a new single-variation listing based on an eBay Catalog product using the Trading API, you will use the AddItem or AddFixedPriceItem call to create your listing. In either of the 'Add' calls, you will need to do the following:

  • Use the ProductListingDetails.ProductReferenceID field to pass in the ePID value for the eBay Catalog product. The ePID value is found in the response of the Catalog API's search call or the FindProducts call of the Shopping API.

  • Supply all other required data for the listing, including the listing country, the primary currency used in that country, listing duration, listing type, payment methods, shipping services, return policy, etc. See the AddItem call reference documentation for more information on creating listings using the Trading API.

A successful 'Add' call will use the supplied ePID value to associate the listing with the appropriate eBay Catalog product and list the product into the proper category.

Note: Please note that the ProductListingDetails container in the Add/Revise/Relist calls of the Trading API have a boolean field called IncludeeBayProductDetails, which is set to 'true' by default. If this field is included in an Add/Revise/Relist call but set to 'false' for a category and brand that requires a catalog product, the create/revise/relist action will be blocked, even if the appropriate ePID for a matching catalog product was included. If the seller passes in an appropriate GTIN or ePID for a product that is not part of the Product-Based mandate, and has the IncludeeBayProductDetails flag set to 'false', eBay will attempt to create the listing based on any seller-provided (non-catalog) details. eBay recommends leaving the IncludeeBayProductDetails value set to 'true' in all cases.

Note: For used or modified products, and for seller-created bundles, the seller must add pictures of the actual item/bundle and they should also create a customized listing description to give prospective buyers a better idea of the product/bundle that they are purchasing. For a used product, sellers should use the “condition description” field to highlight any flaws or wear-and-tear of the used item. For modified products, sellers can provide item specifics unique to the item, but the seller will not be able to override any product specifics already defined in the catalog product. For a seller-created bundle, the seller will actually pass in ‘Bundle Listing’ as an boolean item specific. ‘Bundle Listing’ is passed in as the item specific name, and ‘Yes’ is passed in as the corresponding item specific value. See the Associating catalog products to special listings topic for more information on associating catalog products with bundle, lot, and modified product listings.

Creating a multiple-variation listing with a catalog product using the Trading API

To create a new multiple-variation listing based on an eBay Catalog product using the Trading API, you will use the AddFixedPriceItem call to create your listing. This call will require the following information:

  • Instead of passing in an ePID value in the ProductListingDetails.ProductReferenceID field for a single-variation listing, the seller will be using the Variations.Variation.VariationProductListingDetails container to pass in a GTIN value for each product variation that will be included in the listing. For more information on providing product details for each variation in an AddFixedPriceItem call, see the documentation for the Variations.Variation container. The corresponding GTIN values for a product can be found in the response of the Catalog API's search call or the FindProducts call of the Shopping API.

  • Supply all other required data for the listing, including the listing country, the primary currency used in that country, listing duration, listing type, payment methods, shipping services, return policy, etc. See the AddFixedPriceItem call reference documentation for more information on creating listings using the Trading API.

A successful AddFixedPriceItem call will create the new multiple-variation listing with the product data that is passed in for each variation.

Note: Please note that in Phase 2, the seller will be required to pass in an ePID value for each variation instead of a GTIN value.