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
, product data can be submitted by itself or alongside other listings data elements. The following examples 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 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.
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 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)
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.
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 can be submitted with the Listings Items API andJSON_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 can 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
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 (product, inventory, etc.). With the Listings Items API and JSON_LISTINGS_FEED
, pricing data can be submitted by itself or alongside other listings data elements. The following examples illustrate the submission of pricing data for both scenarios.
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 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 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 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 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 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 andJSON_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. TheMerchantShippingGroupName
attribute can be used with the existingPOST_PRODUCT_DATA
feed type for shipping templates until migration to the Listings Items API orJSON_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 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. 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 1 month ago