Testing Product-Based Shopping Experience APIs in sandbox

With the Product-Based Shopping Experience (PBSE) rolling out to five eBay sites in 2018, sellers on these five sites will have to start associating all new and existing listings to eBay Catalog products for some eBay categories/product lines. To help sellers with this task, eBay has recently rolled out two new APIs (Compliance API and Catalog API), and have made updates to existing APIs.

PBSE is being rolled out in two phases in 2018. This document can be used as a reference when testing new API calls in Sandbox. Some test use cases in this document are relevant to Phase 1 and Phase 2, and some test use cases are for Phase 1 or for Phase 2 only. Which phase(s) each test use case is relevant to will be called out in this document.

This document describes the test use cases available as of May 2018. Please note that all of the eBay Catalog products and data in this document are for test purposes only.

Table of Contents

Creating single-SKU listings using eBay Catalog products
Creating multiple-SKU listings using eBay Catalog products in Phase 1
Creating multiple-SKU listings using eBay Catalog products in Phase 2
Testing Compliance API
Testing if product line requires a catalog product (Phase 1)
Testing if category requires a catalog product (Phase 2)
Testing Catalog API - searching for catalog products
Testing Catalog API - creating and retrieving catalog change requests
Testing Product Metadata calls in Catalog API
Distinguishing between product aspects and instance aspects
New detail fields added to item specifics

Creating single-SKU listings using eBay Catalog products

Phase(s): Phase 1 and Phase 2

API(s): Inventory or Trading

Available for Testing: Now

The createOrReplaceInventoryItem call of the Inventory API or the AddItem call of the Trading API can be used to create a new listing that is associated with an eBay Catalog product.

Phase 1 Testing

For Phase 1 testing, the table below has just a few eBay Catalog products and PBSE categories that you can use.

ePID	Leaf Category ID	Product title
151029249	162	Corel Game Capture HD Pro Video Input Adapter RGCHDPR1ENAM for Windows RGCHDPR1ENAM
113396162	3323	Canon EF 50mm f/1.8 II Lens
2099689951	3709	Lenovo 4337 ThinkPad Mini Dock Series 3 Docking Station With Keys 75y5734
219508495	11071	Samsung 5200 Series UN40J5200 40" 1080p HD LED LCD Internet TV
236715061	11071	Vizio D-Series D32f-E1 32" 1080p HD Full Array LED Internet TV
177661707	11844	Mangroomer Ultimate Pro Cordless Rechargeable Men's Electric Shaver
219485612	11844	Braun Series 9 9090cc Cord/Cordless Rechargeable Men's Electric Shaver
66718804	20598	NuTone 9417DN Heater
216192392	42428	Apple iPhone 6s Plus - 16GB - Silver (Unlocked) A1634 (CDMA + GSM)
239068334	42428	Apple iPhone 8 Plus - 256GB - Space Gray (Unlocked) A1897 (GSM)

See the Creating listings with a catalog product using the Inventory API topic for information on creating a product-based listing using the Inventory API, or the Creating listings with a catalog product using the Trading API topic for information on creating a product-based listing using the Trading API. Note that by passing in the ePID value for a catalog product, the listing will automatically pick up the product title, product description, product aspects, stock photo, and listing category.

Phase 2 Testing

To test Phase 2 functionality, use can use the following test category IDs and test catalog products:

Category ID: 178089, ePID: 30000689833
Category ID: 178090, ePID: 30000689834
Category ID: 178097, ePID: 30000689835

Creating multiple-SKU listings using eBay Catalog products in Phase 1

Phase(s): Phase 1

API(s): Inventory or Trading

Available for Testing: Now

The createOrReplaceInventoryItem call of the Inventory API or the AddFixedPriceItem call of the Trading API can be used to create a new multiple-variation listing, where each variation is associated with an eBay Catalog product. For Phase 1, the GTIN value (UPC, ISBN, or EAN) instead of the ePID value is supplied for each variation.

See the Creating listings with a catalog product using the Inventory API topic for information on creating a product-based, multiple-variation listing using the Inventory API, or the Creating multiple-variation listings with a catalog product using the Trading API topic for information on creating a product-based, multiple-variation listing using the Trading API.

Creating multiple-SKU listings using eBay Catalog products in Phase 2

Phase(s): Phase 2

API(s): Inventory or Trading

Available for Testing: Now

The createOrReplaceInventoryItem call of the Inventory API or the AddFixedPriceItem call of the Trading API can be used to create a new multiple-variation listing, where each variation is associated with an eBay Catalog product. For Phase 2, the ability to supply an ePID value for each variation becomes available, where previously, the seller supplied a GTIN value (UPC, ISBN, or EAN) instead.

Testing Compliance API

Phase(s): Phase 1 and Phase 2

API(s): Compliance

Available for Testing: Now. Please note that API only returns a canned response in Sandbox for Phase 1 and Phase 2. In Production, this API returns real seller data for Phase 1. Production readiness for Phase 2 (including recommended eBay Catalog products functionality) is planned for July 2018.

The Compliance API has one call that is used by seller to retrieve a count of active listings currently not complying with the PBSE requirement, and another call to retrieve actual data on each active listing (and/or variations within listing) that require association with an eBay Catalog product. The endpoints for these two calls are shown below. This API requires an OAuth token. See the OAuth access tokens help topic for information on getting an Oauth token.

getListingViolationsSummary

GET https://api.ebay.com/sell/compliance/v1/listing_violation_summary

This operation has a compliance_type query parameter that lets you filter by one or more compliance types, but only the PRODUCT_ADOPTION compliance type is applicable to Product-Based Shoppping Experience. If you don't use the compliance_type query parameter, a listing count for all three compliance types (including PRODUCT_ADOPTION) will be returned.

The response of this call shows a listingCount field. If the value of this field is greater than '0', the getListingViolations operation should be used to get specific data on the listings that are not compliant

getListingViolations

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

This operation also has a compliance_type query parameter that lets you filter by one of three compliance types. To retrieve data on active listings that require association with an eBay Catalog product, include the compliance_type query parameter and set its value to PRODUCT_ADOPTION.

See the call sample in the getListingViolations call reference for an example of this call's response payload. Each violation for each non-compliant listing is returned in the response, along with a reasonCode value that can be used to troubleshoot the issue.

Note: When testing in the Sandbox environment, these calls will only returned canned responses. For more information on the different reasonCode values that can be returned and how to troubleshoot the issues, see the Using Compliance API reason codes to revise listings topic

Testing if product line requires a catalog product

Phase(s): Phase 1

API(s): Trading

Available for Testing: Now

The GetCategorySpecifics call was updated to return a ProductRequired tag if a product brand within a listing category requires a catalog product when listing/revising an item.

To test this functionality, use the following data:

Use '9355' as the Category ID in the GetCategorySpecifics request payload.
In the response, look for 'brand' in one of the NameRecommendation.Name fields. In that same NameRecommendation container, you should see multiple brand names/products. Look for your brand and a ValidationRules.ProductRequired field, with a value of 'Enabled', as shown below.

<ValueRecommendation>
    <Value>Apple</Value>
    <ValidationRules>
        <ProductRequired>Enabled</ProductRequired>
    </ValidationRules>
</ValueRecommendation>

The new getProductAdoptionPolicies operation in the Metadata API is now available for testing in the Sandbox and Production environments.

Testing if category requires a catalog product

Phase(s): Phase 2

API(s): Trading

Available for Testing: Now

The GetCategoryFeatures call was updated to return a Category.ProductRequiredEnabled tag if an eBay category requires a catalog product when listing/revising an item. Instead of only a partial list of product lines within a category requiring a catalog product, like in Phase 1, complete leaf categories will be affected in Phase 2.

As Phase 2 hasn't taken effect yet, the Category.ProductRequiredEnabled field will not be returned for any active eBay categories. However, the following eBay test categories for the US site are available for testing this Phase 2 functionality in GetCategoryFeatures:

178089
178090
178097

To see if a specific category requires a catalog product, you'd use the following request payload:

<?xml version="1.0" encoding="utf-8"?>
<GetCategoryFeaturesRequest xmlns="urn:ebay:apis:eBLBaseComponents">
   <RequesterCredentials>
      <eBayAuthToken>AgAAAA**.../96cN</eBayAuthToken>
   </RequesterCredentials>
   <ErrorLanguage>en_US</ErrorLanguage>
   <WarningLevel>High</WarningLevel>
   <CategoryID>178089</CategoryID>
   <FeatureID>ProductRequiredEnabled</FeatureID>
   <DetailLevel>ReturnAll</DetailLevel>
</GetCategoryFeaturesRequest>

If the category required a catalog product, the ProductRequiredEnabled tag would be returned under the Category container as shown below:

<Category>
   <CategoryID>178089</CategoryID>
   <ProductRequiredEnabled>Enabled</UPCEnabled>
</Category>

Testing Catalog API - searching for catalog products

Phase(s): Phase 1 and Phase 2

API(s): Catalog

Available for Testing: Now

The Catalog API has one call that is used by seller to search for an eBay Catalog product by GTIN value or by keyword, and another call to retrieve full product details on an eBay Catalog product. The endpoints for these two calls are shown below. This API requires an OAuth token. See the OAuth access tokens help topic for information on getting an Oauth token.

search

GET https://api.ebay.com/commerce/catalog/v1_beta/product_summary/search?

To use this call to search by a GTIN value, the user would pass in an actual GTIN value through the gtin query parameter, as shown below:

GET

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

To use this call to search by a query value, the user would pass in a query string through the q query parameter, as shown below:

GET

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

Based on the criteria in the call request, one or more matching eBay Catalog products are returned in the response. Details of the response include the ePID value of the product (and associated GTIN value(s), product title, product aspects, link to stock photo(s), and a link to the product page.

getProduct

GET https://api.ebay.com/commerce/catalog/v1_beta/product/216192392

A valid ePID value is passed in at the end of the call URI. If the eBay Catalog product is found, complete details of the catalog product are returned in the response.

Sample getProduct test cases

The following test catalog products were added to Sandbox:

ePID: 30000689833
ePID: 30000689834
ePID: 30000689835

To get the product details of ePID 30000689833, submit the following:

GET https://api.ebay.com/commerce/catalog/v1_beta/product/30000689833

The following response should get returned:

{
  "aspects": [
    {
      "localizedName": "BRAND",
      "localizedValues": [
        "Nike"
      ]
    },
    {
      "localizedName": "eBay Product ID (ePID)",
      "localizedValues": [
        "30000689833"
      ]
    }
  ],
  "title": "This is a test product for category 178089",
  "description": "Test Product",
  "version": "0",
  "image": {
    "imageUrl": "https://i.ebayimg.com/00/z/V~8AAOxy2BBSUmtn/$T2eC16hHJGkFFmw)uO0PBSUmtnYCZ!~~_8.JPG?set_id=89040003C1"
  },
  "brand": "Nike",
  "epid": "30000689833",
  "productWebUrl": "https://www.ebay.com/p/This+is+a+test+product+for+category+178089/30000689833?src=urllib",
  "primaryCategoryId": "178089",
  "otherApplicableCategoryIds": [
    "178089"
  ]
}

Now, attempt to retrieve the following eBay Catalog product:

GET https://api.ebay.com/commerce/catalog/v1_beta/product/632506199

This call should fail with the message, "The specified EPID value 632506199 was not found.".

Now, attempt to retrieve the following eBay Catalog product:

GET https://api.ebay.com/commerce/catalog/v1_beta/product/895130588

This call should fail with the message, "The specified EPID value 895130588 is no longer available.".

Testing Catalog API - creating and retrieving catalog change requests

Phase(s): Phase 2

API(s): Catalog

Available for Testing: Now. Please note that any actions taken with the catalog change request operations is only for test purposes, and neither the eBay Catalog in Sandbox nor in Production environment will be affected.

The Catalog API has three calls related to catalog change requests. One call is used by seller to make a request to eBay to add a new product to the eBay Catalog, or to make a request to eBay to revise an existing catalog product. The other two calls are 'Get' calls: one call retrieves the status of a specific catalog change request, and the other can retrieve multiple catalog change requests. This API requires an OAuth token. See the OAuth access tokens help topic for information on getting an Oauth token.

Creating a request to add a product to the eBay Catalog

The createChangeRequest call is used to make a request to eBay to add a product to the eBay Catalog. Below is the endpoint for this call:

POST https://api.ebay.com/commerce/catalog/v1_beta/change_request

See the createChangeRequest call reference document for more information, but the following information must be supplied in the request payload when making a request to add a product to the eBay Catalog:

changeRequestType field must be set to PRODUCT_CREATION
full details of the product, including associated GTIN value(s), product title, product description, product aspects, link to stock photo(s) are provided under the suggestedProduct container
the eBay category to add the new product is set in the suggestedProduct.primaryCategoryId field

All catalog change requests are processed asynchronously. If a createChangeRequest call is successful, a Location header will be returned in the response. This header will have the unique identifier of the catalog change request. This unique identifier is needed when calling getChangeRequest to get the status of the catalog change request.

Creating a request to revise a product in the eBay Catalog

The createChangeRequest call is also used to make a request to eBay to revise a product in the eBay Catalog. Below is the endpoint for this call:

POST https://api.ebay.com/commerce/catalog/v1_beta/change_request

See the createChangeRequest call reference document for more information, but the following information must be supplied in the request payload when making a request to revise a product in the eBay Catalog:

changeRequestType field must be set to PRODUCT_UPDATE
reasonForChangeRequest must be included, and should summarize the product details that the seller wishes to revise
the ePID value of the catalog product that the seller wants to revise is set in the suggestedProduct.epid field
the catalog product version is set in the suggestedProduct.version field. The catalog product version is returned in the getProduct operation.
full details of the product, including associated GTIN value(s), product title, product description, product aspects, link to stock photo(s) are provided under the suggestedProduct container. All product details are needed, including the details that should remain the same and those that the seller is proposing to revise

Retrieving status of a catalog change request

The getChangeRequest call is also used to get the status of a specific catalog change request. If a createChangeRequest call is successful, a Location header will be returned in the response. This header will have the unique identifier of the catalog change request. Below is the endpoint for this call:

GET https://api.ebay.com/commerce/catalog/v1_beta/change_request/{change_request_id}

In the response of the getChangeRequest call, the seller will be particularly interested in the expectedCompletionDate field to get a sense of when eBay will evaluate and make a decision on the catalog change request, as well as the changeRequestStatus field. Each status is discussed in more detail below.

SUBMITTED

A catalog change request will have this status right after being submitted via a createChangeRequest call.

UNDER_REVIEW

A catalog change request will have this status while being reviewed by eBay.

UNDER_EXTENDED_REVIEW

The status of a catalog change request will go from UNDER_REVIEW to UNDER_EXTENDED_REVIEW if the review by eBay takes longer than about one hour.

APPROVED

This status will be returned if eBay has approved the catalog change request. If the catalog change request was to create a new eBay Catalog product, the seller can now grab the newly-created ePID value in the processResolution.epid field, and then create a listing based on this newly-created catalog product. If the catalog change request was to revise an existing eBay Catalog product, the catalog product has been updated with the seller's proposed change(s), and now the seller can create a listing based on this newly-updated catalog product.

APPROVED_WITH_MODIFICATIONS

This status will be returned if eBay has partially approved the catalog change request. For more details on what was accepted by eBay and what wasn't accepted, see the processResolution.corrections container.

REJECTED

This status will be returned if eBay has rejected the catalog change request. For more details on why the catalog change request was rejected, see the processResolution.violations container.

Catalog API test cases

This section will provide examples of creating/updating a catalog product through a createChangeRequest call, and then testing/validating each of the different changeRequestStatus values that are returned, as well as the different violations, corrections, and warnings that can occur when making a createChangeRequest call.

Testing for SUBMITTED status

To retrieve a status of SUBMITTED for your catalog change request, run a createChangeRequest call with the request payload identical to the following, with the values in red being key to getting the SUBMITTED status.

Note: The following example is for a fictional product and solely used to demonstrate the usage of the Catalog API.

{
   "changeRequestType": "PRODUCT_CREATION",
   "reasonForChangeRequest": "Request to add new product"
   "suggestedProduct": {
  "title": "Apple iPhone 6 submitted",
  "description": "This Space Grey iPhone 6 comes with 256GB of storage, and can be used on any
 carrier network in US.",
  "primaryCategoryId": "9355",
  "aspects": [
     {
    "name": "Features",
    "values": ["Touch Screen", "Bluetooth", "Digital Camera", "GPS", "Speakerphone"]
     },
     {
    "name": "Storage Capacity",
    "values": ["256GB"]
     },
     {
    "name": "Color",
    "values": ["Space Gray"]
     },
     {
    "name": "Network Generation",
    "values": ["2G", "3G", "4G"]
     },
     {
    "name": "Camera Resolution",
    "values": ["12.0MP"]
      },
     {
    "name": "Connectivity",
    "values": ["Bluetooth", "WiFi"]
     }
   ],
  "imageUrl": "https://i.ebayimg.com/00/6.JPG?set_id=89040003C1",
  "brand": "Apple",
  "upc": ["0745577656433"],
  "ean": ["0885909530199"],
  "mpn": ["MD295LL/A"]
   }
}

If the preceding createChangeRequest example is processed successfully, the unique identifier of the catalog change request will be returned in the Location HTTP header. The number/letter sequence at the end of the call URI is the unique identifier of the catalog change request, and this call URI in the Location HTTP header can be used to get the status of the catalog change request.

GET https://api.ebay.com/commerce/catalog/v1_beta/change_request/<catalog_change_request_id>

If the call is processed successfully, you should get a changeRequestStatus value of SUBMITTED. A sample response payload is shown below:

{
    "changeRequestId": "5ac3cf22ca4c591b0c324749",
    "changeRequestType": "PRODUCT_CREATION",
    "changeRequestStatus": "SUBMITTED",
    "creationDate": "2018-04-03T18:59:46.752Z",
    "reasonForChangeRequest": "Request to add new product",
    "expectedCompletionDate": "2018-04-04T18:59:46.892Z",
    "suggestedProduct": {
  "title": "Apple iPhone 6 submitted",
  "description": "This Space Grey iPhone 6 comes with 256GB of storage, and can be used on any
 carrier network in US.",
  "primaryCategoryId": "9355",
  "aspects": [
     {
    "name": "Features",
    "values": ["Touch Screen", "Bluetooth", "Digital Camera", "GPS", "Speakerphone"]
     },
     {
    "name": "Storage Capacity",
    "values": ["256GB"]
     },
     {
    "name": "Color",
    "values": ["Space Gray"]
     },
     {
    "name": "Network Generation",
    "values": ["2G", "3G", "4G"]
     },
     {
    "name": "Camera Resolution",
    "values": ["12.0MP"]
     },
     {
    "name": "Connectivity",
    "values": ["Bluetooth", "WiFi"]
     }
  ],
  "imageUrl": "https://i.ebayimg.com/00/6.JPG?set_id=89040003C1C1",
  "brand": "Apple",
  "upc": ["0745577656433"],
  "ean": ["0885909530199"],
  "mpn": ["MD295LL/A"]
   }
}

Testing for APPROVED status

Once eBay approves a catalog change request, the changeRequestStatus field will be returned with a value of APPROVED. To retrieve a status of APPROVED for your catalog change request, run a createChangeRequest call (to create a new product) with the request payload identical to the following, with the values in red being key to getting the SUBMITTED status.

{
    "changeRequestType": "PRODUCT_CREATION"
    "reasonForChangeRequest": "Request to add new product",
    "suggestedProduct": {
  "title": "Apple iPhone 20",
  "description": "This Space Grey iPhone 20 comes with 256GB of storage, and can be used on any
 carrier network in US.",
  "primaryCategoryId": "9355",
  "aspects": [
      {
    "name": "Model",
    "values": ["iPhone 20"]
      }
  ],
  "imageUrl": "https://i.ebayimg.com/00/6.JPG?set_id=89040003C1C1",
  "brand": "Apple",
  "upc": ["0745577656433"],
  "mpn": ["MD295LL/A"]
    }
}

GET https://api.ebay.com/commerce/catalog/v1_beta/change_request/<catalog_change_request_id>

If the call is processed successfully, you should get a changeRequestStatus value of APPROVED. A sample response payload is shown below:

{
   "changeRequestId": "5ac3cf22ca4c591b0c324749",
   "changeRequestType": "PRODUCT_CREATION",
   "changeRequestStatus": "APPROVED",
   "creationDate": "2018-04-03T18:59:46.752Z",
   "reasonForChangeRequest": "Request to add new product",
   "resolutionDate": "2018-04-03T19:59:46.892Z",
   "suggestedProduct": {
  "title": "Apple iPhone 20",
  "description": "This Space Grey iPhone 20 comes with 256GB of storage, and can be used on any
 carrier network in US.",
  "primaryCategoryId": "9355",
  "aspects": [
     {
    "name": "Model",
    "values": ["iPhone 20"]
     }
  ],
  "imageUrl": "https://i.ebayimg.com/00/6.JPG?set_id=89040003C1C1",
  "brand": "Apple",
  "upc": ["0745577656433"],
  "mpn": ["MD295LL/A"]
   }
        
"processResolution": {
  "epid": "114795376",  
  "productHref": "http://api.ebay.com/commerce/catalog/v1_beta/product/114795376"
  }
}

Additionally, a processResolution container should be returned with two fields: the new epid value for the approved product, and the productHref field, which is actually the call URI that can be used in a getProduct call to retrieve new eBay Catalog product definition.

Testing for APPROVED_WITH_MODIFICATIONS status

There are several scenarios where a catalog change request will get approved by eBay but with modifications. In other words, eBay is able to process the catalog change request (to create new catalog product or revise existing product) after making modifications to one or more product details. The modification(s) that eBay made to correct the catalog change request are returned under the processResolution.corrections container. eBay modifications to product attributes (such as category, title, description, GTIN, etc.) are returned under the corrections.productAttribute container, and eBay modifications to product aspects are returned under the corrections.aspectValues container.

To retrieve a status of APPROVED_WITH_MODIFICATIONS for your catalog change request, run a createChangeRequest call (to create a new product) with the request payload identical to the following, with the values in red being key to getting the APPROVED_WITH_MODIFICATIONS status.

{
    "changeRequestType": "PRODUCT_CREATION"
    "reasonForChangeRequest": "Request to add new product",
    "suggestedProduct": {
  "title": "This is my SNOY",
  "description": "This Space Grey iPhone 20 comes with 256GB of storage, and can be used on any
 carrier network in US.",
  "primaryCategoryId": "9355",
  "aspects": [
      {
    "name": "Color",
    "values": ["Blaaaack"]
      },
    {
    "name": "Warranty",
    "values": ["1 year"]
    }
  ],
  "imageUrl": "https://i.ebayimg.com/00/6.JPG?set_id=89040003C1C1",
  "brand": "Apple",
  "upc": ["0745577656433"],
  "mpn": ["MD295LL/A"]
    }
}

GET https://api.ebay.com/commerce/catalog/v1_beta/change_request/<catalog_change_request_id>

If the call is processed successfully, you should get a changeRequestStatus value of APPROVED_WITH_MODIFICATIONS. In the same response payload, the processResolution container will show the epid value for the new catalog product, as well as the productHref field, which is actually the call URI that can be used in a getProduct call to retrieve new eBay Catalog product definition. The processResolution.corrections container displays the corrections that eBay made to the catalog change request in order to approve the request.

"processResolution": {
    "epid": "114795376",
    "productHref": "https://api.ebay.com/commerce/catalog/v1_beta/product/114795376",
    "corrections": [
  {
      "correctionCode": "1001",
      "reason": "Title value has been modified",
      "productAttribute": {
    "attributeName": "TITLE",
    "value": "This is my SNOY",
    "newValue": "This is my SONY"
      }
  },
  {
      "correctionCode": "1901",
      "reason": "Typo fixed for aspect Color. Original value Blaaaack was changed to new value
           Black",
    "aspectValues": {
        "aspectName": "Color",
        "values": [
            {
      "value": "Blaaaack",
      "newValue": "Black"
            }
        ]
    }
  },
  {
      "correctionCode": "1702",
      "reason": "Aspect Warranty has been detected as a non product attribute and hence removed",
      "productAttribute": {
    "attributeName": "ASPECT_NAME",
    "value": "Warranty"
    }
  }
    ]
}

As you can see from the preceding response payload, eBay was able to identify and fix the following three issues:

There was a misspelling in the title field. eBay was able to correct this misspelling.
There was a misspelling for the value of the color product aspect. eBay was able to correct this misspelling.
The seller provided a item aspect, "Warranty", that is not valid item aspect for the product. eBay just removed this item aspect from the catalog change request.

Testing for REJECTED status

There are scenarios where a catalog change request will get rejected by eBay. Based on the nature of the rejection, the seller will either have to make one or more revisions to their catalog change request and resubmit, or in some cases, they may have to abandon their catalog change request altogether. The reason(s) for the rejection will either be returned to the seller through the processResolution.violations container, or through the processResolution.conflictingProducts container. This section shows two test cases where a catalog change request will get rejected.

To retrieve a status of REJECTED for your catalog change request, run a createChangeRequest call (to create a new product) with the request payload identical to the following, with the values in red being key to getting the REJECTED status. In this particular test case, we introduce seven incorrect values, and get seven violations/warnings in the response.

{
    "changeRequestType": "PRODUCT_CREATION"
    "reasonForChangeRequest": "Request to add new product",
    "suggestedProduct": {
  "epid":"114795376",
  "version": "1048481621",
  "title":"BEST DEAL EVER",
  "description":"cookie",
  "primaryCategoryId":"12376585",
  "aspects": [
      {
    "name": "Features",
    "values": ["3G Data Capable", "4G Data Capable"]
      },
    {
    "name": "*",
    "values": ["Black"]
      }
  ],
  "imageUrl": "no url",
  "brand": "*",
  "upc": ["123"],
  "mpn": ["MD295LL/A"]
    }
}

GET https://api.ebay.com/commerce/catalog/v1_beta/change_request/<catalog_change_request_id>

If the call is processed successfully, you should get a changeRequestStatus value of REJECTED. In the same response payload, the processResolution container will show the epid value for the catalog product whose requested changes were rejected, as well as the seven violations that occurred that led to the REJECTED status.

"processResolution": {
    "epid": "114795376",
    "productHref": "https://api.ebay.com/commerce/catalog/v1_beta/product/114795376",
    "violations": [
  {
     "violationCode": "3201",
     "reason": "123 is an invalid UPC value",
     "productAttribute": {
    "values": ["123"],
    "name": "UPC"
     }
  },
  {
     "violationCode": "3401",
     "reason": "* is an invalid Brand value",
     "productAttribute": {
    "values": ["*"],
    "name": "BRAND"
     }
  },
  {
     "violationCode": "3701",
     "reason": "* is not a valid value for Aspect",
     "productAttribute": {
    "values": ["*"],
    "name": "ASPECT_NAME"
     }
  },
  {
     "violationCode": "3501",
     "reason": "12376585 is not a valid value for Category",
     "productAttribute": {
    "values": ["12376585"],
    "name": "CATEGORY"
     }
  },
  {
     "violationCode": "3601",
     "reason": "Image Url value is invalid",
     "productAttribute": {
    "values": ["no url"],
    "name": "IMAGE"
     }
  },
  {
     "violationCode": "3001",
     "reason": "Title value is invalid",
     "productAttribute": {
    "values": ["BEST DEAL EVER"],
    "name": "TITLE"
     }
  },
  {
     "violationCode": "3101",
     "reason": "Descripton value is invalid",
     "productAttribute": {
    "values": ["cookie"],
    "name": "DESCRIPTION"
     }
  }
    ]
  }
}

As you'll notice in the response above, there were issues with the following product details:

Product title name is invalid
Product description is invalid
Category ID is not correct
UPC is not accurate
No valid URL to a product image was supplied
'*' is not a valid aspect name
'*' is not a valid aspect value for Brand aspect

These seven issues would have to be resolved in another catalog change request.

The next example demonstrates a case where a seller is trying to add a new product to the catalog that already exists. Run a createChangeRequest call (to create a new product) with the request payload identical to the following, with the values in red being key to getting the REJECTED status.

{
    "changeRequestType": "PRODUCT_CREATION"
    "reasonForChangeRequest": "Request to add new product",
    "suggestedProduct": {
  "title":"Takata airbags",
  "description""A pair of Takata airbag",
  "primaryCategoryId":"9355",
  "aspects": [
      {
    "name": "Color",
    "values": ["Black"]
      }
  ],
  "imageUrl": "https://i.ebayimg.com/$_6.JPG?set_id=89040003C1",
  "brand": "Takata",
  "upc": ["400055803586"],
  "mpn": ["MD295LL/A"]
    }
}

GET https://api.ebay.com/commerce/catalog/v1_beta/change_request/<catalog_change_request_id>

If the call is processed successfully, you should get a changeRequestStatus value of REJECTED. In the same response payload, the processResolution container will show one violation and one conflicting product.

"processResolution": {
    "violations": [
  {
  "violationCode": "3801",
  "reason": "Invalid product to sell on ebay",
  "productAttribute": {
      "values": ["Product"],
      "name": "GENERAL"
      }
  }
    ],
    "conflictingProducts": [
  {
  "conflictCode": "5001",
  "reason": "Product is in conflict with another product",
  "epid": "240306961",
  "differentiatingAspects": [
      {
    "name": "Storage Capacity",
    "values": ["32GB"]
      },
      {
    "name": "Network",
    "values": ["Unlocked"]
      }
  ]
    }
  ]
}

The violationCode and the conflictCode in the response above indicate that the proposed product is considered a duplicate of an existing product. The differentiatingAspects container indicates which aspects the existing product has that the proposed one doesn�t have, and hence seller should either accept the existing product, or differentiate the proposed product in a new createChangeRequest.

These two issues would have to be resolved in another catalog change request.

Testing Product Metadata calls in Catalog API

The following new product metadata operations of the Catalog API are now available for testing in the Sandbox environment:

getProductMetadataForCategories: This call retrieves an array of all supported aspects, aspect constraints, and values for the specified eBay categories. The array is a union (with duplicates removed) of all returned aspects.
getProductMetadata : This call retrieves an array of all supported aspects, aspect constraints, and values for the specified catalog product and its associated or suggested categories, as well as the values currently associated with that product. The array is a union (with duplicates removed) of all returned aspects.

See the call reference documentation for more information on these two operations.

Distinguishing between product aspects and instance aspects

Phase(s): Phase 2

API(s): Trading

Available for Testing: Now

The GetCategorySpecifics call was updated to return a AspectUsage tag that distinguishes between product aspects and item/instance aspects. A MaxValueLength tag was also added for each aspect to indicate the maximum character length allowed for each aspect. The AspectUsage and MaxValueLength tags will only be returned for PBSE categories.

To test this functionality, use the following request payload, making sure to set the Category ID value to 176985:

<?xml version="1.0" encoding="utf-8"?>
<GetCategorySpecificsRequest xmlns="urn:ebay:apis:eBLBaseComponents">
   <RequesterCredentials>
    <eBayAuthToken>AgAAAA**D1VMn7/q9I990</eBayAuthToken>
   </RequesterCredentials>
   <WarningLevel>High</WarningLevel>
   <CategoryID>176985</CategoryID>
   <DetailLevel>ReturnAll</DetailLevel>
</GetCategorySpecificsRequest>

In the response, look for the 'sleeve grading' aspect, and then look for the two new tags:

<NameRecommendation>
   <Name>Sleeve Grading</Name>
   <ValidationRules>
  <ValueType>Text</ValueType>
  <MaxValues>1</MaxValues>
  <SelectionMode>FreeText</SelectionMode>
  <AspectUsage>Instance</AspectUsage>
  <MaxValueLength>200</MaxValueLength>
   </ValidationRules>

If Instance is returned in the AspectUsage field, as it is in this case, the corresponding aspect is an item (or instance) aspect. Instance aspects are aspects whose values will vary based on that particular instance of the product. When creating/revising a listing, the seller should pass in the name-value pair for this aspect through the Item.ItemSpecifics.NameValueList container of an AddItem call. The MaxValueLength value indicated that the length of 'Sleeve Grading' instance aspect value can be up to 200 characters long.

If Product is returned in the AspectUsage field, the corresponding aspect is a product aspect. Product aspects are defined through an eBay Catalog product, and sellers cannot change these product aspects unless they find that the particular product aspect is inaccurate or missing from the eBay Catalog product, in which case, they could use the Catalog API' s createChangeRequest operation to make a request to eBay to revise an existing eBay Catalog product.

New detail fields added to item specifics

Phase(s): Phase 2

API(s): Trading

Available for Testing: Now

New item specific fields were added to help distinguish special listings such as seller-created bundles, products with aftermarket modifications, and foreign product. If any of these new item specifics is applicable to a category, the GetCategorySpecifics call will return these item specifics. All of these aspects will be instance aspects (see previous section) because all of their value will be unique to the listing.

For more information on the new item specifics, see the Product aspects vs. item specifics topic.