Testing Product-Based Shopping Experience APIs in production

This guide can be used as a reference for testing an early production release of Phase 2 functionality and flows in the Production environment for Product-Based Shopping Experience (PBSE) related APIs. It provides the list of Production test categories, describes the use cases available for testing and their examples, and will help you to quickly adopt Phase 2 capabilities of PBSE.

You will be able to add and modify products using the Catalog API in test categories only, to retrieve the updated or newly created products, and to adopt these products for item listings. You will be also able to trigger listing success or failure in a test category depending on whether the product is adopted or not.

Table of Contents

• Available test categories in Production environment
• Adding a catalog product to a test category
• Updating a catalog product in a test category
• Listing against a new catalog product
• Creating a multiple-variation listing
• Listing bundles and modified or non-domestic items with instance specifics
• Using standalone catalog change request web flows
• Production test leaf categories for testing PBSE use cases

Available test categories in Production environment

Test leaf categories have been added to the Production environment for the US, UK, Australia, and Canada sites. The test leaf categories are mirrors of actual eBay categories on these sites. There are three sets of categories for each marketplace (AU, US, UK, CA[English]): PBSE-enforced, PBSE-enabled, and Non-PBSE.

• For PBSE-enforced test categories, association with an eBay Catalog product is required. Listings with no ePIDs associated will not be allowed, and listing new items or revising existing items will fail with an error.
• For PBSE-enabled test categories, association with an eBay Catalog product is supported but optional. You can submit change requests to create or modify eBay catalog products and will be allowed to list an item without associating a product with the listing itself.
• For non-PBSE test categories, All of the test categories have instance aspects (if applicable for the category), but some of the test categories do not return product aspects. There is a column in the table that denotes whether the test category returns product aspects (specifics).

All of the available test categories have instance aspects (if applicable for the category), but some of the test categories do not return product aspects. There is a column in each table that denotes whether or not the test category returns product aspects.

See Production test leaf categories for testing PBSE use cases for detailed information about the test categories.

Test cases in this document

Developers and sellers can do the following Phase 2 testing with the test categories:

• Use the getProductAdoptionPolicies method or the GetCategoryFeatures call to see if test category requires association with catalog product.
• Use the getProductMetadataForCategories method to see required/recommended product aspects for test category.
• Use the getProductMetadata method to see the required/recommended product aspects when associated to given test categories.
• Use the createChangeRequest method to make a request to add a new product to the eBay catalog in one or more of the test categories.
• Use the createChangeRequest method to make a request to revise an existing catalog product in one of the test categories.
• Use the Inventory API methods or the Trading API methods to create or revise listings and associated them with catalog products test categories.
• Use the getItemAspectsForCategory method of the Taxonomy API or the GetCategorySpecifics call of the Trading API to look for supported instance specifics in the test category.
• Experiment with the change_request methods of the Catalog API to submit and retrieve different change request statuses.
• Create new listings with the Inventory API methods or the AddItem call of the Trading API to initiate and check for different warnings and error messages.

This document describes the preceding test cases in detail.

Retrieve eBay supported product adoption policies

Use the Metadata API's getProductAdoptionPolicies call to retrieve information about all categories in an eBay marketplace, indicating whether listings in each category require adoption of a catalog product.

GET https://api.ebay.com/sell/metadata/v1/marketplace/EBAY_US/get_product_adoption_policies

The following snippet shows that listings in three EBAY_US categories must adopt a catalog product, and the fourth category does not (the productRequired field has a value of false or is not returned at all).

...
{
    "categoryTreeId": "0",
    "categoryId": "178114",
    "productRequired": true
},
{
    "categoryTreeId": "0",
    "categoryId": "178115",
    "productRequired": true
},
{
    "categoryTreeId": "0",
    "categoryId": "178116",
    "productRequired": true
},
{
    "categoryTreeId": "0",
    "categoryId": "179450"
},
...

Retrieve supported aspects for a category

Use the Catalog API's getProductMetadataForCategories call to retrieve an array of all supported aspects, aspect constraints, and aspect values for eBay test category ID 178115. The array is a union (with duplicates removed) of all returned aspects.

GET https://api.ebay.com/commerce/catalog/v1_beta/get_product_metadata_for_categories?primary_category_id=178115

The following snippet describes one aspect returned in the output (you can see an entire payload in the call reference sample):

...
{
  “name”: “Base Material”,
  “constraint”: {
    “aspectDataType”: “STRING”,
    “productToAspectCardinality”: “SINGLE”,
    “aspectMode”: “FREE_TEXT”,
    “aspectRequired”: false
  },
  “values”: [
    {
      “value”: “Fabric”
    },
    {
      “value”: “Metal”
    }
  ]
},
...

Retrieve supported aspects for a product

The Catalog API's getProductMetadata call retrieves an array of all supported aspects, aspect constraints, and aspect values for the catalog product with ePID 26020409399 and several test categories (ID's 178114, 178116,178120), as well as the values currently associated with that product. The array is a union (with duplicates removed) of the aspects for three catagories.

You can use this call to discover the available aspects when additional categories are associated with the product.

GET https://api.ebay.com/commerce/catalog/v1_beta/get_product_metadata?epid=26020409399&primary_category_id=178114&other_applicable_category_ids=178116,178120

The following snippet describes one aspect returned in the output (you can see an entire payload in the call reference sample):

… 
"aspects": [
  {
    "name": "Model",
    "valuesAssociatedWithProduct": [
      "iPhone 20"
    ],
    "constraint": {
      "aspectDataType": "STRING",
      "productToAspectCardinality": "SINGLE",
      "aspectMode": "FREE_TEXT",
      "aspectRequired": false
    },
    "values": [
      {
        "value": "ASUS PadFone 2"
      },
      {
        "value": "ASUS PadFone S"
      },
...

Adding a catalog product to a test category

Use the flow in the following tables to add a new catalog product to a test category:

Use the createChangeRequest method to make a request to add a new product to the eBay Catalog in one of the test categories. In the following examples, be sure to set the changeRequestType field to PRODUCT_CREATION. The examples demonstrate calls that produce various values in the changeRequestStatus field.

New product is approved

{
  "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 the US.",
    "primaryCategoryId": "178114",
    "aspects": [
        {
          "name": "Model",
          "values": ["iPhone 20"]
        }
    ],
    "imageUrl": "https://i.ebayimg.com/00/6.JPG?set_id=89040003C1C1",
    "brand": "Apple",
    "upc": ["0745577656433"],
    "mpn": ["MD295LL/A"]
  }
}

{
  “changeRequestId”: “5b22ed268702d13a07161d1c”,
  “changeRequestType”: “PRODUCT_CREATION”,
  “changeRequestStatus”: “APPROVED”,
  “creationDate”: “2018-06-14T22:33:10.740Z”,
  “reasonForChangeRequest”: “Request to add new product”,
  “resolutionDate”: “2018-06-14T22:33:13.160Z”,
  “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”: “178114",
    “aspects”: [
      {
        “name”: “Model”,
        “values”: [
            “iPhone 20”
        ]
      }
    ],
    “imageUrl”: “https://i.ebayimg.com/00/6.JPG?set_id=89040003C1C1“,
    “brand”: “Apple”,
    “mpn”: [
        “MD295LL/A”
    ],
    “upc”: [
        “0745577656433"
    ]
  },
  “processResolution”: {
      “epid”: “26020409399”,
      “productHref”: “https://api.ebay.com/commerce/catalog/v1_beta/product/26020409399”
  }
}

{
   “aspects”: [
       {
           “localizedName”: “BRAND”,
           “localizedValues”: [
               “Apple”
           ]
       },
       {
           “localizedName”: “eBay Product ID (ePID)“,
           “localizedValues”: [
               “26020409399"
           ]
       },
       {
           “localizedName”: “Model”,
           “localizedValues”: [
               “iPhone 20"
           ]
       }
   ],
   “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.“,
   “version”: “0",
   “image”: {
       “imageUrl”: “https://i.ebayimg.com/00/6.JPG?set_id=89040003C1C1”
   },
   “gtin”: [
       “0745577656433”
   ],
   “mpn”: [
       “MD295LL/A”
   ],
   “upc”: [
       “0745577656433”
   ],
   “brand”: “Apple”,
   “epid”: “26020409399”,
   “productWebUrl”: “https://www.ebay.com/p/Apple+iPhone+20/26020409399”,
   “primaryCategoryId”: “178114”,
   “otherApplicableCategoryIds”: [
       “178114”
   ]
}

New product is approved with modifications

{
   “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”: “178114",
    “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”]
   }
} 

{
    "changeRequestId": "5b22fdf28702d13a07161d22",
    "changeRequestType": "PRODUCT_CREATION",
    "changeRequestStatus": "APPROVED_WITH_MODIFICATIONS",
    "creationDate": "2018-06-14T23:44:50.777Z",
    "reasonForChangeRequest": "Request to add new product",
    "resolutionDate": "2018-06-14T23:44:51.643Z",
    "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": "178114",
        "aspects": [
            {
                "name": "Color",
                "values": [
                    "Blaaaack"
                ]
            },
            {
                "name": "Warranty",
                "values": [
                    "1 year"
                ]
            }
        ],
        "imageUrl": "https://i.ebayimg.com/00/6.JPG?set_id=89040003C1C1",
        "brand": "Apple",
        "mpn": [
            "MD295LL/A"
        ],
        "upc": [
            "0745577656433"
        ]
    },
    "processResolution": {
        "epid": "3020418775",
        "productHref": "https://api.ebay.com/commerce/catalog/v1_beta/product/3020418775",
        "corrections": [
            {
                "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"
                }
            }
        ]
    }
}

{
   “aspects”: [
       {
           “localizedName”: “BRAND”,
           “localizedValues”: [
               “Apple”
           ]
       },
       {
           “localizedName”: “eBay Product ID (ePID)“,
           “localizedValues”: [
               “3020418775"
           ]
       },
       {
           “localizedName”: “Color”,
           “localizedValues”: [
               “Black”
           ]
       }
   ],
   “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.“,
   “version”: “0",
   “image”: {
       “imageUrl”: “https://i.ebayimg.com/00/6.JPG?set_id=89040003C1C1
https://i.ebayimg.com/00/6.JPG?set_id=89040003C1C1
”
   },
   “gtin”: [
       “0745577656433”
   ],
   “mpn”: [
       “MD295LL/A”
   ],
   “upc”: [
       “0745577656433”
   ],
   “brand”: “Apple”,
   “epid”: “3020418775”,
   “productWebUrl”: “https://www.ebay.com/p/Apple+iPhone+20/3020418775”,
   “primaryCategoryId”: “178114”,
   “otherApplicableCategoryIds”: [
       “178114”
   ]
}

Verifying catalog product changes

Once your change request has been approved (with or without modifications), you should be able to see the result on eBay. Use the following URL format to view the product page for the newly created catalog product:

https://www.ebay.com/p/epid

Where epid is the product ID returned in the approved getChangeRequest response. From the above examples:

• https://www.ebay.com/p/26020409399
• https://www.ebay.com/p/3020418775

New product request has SUBMITTED status

{
  "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": "178114",
    "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"]
  }
}

{
  "changeRequestId": "5b22f1738702d13a07161d1e",
  "changeRequestType": "PRODUCT_CREATION",
  "changeRequestStatus": "SUBMITTED",
  "creationDate": "2018-06-14T22:51:31.509Z",
  "reasonForChangeRequest": "Request to add new product",
  "resolutionDate": "2018-06-14T22:51:31.610Z",
  "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": "178114",
    "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",
    "mpn": [
      "MD295LL/A"
    ],
    "ean": [
      "0885909530199"
    ],
    "upc": [
      "0745577656433"
    ]
  },
  "processResolution": {}
}

New product request is rejected

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

{
    "changeRequestId": "5b23054e356685422ebf450e",
    "changeRequestType": "PRODUCT_CREATION",
    "changeRequestStatus": "REJECTED",
    "creationDate": "2018-06-15T00:16:14.349Z",
    "reasonForChangeRequest": "Request to add new product",
    "resolutionDate": "2018-06-15T00:16:14.462Z",
    "suggestedProduct": {
        "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": "*",
        "mpn": [
            "MD295LL/A"
        ],
        "upc": [
            "123"
        ]
    },
    "processResolution": {
        "violations": [
            {
                "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": "3803",
                "reason": "Category 12376585 
is not open for product change requests",
                "productAttribute": {
                    "values": [
                        "12376585"
                    ],
                    "name": "CATEGORY"
                }
            },
            {
                "violationCode": "3201",
                "reason": "123 is an invalid UPC value",
                "productAttribute": {
                    "values": [
                        "123"
                    ],
                    "name": "UPC"
                }
            },
            {
                "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"
                }
            }
        ]
    }
}

Updating a catalog product in a test category

Use the createChangeRequest method to make a request to revise an existing catalog product in one of the test categories. You can use the preceding PRODUCT_CREATION examples to test for the outcomes in those examples by adjusting your createChangeRequest call as follows:

• Set the value of the changeRequestType field to PRODUCT_UPDATE.
• Include the suggestedProduct.epid field, set to the value returned by the getChangeRequest call in the processResolution.epid field of an approved new product change request.
• Include the suggestedProduct.version field, set to the value returned by the getChangeRequest call in the suggestedProduct.version field of an approved new product change request.

The following tables contain additional examples that demonstrate requests ending in the UNDER_REVIEW and UNDER_EXTENDED_ REVIEW values of the changeRequestStatus field. The createChangeRequest call submits the ePID of a product previously created with a successful PRODUCT_CREATION request.

Product update request is under review

{
  "changeRequestType": "PRODUCT_UPDATE",
  "reasonForChangeRequest": "Request to update a product",
 
  "suggestedProduct": {
    "title": "Appeal is being reviewed by agent",
    "description": "This Space Grey iPhone 20 comes with 256GB 
of storage, and can be used on any carrier network in the US.",
    "primaryCategoryId": "178114",
     "version": "1",
  "epid": "3020418775",
    "aspects": [
        {
          "name": "Model",
          "values": ["iPhone 20"]
        }
    ],
    "imageUrl": "https://i.ebayimg.com/00/6.JPG?set_id=89040003C1C1",
    "brand": "Apple",
    "upc": ["0745577656433"],
    "mpn": ["MD295LL\/A"]
  }
}

{
    "changeRequestId": "5b243489fae61a2960b852b6",
    "changeRequestType": "PRODUCT_UPDATE",
    "changeRequestStatus": "UNDER_REVIEW",
    "creationDate": "2018-06-15T21:50:01.422Z",
    "reasonForChangeRequest": "Request to update a product",
    "resolutionDate": "2018-06-15T21:50:01.568Z",
    "suggestedProduct": {
        "epid": "3020418775",
        "version": "1",
        "title": "Appeal is being reviewed by agent",
        "description": "This Space Grey iPhone 20 comes with 256GB 
of storage, and can be used on any carrier network in the US.",
        "primaryCategoryId": "178114",
        "aspects": [
            {
                "name": "Model",
                "values": [
                    "iPhone 20"
                ]
            }
        ],
        "imageUrl": "https://i.ebayimg.com/00/6.JPG?set_id=89040003C1C1",
        "brand": "Apple",
        "mpn": [
            "MD295LL/A"
        ],
        "upc": [
            "0745577656433"
        ]
    },
    "processResolution": {}
}

Product update request is under extended review

{
  "changeRequestType": "PRODUCT_UPDATE",
  "reasonForChangeRequest": "Request to update a  product",
  "suggestedProduct": {
    "aspects": [
    
    ],
    "title": "How to optimize for free shipping",
    "description": "This Space Grey iPhone 20 comes with 256GB 
of storage, and can be used on any carrier network in the US.",
    "version": "2",
    
    "mpn": [
      "MD295LL/A"
    ],
    "upc": [
      "0745577656433"
    ],
    "brand": "Apple",
    "epid": "26020409399",
    
      "imageUrl": "https://i.ebayimg.com/00/6.JPG?set_id=89040003C1C1",
    
    "primaryCategoryId": "178114"
  }
}

{
    "changeRequestId": "5b24369e8702d13a07161d25",
    "changeRequestType": "PRODUCT_UPDATE",
    "changeRequestStatus": "UNDER_EXTENDED_REVIEW",
    "creationDate": "2018-06-15T21:58:54.501Z",
    "reasonForChangeRequest": "Request to update a  product",
    "resolutionDate": "2018-06-15T21:58:54.755Z",
    "suggestedProduct": {
        "epid": "26020409399",
        "version": "2",
        "title": "How to optimize for free shipping",
        "description": "This Space Grey iPhone 20 comes with 256GB 
of storage, and can be used on any carrier network in the US.",
        "primaryCategoryId": "178114",
        "imageUrl": "https://i.ebayimg.com/00/6.JPG?set_id=89040003C1C1",
        "brand": "Apple",
        "mpn": [
            "MD295LL/A"
        ],
        "upc": [
            "0745577656433"
        ]
    },
    "processResolution": {}
}

Listing against a new catalog product

Once you have created a new catalog product in one of the test categories, you can use either the Inventory API methods or the Trading API's AddItem call to create a listing that is associated with this new catalog product. The following two sections summarize the process for each API.

Listing against a new catalog product with Inventory API

The process for using the Inventory API to create a new listing associated with a catalog product is covered under Creating listings with a catalog product using the Inventory API. This assumes you have already created an inventory location using the createInventoryLocation call.

To list a product in a test category:

1. Use the createOrReplaceInventoryItem call to create an inventory item record. Include the seller-defined stock keeping unit (SKU) identifier for the item in the call's sku parameter. The SKU value is currently required to create an inventory item. Include also the product.epid field with the ePID value of 26020409399, which identifies the new catalog product that was previously created by the APPROVED change request in test category 178114. The product could also have been created with a change request that was APPROVED_WITH_MODIFICATIONS. As long as eBay is able to match the supplied ePID value to the catalog product, all product details of the new catalog product are picked up by the inventory item record.
2. Use the createOffer call to produce an unpublished offer of the inventory item. Include the categoryId field with the test category ID, 178114, that you previously used to create the product. This call returns the offerId field, the value of which you use for the next step.
3. Use the publishOffer call to publish the offer as an eBay listing. Include the offerId value from the previous step as a path parameter.

Because test category 178114 is a PBSE-enforced category, listings in this category must adopt a catalog product. You can examine the Production test leaf categories for testing PBSE use cases to see which ones are PBSE-enforced and which are only PBSE-enabled. Listings of items in a PBSE-enabled category can be created without adopting a catalog product.

Listing against a new catalog product with Trading API

Use the AddItem or AddFixedPriceItem call to create a new listing in test category 178114. You include this value in the Item.PrimaryCategory.CategoryID field, along with the other fields required by the call.

Test category 178114 is a PBSE-enforced category, which indicates that listings in this category must adopt a catalog product. You must also include the ePID value of 26020409399 in the ProductListingDetails.ProductReferenceID field of the AddItem or AddFixedPriceItem call or the call will fail. The ePID 26020409399 identifies the new catalog product that was previously created by the APPROVED change request in test category 178114. The product could also have been created with a change request that was APPROVED_WITH_MODIFICATIONS.

You can examine the Production test leaf categories for testing PBSE use cases to see which ones are PBSE-enforced and which are only PBSE-enabled. Listings of items in a PBSE-enabled category can be created without adopting a catalog product.

The Trading API listing process is covered in the Creating a single-variation listing with a catalog product using the Trading API PBSE Playbook topic.

Verifying the catalog product in your listing

To verify that your new catalog product has been adopted for your listing, you can examine the listing programmatically or on the eBay website.

• Use the Trading API's GetItem call to retrieve the details of the listed item. The ePID value should be returned in the ProductReferenceID field.
• Go to your Seller page on My eBay and examine your active item listings. The ePID value should be in the item details.

Creating a multiple-variation listing

Each variation in a multiple-variation (or multi-SKU) listing is treated as an independent inventory item which could be listed by itself. As such, each variation should have its own seller-defined stock keeping unit (SKU) identifier, and for PBSE, each listing will be based on a different catalog product. You can create multi-SKU listings with the Inventory API or the Trading API.

Adding multiple new catalog products to a test category

Go to the Adding catalog product to test category section for details on how to add a new catalog product to test category 178114 using the createChangeRequest call, using . Repeat this step for each variation (SKU).

Creating a multiple-variation listing using Inventory API

To list multiple variations of seller inventory in a test category:

1. Use the createOrReplaceInventoryItem call to create an inventory item record for each variation. Include the seller-defined SKU identifier for the item in the call's sku parameter. The SKU value is required to create an inventory item. Include also the product.epid field for each variation, but do NOT use an ePID value. Currently, the variation's ePID value is not supported for listing multiple variations; instead, provide a valid GTIN value (EAN, ISBN, or UPC) in the epid field. The ePID value will be supported later in Summer 2018.
   
2. Use the createOrReplaceInventoryItemGroup call to associate multiple inventory items together so they will appear as variations in the same listing. The seller must define a unique identifier for the group and submit it in the call's inventoryItemGroupKey parameter. This key cannot be changed once the inventory item group has been created. Use the variantSKUs container to specify the all of the inventory items/variations that will be part of the group.
3. Use the createOffer call to produce an unpublished offer of each inventory item (variation) in the group. Include the categoryId field with the test category ID 178114 that you previously used to create each product. Repeat this step for each inventory item in the group.
4. Use the publishOfferByInventoryItemGroup call to simultaneously publish the offers created for all variations in the group as a single multi-SKU listing. You identify the group using the seller's previously created inventoryItemGroupKey.

Creating a multiple-variation listing using Trading API

The AddFixedPriceItem call (AddItem call doesn't support variations) is used to create a new multiple-variation listing that is associated with a catalog product. This process is covered in the Creating a multiple-variation listing with a catalog product using the Trading API section of the Phase 2 recommended workflows using Trading API PBSE Playbook topic.

• Include the PrimaryCategory.CategoryID field with the test category ID 178114 that you previously used to create each catalog product.
• Currently, the variations' ePID values are not supported for listing multiple variations; the ePID value will be supported later in Summer 2018. Include instead a GTIN field (EAN/ISBN/UPC) in the call with a valid GTIN value for each variation.
• To manually provide the appropriate values for all of the product details for each variation, see Using Multi-Variation Listings..

Viewing a successfully created multiple-variation listing

Use the listingId that is returned in the publishOfferByInventoryItemGroup method of the Inventory API, or the ItemID that is returned in the AddFixedPriceItem call of the Trading API to view the results of the listing

In the Trading API, you could call GetItem to verify that each variation was created correctly with the right ePID value. In the GetItem request payload, you'd set the following parameters:

• ItemID: the unique identifier of the listing
• IncludeItemSpecifics: include this boolean and set it to true
• DetailLevel: include this field and set it to ReturnAll

In the response, verify that each variation has the correct information, including the ePID value that is found in the Variation.VariationProductListingDetails container.

In the Inventory API, you can call getOffer to verify listing-level data like price or availableQuantity. The listingId value returned in that call should be the same for all offers in that inventory item group, and the returned status value should be PUBLISHED. The getInventoryItem method can be called to verify variation-level data that is found in the product container, including the ePID value, and the groupIds value should be returned, and the same value for all inventory items in the inventory item group.

Listing bundles and modified or non-domestic items with instance specifics

When creating special listings like bundles, modified items, and foreign items you will still need to associate them with a catalog product. Follow the flow in the table below to create a new product-based listing with instance specifics in an eBay test category. This process is covered in the Associating catalog products to special listings section of the playbook.

The instance aspects to include in special listings like Custom Bundle, Bundle Description, Modified Item, Modification Description, Non-Domestic Product, and Applicable Regions are described in the table below.

If you're working with the Trading API, use the GetCategorySpecifics call to get instance specific aspects for one of the test categories provided here. This will reveal which aspects are allowed for the given category and which aspects are instance aspects (aspects that can be provided for a listing but not for a catalog product). The AspectUsage fields in the NameRecommendation.ValidationRules container can be accompanied by a MaxValueLength field. If you're using the Taxonomy API, call the getItemAspectsForCategory method and pass the test category ID in the category_id query parameter.

Using standalone catalog change request web flows

Third-party developers can use eBay's stand-alone web pages to enable sellers to file requests to add or update products in the eBay catalog and view the status of these requests, without building their own user interface on top of the Catalog API.

The standalone catalog change request web flows will be available for the production test categories. For more information on setting this up, please see the Making a catalog change request using stand-alone web flows section in the Making a catalog change request PBSE Playbook topic.

Production test leaf categories for testing PBSE use cases

In the following tables there are three sets of categories for each marketplace (AU, US, UK, CA[English]): PBSE-enforced, PBSE-enabled, and Non-PBSE. Each test category has instance aspects (if applicable for the category). For the non-PBSE categories the product aspects are not returned by the Catalog API's product_metadata methods.

Test categories for US, UK, AU

Each row of the following table contains information about one test category, including the real production leaf category it represents, and three category IDs that can be used to work with the test category. For example, the "Category 1" test category (which mirrors production category 9355) has three category IDs: 178114, 178245, and 178376, each one in a different location in the category tree.

Test categories for CA

Each row of the following table contains information about one test category, including the real production leaf category it represents, and the category ID that can be used to work with the test category.