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 2 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 2 Revising Listings

Figure 1: Phase 2 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: Around mid-June 2018, the getListingViolations call of the Compliance API will start returning recommended catalog products for the listings that are non-compliant with the PRODUCT_ADOPTION compliance type, including the ePID. This enhancement will make it much easier for sellers to get these listings revised 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. Although the getListingViolations call returns a canned response (not the seller's real data) in Sandbox, the new productRecommendation has already been added to the canned response when making this call 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

    As soon as your product is found, capture the eBay Product ID (ePID), and proceed to Step 5.

    If your category requires association with a catalog product, but you are either unable to locate the correct product in the eBay Catalog, your first step might be to refine you search and try again. If you still can’t locate the correct product in the eBay Catalog, or if you see a matching product that appears to have either missing or inaccurate product information, you may have to make a catalog change request to eBay. Proceed to Step 4.

    Note: The three Catalog change request method were decommissioned in Q1 2020.

  4. Based on whether you need to request that eBay create a new product in the eBay Catalog, or to revise an existing catalog product with missing or inaccurate product information, you will either use the getProductMetadataForCategories or the getProductMetadata operation of the Catalog API to get product-level aspects for the eBay category ID that is passed in as a query parameter. Then, you will use the createChangeRequest call of the Catalog API to make a request to eBay to create a new product or revise an existing product in the catalog.

    Note: The three Catalog change request method were decommissioned in Q1 2020.

    Note: The getProductMetadataForCategories and the getProductMetadata operations of the Catalog API will become available for testing in Sandbox in late May 2018. These operations will become available in Production in mid-August 2018.
  5. Once you have the eBay Product ID (ePID) for the catalog product, 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: The ProductReferenceID field of the Variations.Variation.VariationProductListingDetails container is not yet available, but will become available as we get closer to the Phase 2 launch. Once the ProductReferenceID field becomes available, 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 2 New Listings

Figure 2: Phase 2 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 and all of the product information appears to be correct, capture the eBay Product ID (ePID), and then go to Step 5. If your product is found but one or more product details appears to be incorrect, 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 GetCategoryFeatures of the Trading API to get various category metadata information and to check if the category requires catalog product adoption by looking for the ProductRequiredEnabled field. If this field is returned, the entire category requires a catalog product when listing.

    If your category requires association with a catalog product, but you are either unable to locate the correct product in the eBay Catalog, your first step might be to refine you search and try again using Step 1. If you still can’t locate the correct product in the eBay Catalog, or if you see a matching product that appears to have either missing or inaccurate product information, you may have to make a catalog change request to eBay. Proceed to Step 4.

    Note: The three Catalog change request method were decommissioned in Q1 2020.

    If your category 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. Based on whether you need to request that eBay create a new product in the eBay Catalog, or to revise an existing catalog product with missing or inaccurate product information, you will either use the getProductMetadataForCategories or the getProductMetadata operation of the Catalog API to get product-level aspects for the eBay category ID that is passed in as a query parameter. Then, you will use the createChangeRequest call of the Catalog API to make a request to eBay to create a new product or revise an existing product in the catalog.

    Note: The three Catalog change request method were decommissioned in Q1 2020.

    Note: The getProductMetadataForCategories and the getProductMetadata operations of the Catalog API will become available for testing in Sandbox in late May 2018. These operations will become available in Production in mid-August 2018.

  5. 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 to give prospective buyers a better idea of the product/bundle that they are purchasing. For a used product, sellers should use the ConditionDescription field to highlight any flaws or wear-and-tear of the used item. For Phase 2, new item specifics will be added to help sellers describe seller-created bundles, modified products, and foreign products. For more information on creating seller-created bundles, modified products, and foreign products in the correct way for Phase 2, see the Associating catalog products to special listings topic. In Phase 2, sellers can provide item specifics unique to the item, but the seller will not be able to override any product aspects already defined in the catalog product. See the Product aspects vs. item specifics topic

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 ProductReferenceID field of the Variations.Variation.VariationProductListingDetails container to pass in an ePID value for each product variation that needs to be updated 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 ePID value 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. To support this change a new ProductReferenceID field will be added to the Variations.Variation.VariationProductListingDetails container.