[BUG] Documentation - Incorrect content type

[sherlock270]

If you need help troubleshooting a problem with Selling Partner APIs, please open a support case. Issues are for reporting documentation bugs and enhancements only.

Describe the bug The incorrect content type is listed under "Consumes" for the patchListingsItem operation under the listings items api

URL of the content on GitHub https://github.com/amzn/selling-partner-api-docs/blob/main/references/listings-items-api/listingsItems_2020-09-01.md#consumes-3

Description of what the documentation currently says Documentation says the operation consumesapplication/json

Description of what the documentation should say Documentation should state the operation consumes application/json-patch+json per IETF

Additional context The operation returns an InvalidInput error when using application/json content type. The operation works correctly when using the application/json-patch+json content type

[johnkw]

I'm not seeing any behavior difference between application/json and application/json-patch+json. Is it possible this was fixed to allow both? Or are you just saying the SP-API is not currently in compliance with the RFC's recommendation?

In any case though, both fail with "Invalid path provided in patch at index of 0." because I have no idea what to use for a "path". Bizarrely "path" is undocumented other than a link to a definition of how a path generically is formatted.

See also bug amzn/selling-partner-api-models#395 for the more general lack of documentation, including the lack of documentation for "path".

[chapmanjw]

@sherlock270 From a REST purity perspective, I totally agree that the content-type for the PATCH operation should be application/json-patch+json. There are some technical limitations that resulted in using application/json reference. It's possible that application/json-patch+json is being ignored if it happens to be working.

As @johnkw mentioned, we do need better documentation and better links to the documentation we have. For example, the use case guide shows an example of a PATCH request to the Listings API: https://github.com/amzn/selling-partner-api-docs/blob/main/guides/en-US/use-case-guides/listings-items-api-use-case-guide/listings-items-api-use-case-guide_2020-09-01.md#step-1-submit-listings-item-patch-request.

The JSON pointer path is formatted as /attributes/ + the name of the attribute being updated. The value follows the structure of the attribute as defined by the Product Type Definitions API.

{
  "productType":"LUGGAGE",
  "patches":[
    {
      "op":"replace",
      "path":"/attributes/item_name",
      "value":[
        {
          "value": "AmazonBasics 16\" Underseat Spinner Carry-On",
          "language_tag": "en_US",
          "marketplace_id": "ATVPDKIKX0DER"
        }
      ]
    },
    {
      "op":"replace",
      "path":"/attributes/purchasable_offer",
      "value":[
        {
          "marketplace_id": "ATVPDKIKX0DER",
          "currency": "USD",
          "our_price": [
            {
              "schedule": [
                {
                  "value_with_tax": 15.00
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "op":"delete",
      "path":"/attributes/item_type_name",
      "value":[
        {
          "marketplace_id": "ATVPDKIKX0DER",
          "language_tag": "en_US"
        }
      ]
    }
  ]
}

[johnkw]

Thanks. It's good to see someone at least looking at these issues. There are so many bugs open right now it sometimes feels hopeless looking at these APIs.

If it's really true that path is just the attribute name, with the string /attributes/ prepended to it, then why not just remove the superfluous /attributes/ from every input, and rename the path field to attribute_name? Then it would be immediately obvious what it actually is, instead of path which is hopelessly vague and confusing.

It seems like this was an attempt to copy RFC 6902, except that it wasn't copied entirely as the original OP points out, and it's not really a good use of RFC 6902, so attempting to use RFC 6902 just makes the API more complicated with no value add.

Also, what is the logical meaning of specifying op as delete but then also specifying a value field? It seems like value cannot possibly be used if the field is being deleted... or at least my imagination fails me for what possible purpose that could have.

[chapmanjw]

@johnkw Great questions. :-)

On the path, /attributes/ is optional. Both /attributes/item_name and /item_name will work. Since the object model of the Listings Items resource puts all of the properties within the attributes property, the path here is meant to represent the path on that resource (so /attributes/ would be more precise).

The JSON Patch modeling used here is a subset of the RFC specification. Not all of the specification is applicable to the use case here, but using this style of modeling was preferable (in my opinion) to making up our own.

The delete case here is interesting. When you look at the JSON Schema from the Product Type Definitions API, you'll note that every attribute is an array and each attribute has selectors (like fulfillment_availability with fulfillment_channel_code). In order to actually delete an instance of an attribute, we need to know which one to delete. There is no particular ordering to the arrays for attributes with multiple instances in the array, so the standard JSON Pointer delete on /attributes/fulfillment_availability/0 doesn't work. In order to delete the right instance, we need to know the selector values (i.e. which fulfillment_channel_code). There were two options we considered (and are potentially still on the table for a future iteration, which your feedback can help with):

1. Keep JSON Pointers, but put the selectors in the value. This is ultimately what we chose for this first iteration. It doesn't change the meaning of the path as defined by the RFC spec, but is not free of being slightly weird.
2. Use JSON Path instead of JSON Pointers. Departing from the RFC spec, we could have used JSON Path where we put the selectors in the path (something like $.attributes.fulfillment_availability[@_.fulfillment_channel_code=BLAH]).

With this in mind, however, our initial release is limited to "whole" attributes (meaning you cannot patch deeper than the top-level attribute and you have to provide the whole attribute). We would like to extend this to "granular" patching where you can patch any field within an attribute. With the selectors, we cannot do that with JSON Pointers. So, we may end up adding support for JSON Path in a future iteration (probably accept both versions for backwards compatibility, since we can easily disambiguate between the two).

Would love your feedback on how we might make this patch operation better in supporting granular patching but also working within the constraints of having to handle selectors.

[johnkw]

Is that only because of marketplace_id? Wait is "marketplace_id": "ATVPDKIKX0DER" part of the definition of what is being updated, but is itself immutable?

[chapmanjw]

marketplace_id is one of the selectors (as these APIs are modeled to support multi-marketplace submissions, which we will enable in the future). Additionally, language_tag is a common selector for textual attributes.

[johnkw]

Honestly this section of the API is incredibly confusing, but thanks for the responses, as it's getting a little more clear what's going here. So SKU is part of the API URL, so, for a given call you can only possibly update 1 SKU ever? But you're allowed to update multiple marketplace_id within the same call? And marketplace_id is an always-required parameter for every single operation?

Why not just make the path parameter just be /SellerID/SKU/marketplace/attribute? Or better yet, don't make it a path at all, but just have every operation have 4 required fields as inputs? (My opinion is that trying to shoehorn this patch RFC into this Amazon situation is just adding to the confusion.)

[Real-dev-byte]

@johnkw @chapmanjw @sherlock270 Using asin name i am using getCatalog to get further details. For patch operation in listings api I am making following assumptions. Please let me know if they are incorrect. SellerID : used manufacturerCode in vendorDetails in getCatalog response productType : used productType in productTypes in getCatalog response SKU : used modelNumber/GTIN/UPC/EAN (whichever present) in getCatalog response

[steven-so]

@chapmanjw @johnkw

Does anyone know what the body supposed to look like when using the patchListingsItem operation to change an image? I'm confused on exactly what I need to provide.

[johnkw]

I haven't tried the scary PATCH stuff, but they finally added GET as per https://github.com/amzn/selling-partner-api-docs/blob/main/references/listings-items-api/listingsItems_2021-08-01.md so you can at least see some of what is available. Strangely it appears the vast majority of fields are not available via the API - it only has the basics. Category specific things like size, color, type are all missing it seems.

[steven-so]

I haven't tried the scary PATCH stuff, but they finally added GET as per https://github.com/amzn/selling-partner-api-docs/blob/main/references/listings-items-api/listingsItems_2021-08-01.md so you can at least see some of what is available. Strangely it appears the vast majority of fields are not available via the API - it only has the basics. Category specific things like size, color, type are all missing it seems.

Yeah it seems like a lot of stuff is missing from the ListingsItemsApi I eventually figured out a way to change images, but I had to use the Feeds API.

[chapmanjw]

For a bit of context here, the Listings APIs are dependent upon migrating product type definitions to support the APIs. Product types themselves are hierarchal with the PRODUCT product type being the root of all other product types. You can refer to the search operation on the Product Type Definitions API to list all of the product types currently migrated: https://github.com/amzn/selling-partner-api-docs/blob/main/guides/en-US/use-case-guides/product-type-definitions-api-use-case-guide/definitions-product-types-api-use-case-guide_2020-09-01.md.

For listings with product types that have been migrated, you can read and write all of the attributes associated with that type of item. However, for listings with product types not yet migrated, you are limited to reading and editing attributes on the root PRODUCT product type.

With the Listings APIs, we are iteratively bringing as much functionality to you as quickly as it's available instead of waiting until all product types have migrated worldwide. We are aware that this does not work for all use-cases. As such, XML-based listings feeds with the Feeds API may be a better fit for use-cases that need to cover all available product types worldwide right now.

Mixing and matching XML-feeds and Listings APIs is also supported. For example, you could use the XML product feeds to create and update product facts, but transition to using the Listings APIs for pricing and inventory data.

[AbePerl1]

Ok I will try that, BTW the documentation does not mention on how to migrate a listing

On Tue, Dec 14, 2021 at 2:49 PM John Chapman @.) < @.> wrote:

For a bit of context here, the Listings APIs are dependent upon migrating product type definitions to support the APIs. Product types themselves are hierarchal with the PRODUCT product type being the root of all other product types. You can refer to the search operation on the Product Type Definitions API to list all of the product types currently migrated: https://github.com/amzn/selling-partner-api-docs/blob/main/guides/en-US/use-case-guides/product-type-definitions-api-use-case-guide/definitions-product-types-api-use-case-guide_2020-09-01.md .

For listings with product types that have been migrated, you can read and write all of the attributes associated with that type of item. However, for listings with product types not yet migrated, you are limited to reading and editing attributes on the root PRODUCT product type.

With the Listings APIs, we are iteratively bringing as much functionality to you as quickly as it's available instead of waiting until all product types have migrated worldwide. We are aware that this does not work for all use-cases. As such, XML-based listings feeds with the Feeds API may be a better fit for use-cases that need to cover all available product types worldwide right now.

Mixing and matching XML-feeds and Listings APIs is also supported. For example, you could use the XML product feeds to create and update product facts, but transition to using the Listings APIs for pricing and inventory data.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/amzn/selling-partner-api-models/issues/392, or unsubscribe https://github.com/notifications/unsubscribe-auth/ADZDNV6F3XMORYGBB76QUGLUQ6NTRANCNFSM466JSQTA . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

--

<img src=" https://s3.amazonaws.com/rkjha/signature-maker/img/male-icon.png" id="sigPhoto" height="65px" width="65px">

<div style="margin-top:0px; margin-left: 74px;" id="sigDetailsWrapper"> <p style="font-family: Helvetica, sans-serif; font-size: 12px; line-height: 14px; color: amzn/selling-partner-api-models#980; margin-top:0; margin-left:0; padding-left:0;"> Abe Perl / Software Developer
<a @." id="sigEmail" @. <span id="sigMobile">/ 8453674186

<span id="sigCompany">fine tech Solutions
<a href=" http://example.com" id="sigWebsite" style="color:#428BCA;" rel="nofollow">

<img src=" https://s3.amazonaws.com/rkjha/signature-maker/icons/twitter_circle_color-20.png" height="20px" width="20px"> <span style="display: none;" id="facebookIcon"><img src=" https://s3.amazonaws.com/rkjha/signature-maker/icons/facebook_circle_color-20.png" height="20px" width="20px"> <span style="display: none;" id="gplusIcon"><img src=" https://s3.amazonaws.com/rkjha/signature-maker/icons/google_circle_color-20.png" height="20px" width="20px"> <span style="display: none;" id="linkedinIcon"><img src=" https://s3.amazonaws.com/rkjha/signature-maker/icons/linkedin_circle_color-20.png" height="20px" width="20px"> <span style="display: none;" id="instagramIcon"><img src=" https://s3.amazonaws.com/rkjha/signature-maker/icons/instagram_circle_color-20.png" height="20px" width="20px"> <span style="display: none;" id="dribbleIcon"><img src=" https://s3.amazonaws.com/rkjha/signature-maker/icons/dribbble_circle_color-20.png" height="20px" width="20px"> <span style="display: none;" id="youtubeIcon"><img src=" https://s3.amazonaws.com/rkjha/signature-maker/icons/youtube_circle_color-20.png" height="20px" width="20px"> <span style="display: none;" id="vimeoIcon"><img src=" https://s3.amazonaws.com/rkjha/signature-maker/icons/vimeo_circle_color-20.png" height="20px" width="20px"> <span style="display: none;" id="githubIcon"><img src=" https://s3.amazonaws.com/rkjha/signature-maker/icons/github_circle_black-20.png" height="20px" width="20px"> <span style="display: none;" id="blogIcon"><img src=" https://s3.amazonaws.com/rkjha/signature-maker/icons/wordpress_circle_color-20.png" height="20px" width="20px">
<a href=" http://signature-maker.net/email-signature?utm_source=generatedSig&amp;utm_medium=email&amp;utm_campaign=emailLink" style="opacity:0.4;color:#333;font-size:9px;">Get your own signature

[chapmanjw]

@AbePerl1 Whether listings are submitted through Listings APIs or XML feeds, etc., they are all the same listings in the end. They have some differences in how the data is represented (like APIs using item_name, but some feeds use title, they are both representing item_name in the catalog). As product types are migrated to the APIs, the listings that can be fully managed with the APIs expands. This does not mean, however, that you cannot keep managing those listings with XML feeds once you start using the Listings APIs at this time.

We will provide additional guidance and documentation on the migration process as the use-cases covered by the APIs expand. Right now, the use-case guides provide an overview of what is currently supported.

[AbePerl1]

@chapmanjw I tried the path many times now. It works on certain fields like the pricing and MSRP, pesticide info. However, on fields that can have an array of items like you mentioned before i.e. the item name, it does not work right. I was able to add an item name, however, I wasn't able to replace an existing item name or remove it, I was only able to remove an item name that I added but not the original.

I would appreciate it if you can help me with this issue.

Respectfully, Abe Perl

[johnkw]

I don't think this is all even close to working yet. You should stick to using the Feed updates for now.

Also I'd really advise to Amazon abandoning that PATCH RFC stuff and just using application-specific API fields for everything.

[chapmanjw]

@AbePerl1 Following the examples above (and assuming that you did not receive validation errors in your API response), you would have successfully submitted your contribution for item_name. However, that is not a guarantee that you will win reconciliation and affect the title on the detail page (someone else's contribution may be winning reconciliation there). For your specific issues, I would recommend contacting developer support so that we can dive into your specific API requests further.

[github-actions[bot]]

This is a very old issue that is probably not getting as much attention as it deserves. We encourage you to check if this is still an issue after the latest release and if you find that this is still a problem, please feel free to open a new issue and make a reference to this one.

[johnkw]

I still haven't tried to use this. The feeds still seem the safer choice. This is probably not fixed, but the documentation is now at: https://developer-docs.amazon.com/sp-api/docs/product-type-api-use-case-guide

[AbePerl1]

Feed is also not good. Amazon added lately a new thing that we need to specify the product type, and if the type is with apparel or shirt or pants, etc.. we need to specify body type /height type. These fields are totally conflicting with the rules and I am validating it with the schema however while posting new items I sit in a loop due to conflicting validation rules, one rule says: "add body type" according to the validation, so I am adding it, then I re-validate the next rule says "expected 0" then I remove it, and I am going around the pond with that. The same happens when i upload a feed

[johnkw]

See also bug amzn/selling-partner-api-models#2531.

[github-actions[bot]]

This is a very old issue that is probably not getting as much attention as it deserves. We encourage you to check if this is still an issue after the latest release and if you find that this is still a problem, please feel free to open a new issue and make a reference to this one.

[johnkw]

Unless there was a massive overhaul, this is still an issue.

[github-actions[bot]]

This is a very old issue that is probably not getting as much attention as it deserves. We encourage you to check if this is still an issue after the latest release and if you find that this is still a problem, please feel free to open a new issue and make a reference to this one.

[johnkw]

Still needs a lot of work.

[shreeharsh-a]

Thank you for bringing this up. We have noted & forwarded this to the relevant team for review & action.

Note: SP API or docs related issues / troubleshooting support is managed by a different team. We can help if the issue is related to the content published on this repo.

[johnkw]

It's great that the SPAPI team has been informed of this bug report. However it would be helpful to leave the bug open until it's fixed, so people know where to look for information on this bug.