Product aspects vs. item specifics

The getItemAspectsForCategory method in the Taxonomy API and the GetCategorySpecifics call in the Trading API will be updated for Phase 2 to start distinguishing between product aspects (defined in the catalog product) and item specifics (whose valuse can be 'manually' passed in by the seller). Only the item specifics that are returned in the responses of these two calls can be specified by the seller when listing/revising PBSE products. If a seller tries to pass in one or more product aspects (that are already defined in the catalog product) those product aspects will either be ignored or an error may occur. Additionally, a "max value length" field will be added to the responses of these two calls, indicating the maximum character limit of an item specific that is passed in by the seller. Previously, all item specifics had the same maximum character limit.

In the getItemAspectsForCategory response, the following fields will start being returned under the aspects.aspectConstraint container:

  • aspectApplicableTo: In the case of a product aspect, a value of PRODUCT will be returned for this field, and a seller will not be able to override this aspect's value. In the case of an instance aspect, a value of ITEM will be returned for this field, and a seller can set the value for this type of aspect.

  • aspectMaxLength: This integer value will state the maximum length of the aspect's value. The seller must make sure not to exceed this value when setting instance aspects on the listing. This field will only be returned for instance aspects.

In the GetCategorySpecifics response, the following fields will start being returned under the NameRecommendation.ValidationRules container:

  • AspectUsage: In the case of a product aspect, a value of Product will be returned for this field, and a seller will not be able to override this aspect's value. In the case of an instance aspect, a value of Instance will be returned for this field, and a seller can set the value for this type of aspect.

  • MaxValueLength: This integer value will state the maximum length of the aspect's value. The seller must make sure not to exceed this value when setting instance aspects on the listing. This field will only be returned for instance aspects.

In addition to the two new fields returned for the two calls, the following item specific fields will be added to help indicate and describe seller-created bundles and products with aftermarket modifications. All of these item specifics are considered instance aspects, and the seller will be allowed to pass these details into item specifics/aspects at listing/revision time:

  • Bundle Details: This field allows the seller to provide more information about a seller-created bundle.
  • Modified Product (boolean): This field allows the seller to state that the product has aftermarket modifications. For modified products, both this item specific and the 'Modification Details' item specific should be passed in.
  • Modification Details: This field allows the seller to provide more details about the modified product and the aftermarket modifications that have been made. For modified products, both this item specific and the 'Modification Product' boolean item specific should be passed in.

See the Associating catalog products to special listings Playbook topic for more information about creating bundle listings, lot listings, and modified products using some of these new item specific fields.