Migrating Listings Management Workflows

This guide explains how to migrate listings management workflows from XML and flat file listings submissions to the Listings Items API and JSON_LISTINGS_FEED. This is necessary to prepare for the deprecation of legacy feed types.

Review the Building Listing Management Workflows Guide prior to this migration guide.

Benefits

The guidance offered here describes the following benefits for both sellers and vendors:

• Full data requirements in product schemas
• Availability of pre-submission validation rules
• Sync and async feedback mechanisms
• Up-to-date product type data requirements that ensure you are using the latest version, unlike XMLs
• Uniformity in schemas across data requirements, unlike XML in the past that led to errors for developers uploading multiple categories
• Reducing the effort required to map flat file or XML attributes to Listings APIs and the JSON_LISTINGS_FEED.
• Reducing human/manual input errors leading to submission errors and abandoned selections
• Easier management of large catalogs and sending of full selections with no upload constraints

API versions

This guide references operations in the following Selling Partner API sections. For more detailed information about building workflows using these sections, see the Building Listings Management Workflows Guide. For more detailed information about the individual API sections, follow the referenced links.

Feed types

This guide references the following feed types used with the Feeds API. For more detailed information about feed types, see Listings Feed Type Values.

Terminology

• JSON Schema: JSON is the serialization format used by the APIs, notifications, and feed formats described in this guide. JSON Schema is a vocabulary for annotating, describing, and validating JSON content and is used by the Product Type Definitions API to describe the data model for Catalog Items and Listings Items. Refer to http://json-schema.org/learn/ for more details about JSON Schema.
• JSON_LISTINGS_FEED: The JSON_LISTINGS_FEED is a bulk feed format contractually compatible with the Listings Items API and is interchangeable with the individual Listings Items API operations.
• XML Schema (XSD): XML is the serialization format used by some listings feed types (for example, POST_PRODUCT_DATA). XML Schema (XSD) is the specification for describing and validating XML content. Refer to https://www.w3.org/XML/Schema for more details about XML Schema (XSD).
• Category XSDs: Category XSDs define the category-specific data modeling for POST_PRODUCT_DATA XML feed submissions.
• Listings Item: Represents an item (that is, a listing) in a selling partner catalog that is uniquely identified by a selling partner-provided SKU (Stock Keeping Unit) and represents the product facts and sales terms for an item sold on or fulfilled by Amazon.
• Variation Family: A variation family is a collection of similar items that vary by color, size, or other attributes used to provide a single detail page experience for buyers on Amazon. For example, a clothing article may come in multiple colors, multiple sizes, and multiple styles. Each unique combination of color, size, and style is represented by a separate item in the variation family.
• FBA: (Fulfilled by Amazon) Items sold on Amazon are fulfilled by Amazon.
• MFN: (Merchant Fulfillment Network) Items sold on Amazon fulfilled by the seller.

Migration strategies

The steps necessary to migrate your listings workflow are unique to your use-case and business needs. This section outlines additional considerations that may aid you in defining a migration strategy that is minimally impactful and takes advantage of new features iteratively.

Mapping product attributes from category XSDs (XML) and flat file feed types

Data elements in the Listings Items API and JSON_LISTINGS_FEED are structured and, in some cases, named differently from how those data elements are structured and named in XML and flat file feed types. The updated data elements are a more direct representation of the data modeling of Amazon’s catalog, expanding support for features not previously available with legacy feed types and enabling consistency with the latest requirements of the Amazon catalog. The mapping of data elements for inventory, pricing, images, shipping, and variation relationships are outlined in this guide in the sections below. However, for product data (for example: item names, bullet points, and other relevant attributes), there are thousands of mappings from legacy XML and flat file feed types. To aid in migration of product attributes, the following files provide mappings from the product data elements from legacy XML and flat file feed types to the corresponding data elements in the Listings Items API and JSON_LISTINGS_FEED.

• Product XML (Category XSD) Mappings: https://m.media-amazon.com/images/G/01/VSSC/XPath-To-JSON-mappings.xlsx
• Product Flat File Mappings: https://m.media-amazon.com/images/G/01/VSSC/FlatFile-To-JSON-Mapping.xlsx

The mappings in these files are limited to product-related attributes (that is, they do not include inventory or pricing) and do not include the product type or marketplace-specific relevancy of each. The Product Type Definitions API provides JSON Schemas that represent the applicable attributes and constraints per product type and marketplace. Using the mapping files in conjunction with the JSON Schemas will let you to update your data mappings, identify which mappings are relevant for each product type and marketplace, identify data elements no longer relevant, and identify new relevant data elements.

Iterative workflow migrations

Listings management workflows are often a complex combination of use-cases and business logic unique to each selling partner that are built around the specific capabilities of individual listings tools (for example, Category XSDs). With previous XML feed submissions, listings workflows were forced to handle product, pricing, inventory, and other data separately, whether or not that pattern fit the use-case and business logic for individual selling partners. With the Listings Items API and JSON_LISTINGS_FEED, this type of workflow pattern is supported while providing flexibility to build workflows that more closely match the use-case and business logic for individual selling partners.

The flexibility provided by the Listings Items API and JSON_LISTINGS_FEED allows an iterative approach to migrating portions of listings management workflows without having to migrate everything at once. Taking a phased approach allows you to refactor, test, iterate, and migrate smaller portions of your workflow, reducing the overall impact these changes have on your business workflows at each stage in your migration. Below are suggested areas to consider when approaching migration in an iterative fashion.

Data types

Creating and managing product data in listings workflows is complex because the data model and constraints vary between marketplaces and product types. For most use-cases, updating inventory, pricing, and images are the least complex.

To iteratively approach migrating listings workflows, break down the migration by data type (for example, inventory, pricing, images). This allows you to start with the least complex data elements and leave the most complex (that is, product data) last.

For example, migrate your pricing and inventory workflows first. This way, you build your initial integrations by migrating the data elements that can be statically mapped from an XML-based workflow to a Listings Items API or JSON_LISTINGS_FEED-based workflow. As you expand your migration to incorporate each data type, you can choose to maintain isolation between the handling of each data type or refactor to consolidate the handling of different data types.

Onboarding to new API and notification features

You can begin to employ new Selling Partner API and notification features that work alongside your existing XML or flat file feeds-based workflow. By doing so early in your migration, you can take advantage of the following features:

• Listings Items API (getListingsItem) - The getListingsItem operation of the Listings Items API returns the current status, issues, and other data associated with a listing, including listings created with other tools. For existing listings, this operation returns the previously submitted data in the format used for Listings Items API and JSON_LISTINGS_FEED submissions.
• Listings Restrictions API - The Listings Restrictions API provides eligibility details for selling partners creating offers on items in the Amazon catalog. This API allows you to verify eligibility requirements for a selling partner prior to spending time or effort on the offer creation process.
• LISTINGS_ITEM_ISSUES_CHANGE Notifications - You can subscribe to the LISTINGS_ITEM_ISSUES_CHANGE notification to recieve a notification when issues are added or cleared on selling partner listings. You can then use the Listings Items API to retrieve the latest status and issues for a listing.
• LISTINGS_ITEM_STATUS_CHANGE Notifications - You can subscibre to the LISTINGS_ITEM_STATUS_CHANGE notification to recieve a notification whenever the buyability status changes on selling partner listings. You can then use the Listings Items API to retrieve the latest status and issues for a listing.

Offer-only workflows

Listings management workflows that manage offer-only listings are less complex than workflows managing listings with product data. Offer-only listings refers to listings with sales terms (inventory and pricing) on existing items in the Amazon catalog. Another iterative approach is migrating offer-only listings workflows prior to migrating listings that include product data. For more details on creating offer-only listings with the Listings Items API and JSON_LISTINGS_FEED submissions, see the List an offer for an item that already exists in the Amazon catalog tutorial in the Building Listings Management Workflows Guide.

Product types and marketplaces

The data model and constraints for managing listings with product data differ by product type and marketplace. Category XSDs define these data models at a category level, while the Product Type Definitions API defines these at the individual product type. With the migration of product data being the most complex portion of migrating listings workflows for most use-cases, an iterative approach by category, product type, and marketplace allows you to configure data mappings, test submissions, and iterate more rapidly on smaller amounts of data, rather than configuring everything at once.

🚧

There is not yet support for all product types in all marketplaces

The Listings Items API and JSON_LISTINGS_FEED do not yet support all product types in all marketplaces. An iterative approach by product type and marketplace allows you to begin migrating and iteratively adopt product types in these tools as they become available.

Migrating product feeds workflows

With previous XML feed submissions (POST_PRODUCT_DATA), product data was always submitted separately from other listings data elements (pricing, inventory, images, shipping, and relationships). The data model for these submissions was derived using Category XSD (downloaded from Seller Central) and Product.xsd XML schemas.

With the Listings Items API and JSON_LISTINGS_FEED, product data may be submitted alongside all other listings elements (for example, when creating a listing with all data elements in a single submission) or by itself (product-only updates). With thousands of attribute mappings, this guide does not list each mapping as it does for other data elements. See the Mapping product attributes from category XSDs (XML) and flat file feed types section for files containing the full set of mappings for product data. This section outlines examples before and after migration.

Submitting product data

Product XML feeds always handled product updates separately from other listings data elements (inventory, pricing, etc.). With the Listings Items API and JSON_LISTINGS_FEED, product data may be submitted by itself or alongside other listings data elements. The examples below illustrate the submission of product data for both scenarios.

Previous XML Submission

<AmazonEnvelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="amzn-envelope.xsd">
  <Header>
    <DocumentVersion>1.01</DocumentVersion>
    <MerchantIdentifier>AXXXXXXXXXXXXX</MerchantIdentifier>
  </Header>
  <MessageType>Product</MessageType>
  <Message>
    <MessageID>1</MessageID>
    <OperationType>Update</OperationType>
    <Product>
      <SKU>ABC123</SKU>
      <StandardProductID>
        <Type>ASIN</Type>
        <Value>BXXXXXXXXX</Value>
      </StandardProductID>
      <Condition>
        <ConditionType>New</ConditionType>
      </Condition>
      <DescriptionData>
        <Title>MyBrand Carry-On Luggage</Title>
        <Brand>MyBrand</Brand>
      </DescriptionData>
      <ProductData>
        <Luggage>
          <ProductType>Luggage</ProductType>
          <Color>Red</Color>
        </Luggage>
      </ProductData>
    </Product>
  </Message>
</AmazonEnvelope>

New Listings Items API submission when creating a listing with other data elements

PUT https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXXX/ABC123
  ?marketplaceIds=ATVPDKIKX0DER
  &issueLocale=en_US

{
  "productType": "LUGGAGE",
  "requirements": "LISTING",
  "attributes": {
    "condition_type": [
      {
        "value": "new_new",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "merchant_suggested_asin": [
      {
        "value": "BXXXXXXXXX",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "item_name": [
      {
        "value": "MyBrand Carry-On Luggage",
        "language_tag": "en_US",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "brand": [
      {
        "value": "MyBrand",
        "language_tag": "en_US",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "color": [
      {
        "value": "Red",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "main_product_image_locator": [
      {
         "media_location": "https://example/main.jpg",
         "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    ... (more attributes, if applicable)
  }
}

New Listings Items API submission when updating product only

PATCH https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXXX/ABC123
  ?marketplaceIds=ATVPDKIKX0DER
  &issueLocale=en_US

{
  "productType": "LUGGAGE",
  "patches": [
    {
      "op": "replace",
      "path": "/attributes/item_name",
      "value": [
        {
          "value": "MyBrand Carry-On Luggage",
          "language_tag": "en_US",
          "marketplace_id": "ATVPDKIKX0DER"
        }
      ]
    },
    ... (more patches, if applicable)
  ]
}

New JSON_LISTINGS_FEED submission when creating a listing with other data elements

{
  "header": {
    "sellerId": "AXXXXXXXXXXXXX",
    "version": "2.0",
    "issueLocale": "en_US"
  },
  "messages": [
    {
      "messageId": 1,
      "sku": "ABC123",
      "operationType": "UPDATE",
      "productType": "LUGGAGE",
      "requirements": "LISTING",
      "attributes": {
        "condition_type": [
          {
            "value": "new_new",
            "marketplace_id": "ATVPDKIKX0DER"
          }
        ],
        "merchant_suggested_asin": [
          {
            "value": "BXXXXXXXXX",
            "marketplace_id": "ATVPDKIKX0DER"
          }
        ],
        "item_name": [
          {
            "value": "MyBrand Carry-On Luggage",
            "language_tag": "en_US",
            "marketplace_id": "ATVPDKIKX0DER"
          }
        ],
        "brand": [
          {
            "value": "MyBrand",
            "language_tag": "en_US",
            "marketplace_id": "ATVPDKIKX0DER"
          }
        ],
        "color": [
          {
            "value": "Red",
            "marketplace_id": "ATVPDKIKX0DER"
          }
        ],
        "main_product_image_locator": [
          {
            "media_location": "https://example/main.jpg",
            "marketplace_id": "ATVPDKIKX0DER"
          }
        ],
        ... (more attributes, if applicable)
      }
    },
    ... (more messages, if applicable)
  ]
}

New JSON_LISTINGS_FEED submission when updating product only

{
  "header": {
    "sellerId": "AXXXXXXXXXXXXX",
    "version": "2.0",
    "issueLocale": "en_US"
  },
  "messages": [
    {
      "messageId": 1,
      "sku": "ABC123",
      "operationType": "PATCH",
      "productType": "LUGGAGE",
      "patches": [
        {
          "op": "replace",
          "path": "/attributes/item_name",
          "value": [
            {
              "value": "MyBrand Carry-On Luggage",
              "language_tag": "en_US",
              "marketplace_id": "ATVPDKIKX0DER"
            }
          ]
        },
        ... (more patches, if applicable)
      ]
    },
    ... (more messages, if applicable)
  ]
}

Migrating inventory feeds workflows

With previous XML feed submissions (POST_INVENTORY_AVAILABILITY_DATA), inventory data was always submitted separately from product and other listings data elements. With the Listings Items API and JSON_LISTINGS_FEED, inventory data may be submitted alongside all other listings data elements (for example, when creating a listing with all data elements in a single submission) or by itself (inventory-only updates). This section outlines the data mappings from the legacy XML feed schema (Inventory.xsd) along with examples before and after migration.

While some product types are not yet available for the Listings Items API and JSON_LISTINGS_FEED, inventory data may be submitted for any listings item regardless of its product type. This allows inventory-only workflows to migrate entirely to the Listings Items API and JSON_LISTINGS_FEED.

Data mappings

The table below provides a mapping of XML element by XPath to JSON element by JSON Pointer for inventory data.

Submitting inventory data

Inventory XML feeds always handled inventory updates separately from other listings data elements (product, pricing, etc.). With the Listings Items API and JSON_LISTINGS_FEED, inventory data may be submitted by itself or alongside other listings data elements. The examples below illustrate the submission of inventory data for both scenarios.

Previous XML Submission for MFN Quantity

<AmazonEnvelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="amznenvelope.xsd">
  <Header>
    <DocumentVersion>1.01</DocumentVersion>
    <MerchantIdentifier>AXXXXXXXXXXXXX</MerchantIdentifier>
  </Header>
  <MessageType>Inventory</MessageType>
  <Message>
    <MessageID>1</MessageID>
    <OperationType>Update</OperationType>
    <Inventory>
      <SKU>ABC123</SKU>
      <FulfillmentCenterID>DEFAULT</FulfillmentCenterID>
      <Quantity>5</Quantity>
    </Inventory>
  </Message>
</AmazonEnvelope>

New Listings Items API submission when creating an offer-only listing with other data elements

PUT https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXXX/ABC123
  ?marketplaceIds=ATVPDKIKX0DER
  &issueLocale=en_US

{
  "productType": "PRODUCT",
  "requirements": "LISTING_OFFER_ONLY",
  "attributes": {
    "condition_type": [
      {
        "value": "new_new",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "merchant_suggested_asin": [
      {
        "value": "BXXXXXXXXX",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "fulfillment_availability": [
      {
         "fulfillment_channel_code": "DEFAULT",
         "quantity": 5
      }
    ],
    ... (more attributes, if applicable)
  }
}

New Listings Items API submission when updating inventory only

PATCH https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXXX/ABC123
  ?marketplaceIds=ATVPDKIKX0DER
  &issueLocale=en_US

{
  "productType": "PRODUCT",
  "patches": [
    {
      "op": "replace",
      "path": "/attributes/fulfillment_availability",
      "value": [
        {
          "fulfillment_channel_code": "DEFAULT",
          "quantity": 5
        }
      ]
    },
    ... (more patches, if applicable)
  ]
}

New JSON_LISTINGS_FEED submission when creating an offer-only listing with other data elements

{
  "header": {
    "sellerId": "AXXXXXXXXXXXXX",
    "version": "2.0",
    "issueLocale": "en_US"
  },
  "messages": [
    {
      "messageId": 1,
      "sku": "ABC123",
      "operationType": "UPDATE",
      "productType": "PRODUCT",
      `"requirements"`: `"LISTING_OFFER_ONLY"`,
      "attributes": {
        "condition_type": [
          {
            "value": "new_new",
            "marketplace_id": "ATVPDKIKX0DER"
          }
        ],
        "merchant_suggested_asin": [
          {
            "value": "BXXXXXXXXX",
            "marketplace_id": "ATVPDKIKX0DER"
          }
        ],
        "fulfillment_availability": [
          {
            "fulfillment_channel_code": "DEFAULT",
            "quantity": 5
          }
        ],
        ... (more attributes, if applicable)
      }
    },
    ... (more messages, if applicable)
  ]
}

New JSON_LISTINGS_FEED submission when updating inventory only

{
  "header": {
    "sellerId": "AXXXXXXXXXXXXX",
    "version": "2.0",
    "issueLocale": "en_US"
  },
  "messages": [
    {
      "messageId": 1,
      "sku": "ABC123",
      "operationType": "PATCH",
      "productType": "PRODUCT",
      "patches": [
        {
          "op": "replace",
          "path": "/attributes/fulfillment_availability",
          "value": [
            {
              "fulfillment_channel_code": "DEFAULT",
              "quantity": 5
            }
          ]
        },
        ... (more patches, if applicable)
      ]
    },
    ... (more messages, if applicable)
  ]
}

SwitchFulfillmentTo (convert between MFN and FBA)

Inventory XML feeds support switching between MFN and FBA fulfillment for a listings item. With the Listings Items API and JSON_LISTINGS_FEED, the same result may be achieved by patching an item to explicitly add one and explicitly delete the other. The examples below illustrate the switch from FBA to MFN.

Previous XML submission switching from FBA to MFN

<AmazonEnvelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="amznenvelope.xsd">
  <Header>
    <DocumentVersion>1.01</DocumentVersion>
    <MerchantIdentifier>AXXXXXXXXXXXXX</MerchantIdentifier>
  </Header>
  <MessageType>Inventory</MessageType>
  <Message>
    <MessageID>1</MessageID>
    <OperationType>Update</OperationType>
    <Inventory>
      <SKU>ABC123</SKU>
      <FulfillmentCenterID>DEFAULT</FulfillmentCenterID>
      <Quantity>5</Quantity>
      <SwitchFulfillmentTo>MFN</SwitchFulfillmentTo>
    </Inventory>
  </Message>
</AmazonEnvelope>

New Listings Items API submission switching from FBA to MFN

PATCH https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXXX/ABC123
  ?marketplaceIds=ATVPDKIKX0DER
  &issueLocale=en_US

{
  "productType": "PRODUCT",
  "patches": [
    {
      "op": "add",
      "path": "/attributes/fulfillment_availability",
      "value": [
        {
          "fulfillment_channel_code": "DEFAULT",
          "quantity": 5
        }
      ]
    },
    {
      "op": "delete",
      "path": "/attributes/fulfillment_availability",
      "value": [
        {
          "fulfillment_channel_code": "AMAZON_NA"
        }
      ]
    }
  ]
}

New JSON_LISTINGS_FEED submission from FBA to MFN

{
  "header": {
    "sellerId": "AXXXXXXXXXXXXX",
    "version": "2.0",
    "issueLocale": "en_US"
  },
  "messages": [
    {
      "messageId": 1,
      "sku": "ABC123",
      "operationType": "PATCH",
      "productType": "PRODUCT",
      "patches": [
        {
          "op": "add",
          "path": "/attributes/fulfillment_availability",
          "value": [
            {
              "fulfillment_channel_code": "DEFAULT",
              "quantity": 5
            }
          ]
        },
        {
          "op": "delete",
          "path": "/attributes/fulfillment_availability",
          "value": [
            {
              "fulfillment_channel_code": "AMAZON_NA"
            }
          ]
        }
      ]
    }
  ]
}

Migrating pricing feeds workflows

With previous XML feed submissions (POST_PRODUCT_PRICING_DATA), pricing data was always submitted separately from product and other listings data elements. With the Listings Items API and JSON_LISTINGS_FEED, pricing data may be submitted alongside all other listings data elements (For example, creating a listing with all data elements in a single submission) or by itself (for example, pricing-only updates). This section outlines the data mappings from the legacy XML feed schema (Price.xsd) along with examples before and after migration.

🚧

B2B pricing is not yet supported for submissions

B2B pricing is not yet supported for submissions in the Listings Items API and JSON_LISTINGS_FEED. B2B pricing will be supported prior to the deprecation of XML feed submissions. Additionally, standard pricing may be submitted with the Listings Items API and JSON_LISTINGS_FEED without impacting existing B2B pricing configured using XML feeds, templates, or Seller Central.

While some product types are not yet available for the Listings Items API and JSON_LISTINGS_FEED, pricing data may be submitted for any listings item regardless of its product type. This allows pricing-only workflows to migrate entirely to the Listings Items API and JSON_LISTINGS_FEED.

Data mappings

The table below provides a mapping of XML element by XPath to JSON element by JSON Pointer for pricing data. Data elements no longer relevant have been excluded.

Submitting pricing data

Pricing XML feeds always handled inventory updates separately from other listings data elements (product, inventory, etc.). With the Listings Items API and JSON_LISTINGS_FEED, pricing data may be submitted by itself or alongside other listings data elements. The examples below illustrate the submission of pricing data for both scenarios.

Previous XML submission

<AmazonEnvelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="amznenvelope.xsd">
  <Header>
    <DocumentVersion>1.01</DocumentVersion>
    <MerchantIdentifier>AXXXXXXXXXXXXX</MerchantIdentifier>
  </Header>
  <MessageType>Price</MessageType>
  <Message>
    <MessageID>1</MessageID>
    <OperationType>Update</OperationType>
    <Price>
      <SKU>ABC123</SKU>
      <StandardPrice currency="USD">90.00</StandardPrice>
    </Price>
  </Message>
</AmazonEnvelope>

New Listings Items API submission when creating an offer-only listing with other data elements

PUT https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXXX/ABC123
  ?marketplaceIds=ATVPDKIKX0DER
  &issueLocale=en_US

{
  "productType": "PRODUCT",
  "requirements": "LISTING_OFFER_ONLY",
  "attributes": {
    "condition_type": [
      {
        "value": "new_new",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "merchant_suggested_asin": [
      {
        "value": "BXXXXXXXXX",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "purchasable_offer": [
      {
        "currency": "USD",
        "our_price": [
          {
            "schedule": [
              {
                "value_with_tax": 90.00
              }
            ]
          }
        ]
      }
    ],
    ... (more attributes, if applicable)
  }
}

New Listings Items API submission when updating pricing only

PATCH https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXXX/ABC123
  ?marketplaceIds=ATVPDKIKX0DER
  &issueLocale=en_US

{
  "productType": "PRODUCT",
  "patches": [
    {
      "op": "replace",
      "path": "/attributes/purchasable_offer",
      "value": [
        {
          "currency": "USD",
          "our_price": [
            {
              "schedule": [
                {
                  "value_with_tax": 90.00
                }
              ]
            }
          ]
        }
      ]
    },
    ... (more patches, if applicable)
  }
}

New JSON_LISTINGS_FEED submission when creating an offer-only listing with other data elements

{
  "header": {
    "sellerId": "AXXXXXXXXXXXXX",
    "version": "2.0",
    "issueLocale": "en_US"
  },
  "messages": [
    {
      "messageId": 1,
      "sku": "ABC123",
      "operationType": "UPDATE",
      "productType": "PRODUCT",
      `"requirements"`: `"LISTING_OFFER_ONLY"`,
      "attributes": {
        "condition_type": [
          {
            "value": "new_new",
            "marketplace_id": "ATVPDKIKX0DER"
          }
        ],
        "merchant_suggested_asin": [
          {
            "value": "BXXXXXXXXX",
            "marketplace_id": "ATVPDKIKX0DER"
          }
        ],
        "purchasable_offer": [
          {
            "currency": "USD",
            "our_price": [
              {
                "schedule": [
                  {
                    "value_with_tax": 90.00
                  }
                ]
              }
            ]
          }
        ],
        ... (more attributes, if applicable)
      }
    },
    ... (more messages, if applicable)
  ]
}

New JSON_LISTINGS_FEED submission when updating pricing only

{
  "header": {
    "sellerId": "AXXXXXXXXXXXXX",
    "version": "2.0",
    "issueLocale": "en_US"
  },
  "messages": [
    {
      "messageId": 1,
      "sku": "ABC123",
      "operationType": "PATCH",
      "productType": "PRODUCT",
      "patches": [
        {
          "op": "replace",
          "path": "/attributes/purchasable_offer",
          "value": [
            {
              "currency": "USD",
              "our_price": [
                {
                  "schedule": [
                    {
                      "value_with_tax": 90.00
                    }
                  ]
                }
              ]
            }
          ]
        },
        ... (more patches, if applicable)
      ]
    },
    ... (more messages, if applicable)
  ]
}

Migrating image feeds workflows

With previous XML feed submissions (POST_PRODUCT_IMAGE_DATA), image data was always submitted separately from product and other listings data elements by providing image types and URLs for Amazon to download images. With the Listings Items API and JSON_LISTINGS_FEED, image data may be submitted alongside all other listings data elements (for example, when creating a listing with all data elements in a single submission) or by itself (image-only updates). This section outlines the image type mappings from the legacy XML feed schema (ProductImage.xsd) along with examples before and after migration.

While some product types are not yet available for the Listings Items API and JSON_LISTINGS_FEED, image data may be submitted for any listings item regardless of its product type. This allows image-only workflows to migrate entirely to the Listings Items API and JSON_LISTINGS_FEED.

Image hosting

Images submitted with the Listings Items API and JSON_LISTINGS_FEED must be hosted on or distributed by an Amazon resource (for example, Amazon S3, AWS CloudFront). For more details on hosting requirements, see Submitting Images and Other Media Attributes. Your use-case may qualify for the AWS Free Tier for Amazon S3. For more advanced use-cases, AWS CloudFront custom origins may be used to host content in your own services or content delivery networks, with AWS CloudFront providing the distribution of your content to Amazon when submitting your listings-related images.

Image type mappings

The table below provides a mapping of image types used in XML image feeds to the applicable JSON element by JSON Pointer.

Submitting image data

Image XML feeds always handled image updates separately from other listings data elements (product, pricing, etc.) by providing image types and URLs for Amazon to download images. With the Listings Items API and JSON_LISTINGS_FEED, image data may be submitted by itself or alongside other listings data elements. The examples below illustrate the submission of image data for both scenarios.

Previous XML Submission

<AmazonEnvelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="amzn-envelope.xsd">
  <Header>
    <DocumentVersion>1.01</DocumentVersion>
    <MerchantIdentifier>AXXXXXXXXXXXXX</MerchantIdentifier>
  </Header>
  <MessageType>ProductImage</MessageType>
  <Message>
    <MessageID>1</MessageID>
    <OperationType>Update</OperationType>
    <ProductImage>
      <SKU>ABC123</SKU>
      <ImageType>Main</ImageType>
      <ImageLocation>https://example/main.jpg</ImageLocation>
    </ProductImage>
  </Message>
</AmazonEnvelope>

New Listings Items API submission when creating a listing with other data elements

PUT https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXXX/ABC123
  ?marketplaceIds=ATVPDKIKX0DER
  &issueLocale=en_US

{
  "productType": "LUGGAGE",
  "requirements": "LISTING",
  "attributes": {
    "condition_type": [
      {
        "value": "new_new",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "merchant_suggested_asin": [
      {
        "value": "BXXXXXXXXX",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "main_product_image_locator": [
      {
         "media_location": "https://example/main.jpg",
         "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    ... (more attributes, if applicable)
  }
}

New Listings Items API submission when updating images only

PATCH https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXXX/ABC123
  ?marketplaceIds=ATVPDKIKX0DER
  &issueLocale=en_US

{
  "productType": "PRODUCT",
  "patches": [
    {
      "op": "replace",
      "path": "/attributes/main_product_image_locator",
      "value": [
        {
          "media_location": "https://example/main.jpg",
          "marketplace_id": "ATVPDKIKX0DER"
        }
      ]
    },
    ... (more patches, if applicable)
  ]
}

New JSON_LISTINGS_FEED submission when creating a listing with other data elements

{
  "header": {
    "sellerId": "AXXXXXXXXXXXXX",
    "version": "2.0",
    "issueLocale": "en_US"
  },
  "messages": [
    {
      "messageId": 1,
      "sku": "ABC123",
      "operationType": "UPDATE",
      "productType": "LUGGAGE",
      "requirements": "LISTING",
      "attributes": {
        "condition_type": [
          {
            "value": "new_new",
            "marketplace_id": "ATVPDKIKX0DER"
          }
        ],
        "merchant_suggested_asin": [
          {
            "value": "BXXXXXXXXX",
            "marketplace_id": "ATVPDKIKX0DER"
          }
        ],
        "main_product_image_locator": [
          {
            "media_location": "https://example/main.jpg",
            "marketplace_id": "ATVPDKIKX0DER"
          }
        ],
        ... (more attributes, if applicable)
      }
    },
    ... (more messages, if applicable)
  ]
}

New JSON_LISTINGS_FEED submission when updating images only

{
  "header": {
    "sellerId": "AXXXXXXXXXXXXX",
    "version": "2.0",
    "issueLocale": "en_US"
  },
  "messages": [
    {
      "messageId": 1,
      "sku": "ABC123",
      "operationType": "PATCH",
      "productType": "PRODUCT",
      "patches": [
        {
          "op": "replace",
          "path": "/attributes/main_product_image_locator",
          "value": [
            {
              "media_location": "https://example/main.jpg",
              "marketplace_id": "ATVPDKIKX0DER"
            }
          ]
        },
        ... (more patches, if applicable)
      ]
    },
    ... (more messages, if applicable)
  ]
}

Migrating relationship feeds workflows

A variation family represents a collection of items for one product that is sold in multiple varieties. For example, a clothing article may come in multiple sizes and colors. Each unique size and color combination is represented by a separate listings item and grouped together by a parent listings item to provide a single detail page experience.

With XML feeds, individual listings items were created with the POST_PRODUCT_DATA feed type and the POST_PRODUCT_RELATIONSHIP_DATA feed type was then used to explicitly link listings items together under one parent listings item. With the Listings Items API and JSON_LISTINGS_FEED, a parent listings item is created first and each child listings item refers to the parent listings item with the child_parent_sku_relationship attribute. Each listings item in the variation family uses the parentage_level attribute to define if it is a parent or child within the variation family and the variation_theme attribute to define the variated attributes for the variation family.

This section outlines examples of linking listings items in a variation family using a legacy XML feed (POST_PRODUCT_RELATIONSHIP_DATA), Listings Items API, and JSON_LISTINGS_FEED.

Submitting relationships data

Relationship XML feeds always handled relationship updates separately from other listings data elements (product, pricing, etc.). With the Listings Items API and JSON_LISTINGS_FEED, relationship data may be submitted by itself or alongside other listings data elements. The examples below illustrate the submission of relationship data for both scenarios.

📘

Parent/Child relations are defined differently in XML and JSON

With relationships defined in XML feed (POST_PRODUCT_RELATIONSHIP_DATA) submissions, the relationships are configured on the variation parent referring to each variation child. With relationships defined in Listings Items API and JSON_LISTINGS_FEED submissions, the relationships are configured on each variation child referring to the variation parent.

Previous XML Submission

<?xml version="1.0" encoding="UTF-8"?>
<AmazonEnvelope>
  <Header>
    <DocumentVersion>1.01</DocumentVersion>
    <MerchantIdentifier>AXXXXXXXXXXXXX</MerchantIdentifier>
  </Header>
  <MessageType>Relationship</MessageType>
  <PurgeAndReplace>false</PurgeAndReplace>
  <Message>
    <MessageID>1</MessageID>
    <OperationType>Update</OperationType>
    <Relationship>
      <ParentSKU>ABC123</ParentSKU>
      <Relation>
        <SKU>Child123</SKU>
        <Type>Variation</Type>
      </Relation>
    </Relationship>
  </Message>
</AmazonEnvelope>

New Listings Items API submission when creating a child and adding to a variation family with other data elements

PUT https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXXX/Child123
  ?marketplaceIds=ATVPDKIKX0DER
  &issueLocale=en_US

{
  "productType": "LUGGAGE",
  "requirements": "LISTING",
  "attributes": {
    "condition_type": [
      {
        "value": "new_new",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "merchant_suggested_asin": [
      {
        "value": "BXXXXXXXXX",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "child_parent_sku_relationship": [
      {
        "child_relationship_type": "variation",
        "parent_sku": "ABC123",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    ... (more attributes, if applicable)
  }
}

New Listings Items API submission when adding a child to a variation family only

PATCH https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXXX/Child123
  ?marketplaceIds=ATVPDKIKX0DER
  &issueLocale=en_US

{
  "productType": "LUGGAGE",
  "patches": [
    {
      "op": "replace",
      "path": "/attributes/child_parent_sku_relationship",
      "value": [
        {
          "child_relationship_type": "variation",
          "parent_sku": "ABC123",
          "marketplace_id": "ATVPDKIKX0DER"
        }
      ]
    },
    ... (more patches, if applicable)
  ]
}

New JSON_LISTINGS_FEED submission when creating a child and adding to a variation family with other data elements

{
  "header": {
    "sellerId": "AXXXXXXXXXXXXX",
    "version": "2.0",
    "issueLocale": "en_US"
  },
  "messages": [
    {
      "messageId": 1,
      "sku": "Child123",
      "operationType": "UPDATE",
      "productType": "LUGGAGE",
      "requirements": "LISTING",
      "attributes": {
        "condition_type": [
          {
            "value": "new_new",
            "marketplace_id": "ATVPDKIKX0DER"
          }
        ],
        "merchant_suggested_asin": [
          {
            "value": "BXXXXXXXXX",
            "marketplace_id": "ATVPDKIKX0DER"
          }
        ],
        "child_parent_sku_relationship": [
          {
            "child_relationship_type": "variation",
            "parent_sku": "ABC123",
            "marketplace_id": "ATVPDKIKX0DER"
          }
        ],
        ... (more attributes, if applicable)
      }
    },
    ... (more messages, if applicable)
  ]
}

New JSON_LISTINGS_FEED submission when adding a child to a variation family only

{
  "header": {
    "sellerId": "AXXXXXXXXXXXXX",
    "version": "2.0",
    "issueLocale": "en_US"
  },
  "messages": [
    {
      "messageId": 1,
      "sku": "Child123",
      "operationType": "PATCH",
      "productType": "LUGGAGE",
      "patches": [
        {
          "op": "replace",
          "path": "/attributes/child_parent_sku_relationship",
          "value": [
            {
              "child_relationship_type": "variation",
              "parent_sku": "ABC123",
              "marketplace_id": "ATVPDKIKX0DER"
            }
          ]
        },
        ... (more patches, if applicable)
      ]
    },
    ... (more messages, if applicable)
  ]
}

Migrating shipping override feeds workflows

Shipping settings for listings items are configured on the account-level by default for sellers in Seller Central. Professional sellers may apply alternative shipping settings by defining shipping templates that are applied to each applicable listings item. The Listings Items API and JSON_LISTINGS_FEED support applying shipping templates to individual listings items by specifying the merchant_shipping_group attribute. By providing the sellerId parameter with the Product Type Definitions API, you can retrieve the available shipping templates configured by the seller as an enumeration on the merchant_shipping_group attribute value.

With XML feeds (POST_PRODUCT_OVERRIDES_DATA), however, shipping overrides were applied per-listing instead of with shipping templates. Shipping overrides have been deprecated in favor of shipping templates and are not supported by the Listings Items API or JSON_LISTINGS_FEED. For sellers using shipping overrides, the following Seller Central help resources provide details on configuring account-level and shipping template settings.

• Configure shipping rates and restrictions: https://sellercentral.amazon.com/help/hub/reference/G891
• Create, edit, or delete shipping templates: https://sellercentral.amazon.com/help/hub/reference/G201834090
• Migrate to the new shipping settings: https://sellercentral.amazon.com/help/hub/reference/G201834130

🚧 Shipping overrides are deprecated

Shipping overrides (POST_PRODUCT_OVERRIDES_DATA) are a deprecated feature. The MerchantShippingGroupName attribute may be used with the existing POST_PRODUCT_DATA feed type for shipping templates until migration to the Listings Items API or JSON_LISTINGS_FEED is complete.

Submitting shipping data

Shipping XML feeds always handled shipping overrides separately from other listings data elements (product, pricing, etc.). With the Listings Items API and JSON_LISTINGS_FEED, shipping templates data may be submitted by itself or alongside other listings data elements. The examples below illustrate the submission of shipping templates data for both scenarios.

New JSON_LISTINGS_FEED submission when creating a listing with other data elements

{
  "header": {
    "sellerId": "AXXXXXXXXXXXXX",
    "version": "2.0",
    "issueLocale": "en_US"
  },
  "messages": [
    {
      "messageId": 1,
      "sku": "ABC123",
      "operationType": "UPDATE",
      "productType": "LUGGAGE",
      "requirements": "LISTING",
      "attributes": {
        "condition_type": [
          {
            "value": "new_new",
            "marketplace_id": "ATVPDKIKX0DER"
          }
        ],
        "merchant_suggested_asin": [
          {
            "value": "BXXXXXXXXX",
            "marketplace_id": "ATVPDKIKX0DER"
          }
        ],
        "merchant_shipping_group": [
          {
            "value": "legacy-template-id",
            "marketplace_id": "ATVPDKIKX0DER"
          }
        ],
        ... (more attributes, if applicable)
      }
    },
    ... (more messages, if applicable)
  ]
}

New JSON_LISTINGS_FEED submission when updating shipping templates only

{
  "header": {
    "sellerId": "AXXXXXXXXXXXXX",
    "version": "2.0",
    "issueLocale": "en_US"
  },
  "messages": [
    {
      "messageId": 1,
      "sku": "ABC123",
      "operationType": "PATCH",
      "productType": "PRODUCT",
      "patches": [
        {
          "op": "replace",
          "path": "/attributes/merchant_shipping_group",
          "value": [
            {
              "value": "legacy-template-id",
              "marketplace_id": "ATVPDKIKX0DER"
            }
          ]
        },
        ... (more patches, if applicable)
      ]
    },
    ... (more messages, if applicable)
  ]
}

Migrating flat file feeds workflows

With previous flat file (POST_FLAT_FILE_LISTINGS_DATA, POST_FLAT_FILE_INVLOADER_DATA) feed submissions, various combinations of listings data elements were accepted in tabular format (Excel spreadsheets or TSV files). These combinations included all listings data elements, offer-only data elements, price and inventory data elements, and others. See the Mapping product attributes from category XSDs (XML) and flat file feed types section for files containing the full set of mappings for product data. This section outlines examples before and after migration for the price and inventory template.

Submitting data

Flat file feeds handled various combinations of listings data elements, depending on the template used. With the Listings Items API and JSON_LISTINGS_FEED, these combinations have been generalized to “requirements” to identify the type of listing being created:

• LISTING: Indicates the submitted data contains product facts and sales terms. This correlates to the “Product Template” for flat file feeds.
• LISTING_PRODUCT_ONLY: Indicates the submitted data contains product facts only. This correlates to the “Product Template” for flat file feeds with the skip offer feature selected on each row.
• LISTING_OFFER_ONLY: Indicates the submitted data contains sales terms only. This correlates to the “Listing Loader” template for flat file feeds.

When editing existing listings with flat file feeds, the “Price and Quantity” template accepted a minimal set of data for updating price and inventory details whereas the “Product Template” accepted additional details with the partial update feature selected. The examples below compare the “Price and Quantity” template to partial updates submitted to the Listings Items API and JSON_LISTINGS_FEED.

Previous flat file submission for updating price and quantity

New Listings Items API submission for updating price and quantity

PATCH https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXXX/ABC123
  ?marketplaceIds=ATVPDKIKX0DER
  &issueLocale=en_US

{
  "productType": "PRODUCT",
  "patches": [
    {
      "op": "replace",
      "path": "/attributes/purchasable_offer",
      "value": [
        {
          "currency": "USD",
          "our_price": [
            {
              "schedule": [
                {
                  "value_with_tax": 90.00
                }
              ]
            }
          ],
          "minimum_seller_allowed_price": [
            {
              "schedule": [
                {
                  "value_with_tax": 80.00
                }
              ]
            }
          ],
          "maximum_seller_allowed_price": [
            {
              "schedule": [
                {
                  "value_with_tax": 100.00
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "op": "replace",
      "path": "/attributes/fulfillment_availability",
      "value": [
        {
          "fulfillment_channel_code": "DEFAULT",
          "quantity": 5,
          "lead_time_to_ship_max_days": 1
        }
      ]
    }
    ... (more patches, if applicable)
  ]
}

New JSON_LISTINGS_FEED submission for updating price and quantity

{
  "header": {
    "sellerId": "AXXXXXXXXXXXXX",
    "version": "2.0",
    "issueLocale": "en_US"
  },
  "messages": [
    {
      "messageId": 1,
      "sku": "ABC123",
      "operationType": "PATCH",
      "productType": "LUGGAGE",
      "patches": [
        {
          "op": "replace",
          "path": "/attributes/purchasable_offer",
          "value": [
            {
              "currency": "USD",
              "our_price": [
                {
                  "schedule": [
                    {
                      "value_with_tax": 90.00
                    }
                  ]
                }
              ],
              "minimum_seller_allowed_price": [
                {
                  "schedule": [
                    {
                      "value_with_tax": 80.00
                    }
                  ]
                }
              ],
              "maximum_seller_allowed_price": [
                {
                  "schedule": [
                    {
                      "value_with_tax": 100.00
                    }
                  ]
                }
              ]
            }
          ]
        },
        {
          "op": "replace",
          "path": "/attributes/fulfillment_availability",
          "value": [
            {
              "fulfillment_channel_code": "DEFAULT",
              "quantity": 5,
              "lead_time_to_ship_max_days": 1
            }
          ]
        },
        ... (more patches, if applicable)
      ]
    },
    ... (more messages, if applicable)
  ]
}

FAQs

Am I required to migrate off the feed types listed in this guide?

Not yet. The Listings Items API, JSON_LISTINGS_FEED feed type, and related API offerings provide the means to build comprehensive, efficient, and event-driven listings workflows. However, not all product types are supported in the Listings Items API at this time. Once all product types are supported, further guidance and timelines will be provided for the deprecation of the feed types (other than JSON_LISTINGS_FEED) listed in this guide.

Shipping overrides (POST_PRODUCT_OVERRIDES_DATA), however, are a deprecated feature. Sellers using shipping overrides should migrate to account-level or shipping template settings as soon as possible to avoid disruption. The MerchantShippingGroupName attribute may be used with the existing POST_PRODUCT_DATA feed type for shipping templates until migration to the Listings Items API or JSON_LISTINGS_FEED is complete.

Can I continue to use existing feed types until my migration is complete?

Yes. You may continue to use your existing listings workflows while migrating. Once migrated (in whole or in part), submissions for the same content should not be duplicated using both workflows. For example, if you have migrated a workflow for price-only updates, submitting the same price-only updates in both old and new workflows will be redundant and cause processing delays for the duplicative submissions.

Why should I begin migrating now?

Migrating to the Listings API gives you access to up-to-date templates, including clear data requirements for product schemas, and the ability to receive synchronous and asynchronous feedback for your submissions regardless of whether you are a seller or vendor.

Can I continue to submit in bulk with feeds?

Yes. The JSON_LISTINGS_FEED feed type is compatible and interoperable with the Listings Items API and Product Type Definitions API. Deciding between using the JSON_LISTINGS_FEED, the Listings Items API, or both depends on your specific use-case. See Creating and Updating Listings Items in Bulk for more details and guidance.

What can I migrate if product types for my use-case are not yet available?

The Listings APIs is currently available for the Hardlines and Softlines categories across all marketplaces (except India) worldwide, excluding Consumables, Books, and Media categories. You can still migrate your process of updating just inventory/price or offer updates for any listings item regardless of its product type. Refer to table below for additional details on your specific use case: