Phase 1 recommended workflows using REST APIs

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

Table of Contents

• Discovering non-compliant listings and revising with catalog product
  • Finding a matching product for non-compliant listings
  • Revising a listing with a catalog product using the Inventory API
• Creating new listings with catalog product
  • Finding a matching product for new listings
  • Creating listings with a catalog product using the Inventory API

Discovering non-compliant listings and revising with catalog product

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.

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

Finding a matching product for non-compliant listings

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: As of mid-June 2018, the getListingViolations call of the Compliance API returns recommended catalog products for the listings that are non-compliant with the PRODUCT_ADOPTION compliance type, including the ePID. This enhancement makes 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 can 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 can 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 getInventoryItem operation of the Inventory 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 getInventoryItem operation, you’ll need the SKU value that is associated with the listing (or variation).

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. 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://api.ebay.com/commerce/catalog/v1_beta/product_summary/search?gtin%3D0813917020203

   Query Search

   GET

   https://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), and then follow the process below to use the Inventory API to revise your single or multiple-variation listing.

Revising a listing with a catalog product using the Inventory API

To revise a listing with a catalog product using the Inventory API, follow the procedure below. This procedure assumes that the seller is already integrated with the Inventory API and that the listing is already in the Inventory API listing model.

1. Before updating an active listing using the Inventory API, use the getInventoryItem operation to retrieve the corresponding Inventory Item record. The createOrReplaceInventoryItem operation does a complete replace of the Inventory Item record, so the seller will want to make sure that they see all details of the Inventory Item record and reuse some of these details as needed. The SKU value for the Inventory Item record to retrieve is passed in at the end of the call URI as shown below:

   GET https://api.ebay.com/sell/inventory/v1/inventory_item/{sku}

2. Use the createOrReplaceInventoryItem operation to revise the listing (or a single-variation within a multiple-variation listing) with the product details of the catalog product. The SKU value for the Inventory Item record to revise is passed in at the end of the call URI as shown below:

   PUT https://api.ebay.com/sell/inventory/v1/inventory_item/{sku}

   Assuming that you do not want to make any other changes to the Inventory Item record, the only new data that you will be adding to the Inventory Item record is the product.epid value. If the product is new, the epid field may be the only field that you need to specify under the product container of the createOrReplaceInventoryItem operation. However, if the product is used or modified, you will still want to pass in the URLs to your item's images through the product.imageUrls array. A successful createOrReplaceInventoryItem operation will automatically update the active listing with the catalog product data.

   Remember to repeat the process for each variation within a multiple-variation listing that requires association with a catalog product.

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.

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. 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://api.ebay.com/commerce/ catalog/v1_beta/product_summary/search?gtin%3D0813917020203

   Query Search

   GET
https://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 getCategorySuggestions in the Taxonomy API to find the appropriate category for your listing. Be sure to capture the categoryID value in the response, as this value will be needed in the next step in the workflow. In the getCategorySuggestions operation, the supported eBay categories are returned in the response and they are sorted by relevance (most to least relevant). Once you have the categoryID, you can continue to Step 3.

3. Call getProductAdoptionPolicies of the Metadata API to see if your listing category and brand require a catalog product. In the resource URI, you will pass in the eBay Category ID in the filter query parameter. See the Call Reference documentation for the proper syntax to use.

   In the response payload, the productRequired boolean is returned as true if listings within the eBay category require association with an eBay Catalog product. The productRequired boolean is not returned at all if 'false'. If any product brands within the eBay category are excluded from the PBSE requirement, those brand names will be returned in the exclusion.brands array. The exclusion container will not be returned at all if there are no brand exclusions.

   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 the process below to create your product-based listing using the Inventory API.

Creating listings with a catalog product using the Inventory API

The steps required to create a product-based eBay listing using the Inventory API will depend on whether or not a seller/developer is new to the Inventory API. For a seller/developer who is already using the Inventory API and who has inventory locations and inventory already loaded into the Inventory API model, less steps are required. The following flow diagram actually covers all use cases for creating or revising listings with the Inventory API using a catalog product for all users (new to the Inventory API or partially/fully integrated with the API).

Figure 3: Phase 1 creating listings with a catalog product using Inventory API

The following procedure to create a listing based on a catalog product assumes that the seller is already integrated with the Inventory API, and has already set up the desired Inventory Location, and the Inventory Item record for the product:

1. Call getInventoryItem to retrieve all of the existing details for the Inventory Item record. When you use the createOrReplaceInventoryItem operation to revise an existing Inventory Item (published or unpublished), the operation does a complete replacement of the record, so all defined data that you want to retain is required. Capture the data in the response of this call, as it can be reused in the createOrReplaceInventoryItem operation.

2. Use the createOrReplaceInventoryItem operation to revise the Inventory Item record with the product details of the eBay Catalog product. To specify which Inventory Item record to modify, you pass in the seller-defined SKU value for the product in the call URI.

   Assuming that you do not want to make any other changes to the Inventory Item record, the only new data that you will be adding to the Inventory Item record is the product.epid value. If the product is new, the epid field may be the only field that you need to specify under the product container of the createOrReplaceInventoryItem operation. However, if the product is used or modified, you will still want to pass in the URLs to your item's images through the product.imageUrls array. A successful createOrReplaceInventoryItem operation will update the Inventory Item record with the catalog product data.

3. Create the offer for the product using the createOffer operation. You can read more about the required and conditional fields for this call in the createOffer call reference documentation. A successful createOffer operation will produce an offerId value in the response, and this value will be needed for the next step

4. Publish the offer and create the new listing by using the publishOffer operation. The offerId value that is returned in the response of the createOffer operation is passed in as part of the call URI. The call will look something like this:

   https://api.ebay.com/sell/inventory/v1/offer/36445435465/publish, where '36445435465' is the actual offerId value of the offer to publish.

5. A successful publishOffer operation will produce a listingId value in the response, and this value is the unique identifier of the new listing.

If the seller is not integrated with the Inventory API, the first logical step would be to create the Inventory Location (where the product will be shipped from). An Inventory Location is set up using the createInventoryLocation operation. Note that the Inventory Location should be a physical address from where the seller will actually ship the product (like a warehouse or store). The next step would be to create the Inventory Item record for the product using the createOrReplaceInventoryItem operation. Once the Inventory Location and Inventory Item objects are created by the seller, the seller would go onto to create and publish the offer. Steps 3-5 in the procedure above discuss the requirements to do this.

Creating a multiple-variation listing with the Inventory API is very similar to creating a single-variation listing with the Inventory API, with the following exceptions:

• You have to use a separate createOrReplaceInventoryItem operation (or one bulkCreateOrReplaceInventoryItem operation) to create an Inventory Item object for each product variation.

• A createOrReplacementInventoryItemGroup operation must be used to link all inventory items together. In this operation, the SKUs that define each inventory item in the group are declared, and the seller sets the aspects where each product variation differs (such as size and color), and the options available for these aspects. See the createOrReplacementInventoryItemGroup call reference documentation for more information.

• You have to use a separate createOffer operation (or one bulkCreateOffer operation) to create an offer for each product variation. For each of the createOffer operations (or one bulkCreateOffer operation), the eBay listing category, eBay listing site, Inventory Location, and referenced business policies must be the same, but the SKU value must be unique for all inventory items, and the available quantity and price can also vary for each inventory item.

• Instead of using a publishOffer operation to create the listing, the publishOfferByInventoryItemGroup operation is used to publish the multiple-variation listing.