Package quantity currently unavailable and will most of the time be wrong anyways

[teddy-codes]

Re: amzn/selling-partner-api-models#1663

The issue above was created for all attributes, but I would like to go a step further to mention that the package quantity of an item most of the time is incorrect. The provided quantity will be 1 in the response from MWS, but in the title, it will specify a 2 pack. I know that this is due to how sellers list the item, but I would like it to be enforced as the field is currently quite useless.

I would also like to see the attributes of an item available to us developers for viewing when using the getCatalogItem api request.

[hoangtrucit]

We working to migrate from MWS, we have the same issue. Please help us. Thanks

[chapmanjw]

@teddy-codes You can get the available attributes for a given ASIN by its product type with the Product Type Definitions API. With the new Catalog and Listings APIs, the attributes data sections are intended to work hand-in-hand with the schemas from the Product Type Definitions API.

For a bit of background, the MWS Products API schema was basically a snapshot of how these attributes existed in 2010. As you've no doubt observed, those didn't evolve along with the actual catalog data (i.e. the attributes in XML product feeds have changed over time, but the MWS Products API responses haven't). While also not a perfect solution for all use-cases, the newer Catalog and Listings APIs do not explicitly model most attributes (mostly just the summary ones that are very unlikely to change) but rather relies on the Product Type Definitions API to provide these dynamically.

The package quantity issue is certainly an interesting one. :-) Doing a little deep diving, the intention of that attribute is to define the number of uniquely barcoded items being sold as one thing (like 1 box of 50 nails would be 1, but 5 boxes of 50 nails would be 5) to disambiguate ASINs with the same product identifiers, but different number of items included.

I can forward your feedback to the team that handles these validations, but I don't know when/if it would go anywhere beyond that.

[teddy-codes]

Honestly, this is something that we have just been living with and have no real way to validate it. The data is just flat out wrong most of the time... I wish that it was something that could be resolved easily, but that would require every seller on Amazon list the PROPER package quantity for the item which is still subjective as sellers use this to get an advantage and create another listing. I understand that Amazon is a playground, but there has to be a better way to deal with this.

In regards to the product type definitions api, what's the plan with this? It seems like a programming nightmare to handle different product type definitions when trying to retrieve basic product information. Do some sellers now not get the title attribute? seems weird.

[chapmanjw]

@teddy-codes The "basic" product information should be available in the summaries section with explicit API contract modeling. The definition of what "basic" product information is applicable does, however, change for different types of products. As such, we are looking to balance what is broadly applicable and stable (i.e. unlikely to change) vs. what is not broadly applicable across product types or more likely to change over time. As the Amazon catalog evolves, version bumps to the APIs themselves are disruptive to everyone, whereas using the Product Type Definitions API for those limits the blast radius of those disruptions and allows integrators to code around those changes.

This is not all that dissimilar to product XML feeds and XSDs where the Feeds API doesn't change, but the XSDs themselves do in defining the attributes. We certainly appreciate the pain points in the attributes data being fluid and the extra burden imposed by relying on schemas instead of a hard-coded API contract, as we face the same challenges as clients of our own systems. Your feedback on what falls into the "basic" information bucket has already shaped our near-term roadmap for these APIs.

Beyond these "building blocks" of attributes data and schemas, do you have ideas on how we can make this simpler for developers? Assuming these building blocks remain largely as-is (i.e. attributes that work with the schemas and the smaller set of summary data), is there something we could do around documentation, vended libraries/software, or something else to make integrating simpler?

[teddy-codes]

In my opinion, one JSON schema with a list of all attributes (with optionals being provided). This is similar to what we had previously in MWS with the products.xsd file.

The JSON schema would then only change by adding attributes and/or releasing an update to the api where there are two keys for now, but the previous key will be deprecated and/or both keys are removed. Now sure if you aware of the Stripe API, but they had done this.

[chapmanjw]

In my opinion, one JSON schema with a list of all attributes (with optionals being provided). This is similar to what we had previously in MWS with the products.xsd file.

The JSON schema would then only change by adding attributes and/or releasing an update to the api where there are two keys for now, but the previous key will be deprecated and/or both keys are removed. Now sure if you aware of the Stripe API, but they had done this.

Just to clarify, you are suggesting a single JSON Schema containing all possible attributes (not dependent on the product type) for use with reading from the Catalog Items API?

I think that is a great idea. That would certainly simplify general read use-cases for the Catalog Items APIs where the intention is not to roundtrip the data back to the Listings Items APIs.

I'll do some investigating to see what we'd need to make that happen and see if I can get it on our roadmap.

[teddy-codes]

Yea, that's what I am thinking.

One schema for all possible attributes for use only with the catalog API.

[chapmanjw]

@teddy-codes In my initial deep dive, the system that handles the content which powers the Definitions API does not currently have a mechanism to provide the data we need in aggregate, which just means its not a quick/easy thing to deliver. While getting this setup for programmatic access in an API may be a longer effort (probably not in 2022), I'm looking next at how we might do something scrappy and throw the schemas up on Github. If we can keep those relatively up-to-date (~monthly or ~quarterly), could be a stop-gap solution until available in an API. We'd want to avoid any "one-time" version of this since the Amazon catalog changes, frequently.

[chapmanjw]

@teddy-codes One other aspect we need to think through is localization. The MWS APIs didn't have any localization of schemas (display labels, etc.), but the Definitions APIs do. The primary use here is to allow applications to display localized attribute names and descriptions to end users in their own user interfaces. For the stop-gap version on Github, this would either mean one schema without localization, or one schema per locale (IIRC, we support ~13 languages and ~20 locales). For your use-case, would you use the localized content or just the structure (i.e. to generate code or whatever)?

[teddy-codes]

If the attribute names change based on locale: ie title is now título for es_MX, then we need the localized schemas. If not, the schema would look similar to the products.xsd file (just the structure) and we would use that. If we have to go the locale route, the only one we are looking for is en_US.

In regards to updating of the schema, having the updates to the schema be less frequent is fine, but there has to be a deprecation timeline of fields prior to removal for us to adapt our applications.

[chapmanjw]

@teddy-codes The attribute names themselves are always in English. The display labels for those attribute names are what get localized (so the same as the XSDs, but with labels).

As far as "graceful" changes to the attributes and product type definitions go, we are working on some of that this year. The intention there is to cover two aspects:

1. New attributes get added as optional along with an indicator of when they will become required (if they become required).
2. Replacement attributes (i.e., renaming and/or restructuring) coexist with their predecessors along with an indicator of when the old will be removed and which attribute is being replaced.

I do not know yet how these will manifest in the JSON Schemas as the JSON Schema specification has no vocabulary to describe this by default. This will most likely take the form of custom vocabulary (like we've done with selectors, hidden, and other "extra" information).

What would help us in these designs is getting the full picture of how various applications would react to these scenarios. What type of information (and in what form) would be needed for an application automate most of all of these attribute transitions? Is automation here needed or even desired? Or would making this information available in a form that integrators can take manual action be preferred?

Beyond the addition of new attributes, making optional attributes required, and replacing attributes in more graceful fashions, we would also like to simplify knowing what changed from version to version. Product type versions are "global", meaning any change to anything results in a version bump for all product types. One avenue to explore there is product type-specific versioning, but that comes with its own ramifications (i.e. you would need to track versioning at a PT-level, which is not ideal for some applications). The other avenue we are looking at is how to provide meaningful diffs and reporting of changes between versions globally (things like which PTs were impacted, classifying the types of changes, listing the impacted attributes). This, again, comes to what form would make this most useful and what actions would applications take with the information?

So many things to do :-). I need more engineers, know any? ;-)

[teddy-codes]

IMO, automation of this is overkill and can be an afterthought. A manual update should be the first step as any change to keys would require manual remapping/removal of attributes anyway.

For versioning, having one global version for all PTs is preferred. There has to be some kind of deprecation flow, though. The stripe documentation or github documentation do a good job at illustrating what I'm expecting as a consumer of the API. This would allow us (third-party developers) to raise any issues that we have while the attribute is still deprecated. I don't see the versioning of PTs having a fast-paced change history, but was just an example of what I've come across.

In terms of deprecation vocabulary, the spec can be found here. This was merged here.

PT-level versioning is going to be a mess to maintain, so let's not do that?

I think I know someone ;-)

[teddy-codes]

@chapmanjw I know that your team is working on a release for April (2022-04-01) of the catalogs API. Are these changes going to be available in that release?

[chapmanjw]

@teddy-codes Good news, we have released the v2022-04-01 version of the Catalog Items API: https://developer-docs.amazon.com/sp-api/docs/catalog-items-api-v2022-04-01-reference. This includes the package quantity and some other uniquely identifying attributes in the summaries along with a host of other changes.

[teddy-codes]

@chapmanjw Thanks for all the help getting these features added back into the API!

I look forward to experimenting with those changes.