Phase 1 recommended workflows using REST APIs

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 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.

Note: If you created an active listing using the Inventory API, you must use the Inventory API to revise that listing. Conversely, in order for the Inventory API to be used to revise an existing listing that was creating using the Trading API listing model, the seller must first use the bulkMigrateListing operation in the Inventory API to convert that listing to the Inventory listing model. Be sure to read the bulkMigrateListing call reference documentation because the listing requirements for an Inventory API listing are slightly different than the listing requirements for a Trading API 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 Inventory API model. 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. If your listing is currently in the Trading API listing model but you want to convert the listing to the Inventory API model, you can use the bulkMigrateListing operation in the Inventory API.

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: 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

Note: For listings in the Inventory API model, the process to revise a single or multiple-variation listing is basically the same since an Inventory Item object exists for every product or product variation within a multiple-variation listing. In the case of a multiple-variation listing, a seller will have to follow the procedure below to update each and every variation that requires association with a catalog product.

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.

Note: The bulkCreateOrReplaceInventoryItem method was recently added to the Inventory API, and this operation allows the seller to create or update up to 25 inventory item records at once. The bulkCreateOrReplaceInventoryItem method works similarly to the createOrReplaceInventoryItem operation except that the sku value is passed in for each product in the request payload instead of being passed in at the end of the resource URI.

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. 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).

Phase 1 Creating Inventory Listings

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.

Note: The bulkCreateOrReplaceInventoryItem method was recently added to the Inventory API, and this operation allows the seller to create or update up to 25 inventory item records at once. The bulkCreateOrReplaceInventoryItem method works similarly to the createOrReplaceInventoryItem operation except that the sku value is passed in for each product in the request payload instead of being passed in at the end of the resource URI.

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.