Listing workflow migration tutorial

How the Listings Items API and JSON_LISTINGS_FEED relate to legacy XML and flat file feed types.

Migration workflows help you migrate your individual listings workflows. This guide shows how the Listings Items API and JSON_LISTINGS_FEED relate to legacy XML and flat file feed types, outlining API endpoints and payload examples before and after migration.

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 can 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. Refer to 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 (such as inventory and pricing). With the Listings Items API and JSON_LISTINGS_FEED, you can submit product data alone or with other listings data elements. The following examples describe 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 can 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 can 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

For a mapping of XML element by XPath to JSON element by JSON Pointer for inventory data, refer to Inventory Feed mappings.

Image hosting

To learn how to submit images and other media attributes to the Listings Items API, refer to Submitting images and other media attributes.

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 can be submitted by itself or alongside other listings data elements. The following examples illustrate the submission of inventory data for both scenarios.

Inventory XML feeds always handled inventory updates separately from other listings data elements (such as product and pricing). With the Listings Items API and JSON_LISTINGS_FEED, inventory data may be submitted by itself or alongside other listings data elements. The following examples 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 can be achieved by patching an item to explicitly add one and explicitly delete the other. The following examples 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 can 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.

📘
Note
B2B pricing is now supported for submissions in the Listings Items API and JSON_LISTINGS_FEED. For more information, refer to Manage Advanced Multiple-Offer and Multiple-Fulfillment Use Cases.

While some product types are not yet available for the Listings Items API and JSON_LISTINGS_FEED, you can submit pricing data for any listings item regardless of its product type. Because of this, you can migrate pricing-only workflows entirely to the Listings Items API and JSON_LISTINGS_FEED.

Data mappings

For a mapping of XML element by XPath to JSON element by JSON Pointer for pricing data, refer to Pricing Feed mappings.

Submitting pricing data

Pricing XML feeds always handled pricing updates separately from other listings data elements (such as product and inventory). With the Listings Items API and JSON_LISTINGS_FEED, pricing data may be submitted by itself or alongside other listings data elements. The following examples 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">30.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": [
      {
        "audience": "ALL",
        "currency": "USD",
        "our_price": [
          {
            "schedule": [
              {
                "value_with_tax": 30.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": [
        {
          "audience": "ALL",
          "currency": "USD",
          "our_price": [
            {
              "schedule": [
                {
                  "value_with_tax": 30.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": [
          {
            "audience": "ALL",
            "currency": "USD",
            "our_price": [
              {
                "schedule": [
                  {
                    "value_with_tax": 30.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": [
            {
              "audience": "ALL",
              "currency": "USD",
              "our_price": [
                {
                  "schedule": [
                    {
                      "value_with_tax": 30.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 can 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 can 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.

Data mappings

For a mapping of image types used in XML image feeds to the applicable JSON element by JSON Pointer, refer to Image type mappings.

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, refer to Submitting Images and Other Media Attributes. Your use case might qualify for the AWS Free Tier for Amazon S3. For more advanced use cases, AWS CloudFront custom origins can 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.

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 can be submitted by itself or alongside other listings data elements. The following examples illustrate the submission of image data for both scenarios.
Image XML feeds always handled image updates separately from other listings data elements (such as product and pricing) 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 following examples 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 can 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 can be submitted by itself or alongside other listings data elements. The following examples illustrate the submission of relationship data for both scenarios.

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

📘
Note
Parent-child relationships 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 can 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 can 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 can be submitted by itself or alongside other listings data elements. The following examples illustrate the submission of shipping templates data for both scenarios.

Shipping XML feeds always handled shipping overrides separately from other listings data elements (such as product and pricing). With the Listings Items API and JSON_LISTINGS_FEED, shipping templates data may be submitted by itself or alongside other listings data elements. The following examples 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. Refer to 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 following examples 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

SKU	Price	Minimum Seller Allowed Price	Maximum Seller Allowed Price	Quantity	Handling time	Fulfillment channel
ABC123	90.00	80.00	100.00	5	1	`DEFAULT`

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)
  ]
}

Updated about 2 months ago

Listing workflow migration tutorial

Migrating product feeds workflows

Submitting product data

Migrating inventory feeds workflows

Data mappings

Image hosting

Submitting inventory data

`SwitchFulfillmentTo` (convert between MFN and FBA)

Migrating pricing feeds workflows

📘
Note

Data mappings

Submitting pricing data

Migrating image feeds workflows

Data mappings

Image hosting

Submitting image data

Migrating relationship feeds workflows

Submitting relationships data

📘
Note

Migrating shipping override feeds workflows

🚧
Shipping overrides are deprecated

Submitting shipping data

Migrating flat file feeds workflows

Submitting data

Migrating product feeds workflows

Submitting product data

Migrating inventory feeds workflows

Data mappings

Image hosting

Submitting inventory data

SwitchFulfillmentTo (convert between MFN and FBA)

Migrating pricing feeds workflows

📘Note

Data mappings

Submitting pricing data

Migrating image feeds workflows

Data mappings

Image hosting

Submitting image data

Migrating relationship feeds workflows

Submitting relationships data

📘Note

Migrating shipping override feeds workflows

🚧Shipping overrides are deprecated

Submitting shipping data

Migrating flat file feeds workflows

Submitting data

`SwitchFulfillmentTo` (convert between MFN and FBA)

📘
Note

📘
Note

🚧
Shipping overrides are deprecated