Feeds API v2021-06-30 Use Case Guide
Upload data to Amazon to manage a selling business.
API Version: 2021-06-30
What is the Feeds API?
With the Selling Partner API for Feeds (Feeds API), you can build applications that enable sellers to upload information to Amazon that helps them manage their selling businesses. There are feeds for a wide variety of use cases, such as creating listings, managing inventory and prices, acknowledging orders, and more. See Feed Type Values for a list of available feed types.
Workflow for submitting a feed
Here are the high-level steps for submitting a feed:
-
Call the
createFeedDocument
operation, specifying the content type for the feed that you are submitting.Amazon returns a
feedDocumentId
value and a URL for uploading the feed contents. -
Upload your feed document contents to the URL from the previous step.
-
Call the
createFeed
operation. Use theinputFeedDocumentId
parameter to pass in thefeedDocumentId
value from step 1. Specify the marketplaces that you want the feed to be applied to and any relevant feed options.Amazon returns a
feedId
value. -
Periodically poll the Amazon SQS queue for the
FEED_PROCESSING_FINISHED
notification event, which provides information when the feed processing isCANCELLED
,DONE
, orFATAL
.Amazon returns the
resultFeedDocumentId
value in the notification when the feed moves into theDONE
state. -
Call the
getFeedDocument
operation. Use thefeedDocumentId
parameter to pass in theresultFeedDocumentId
value from the previous step.Amazon returns the
feedDocumentId
value, a URL for downloading the feed processing report, and the compression algorithm. -
Download the feed processing report.
-
Check the feed processing report for errors generated during feed processing. If there are errors, correct them and submit the corrected feed, starting at step 1. If there are no errors, your feed submission was successful.
For more details about submitting a feed, see Tutorial: Submit a feed.
Terminology
- Amazon S3 presigned URL: A URL for an S3 bucket from which you can download an object without AWS security credentials or permissions. In some cases the object may be compressed, in which case
compressionAlgorithm
is returned in addition to the URL. The URL expires after 5 minutes.
Tutorial: Submit a feed
This tutorial shows you how to submit a feed, check the status of feed processing, and verify that your feed submission was successful. The tutorial contains Java code samples that demonstrate a way to upload a feed and download a feed processing summary report. You can use the principles demonstrated in the sample code to guide you in building applications in other programming languages, using other HttpClient libraries or upload feeds with different formats.
Prerequisites
To complete this tutorial, you will need:
-
A feed to submit. See Feed Type Values for a list of available feed types.
-
Authorization from the seller for whom you are making calls. See the Authorizing Selling Partner API applications for more information.
-
A working Java Development Kit (JDK) installation.
Step 1. Create a feed document
Call the createFeedDocument
operation to create a feed document.
- Call the
createFeedDocument
operation, passing the following parameter:
Body parameter:
Name | Description | Required |
---|---|---|
contentType | The content type of the feed. Amazon recommends UTF-8 character encoding. Important: Use this Type: string | Yes |
Request example
POST https://sellingpartnerapi-na.amazon.com/feeds/2021-06-30/documents
{
"contentType":"text/xml; charset=UTF-8"
}
Response
A successful response includes the following:
Name | Description | Required |
---|---|---|
feedDocumentId | The identifier of the feed document. Type: string | Yes |
url | A presigned URL for the feed document. If `compressionAlgorithm` is not returned, you can download the report directly from this URL. This URL expires after 5 minutes. Type: string | Yes |
Response example
{
"feedDocumentId": "amzn1.tortuga.3.920614b0-fc4c-4393-b0d9-fff175300000.T29XK4YL08B2VM",
"url": "https://tortuga-prod-na.s3.amazonaws.com/%2FNinetyDays/amzn1.tortuga.3.920614b0-fc4c-4393-b0d9-fff175300000.T29XK4YL08B2VM?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20200919T035824Z&X-Amz-SignedHeaders=<headers>&X-Amz-Expires=300&X-Amz-Credential=<credential>&X-Amz-Signature=<signature>"
}
-
Save the following values:
-
url
. Use this value in Step 3. Upload the feed data. -
feedDocumentId
. Use this value in Step 4. Create a feed. ThisfeedDocumentId
value expires after two days. If you pass in an expiredfeedDocumentId
value to thecreateFeed
operation, the call will fail.
-
Step 2. Construct a feed
Construct a feed that you can upload in Step 3. Upload the feed data.
XML feeds
To construct an XML feed you need to include the three core XSDs (Base, Envelope, and Header) plus your category-specific feed.
Core XSDs:
- Base. Used to promote consistency among feeds. All other XSDs reference the elements and data types in the Base XSD.
- Envelope. Used to wrap all other data with message-level protocol data. Consists of a header and one or more messages.
- Header. Used by the Envelope XSD to specify universal data related to the feed or a message in the feed.
For links to XSDs for category-specific feeds, go to XSDs in the Seller Central Help and look in the Category XSDs section.
The following is an example of an XML feed for a health-related product:
Use a Seller ID for
MerchantIdentifier
The value of
MerchantIdentifier
in the following feed must be a Seller ID. Your Seller ID can be found in Seller Central under Settings > Account Info > Your Merchant Token.
<?xml version="1.0" encoding="iso-8859-1"?>
<AmazonEnvelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="amzn-envelope.xsd">
<Header>
<DocumentVersion>1.01</DocumentVersion>
<MerchantIdentifier>XXXXXXXXXXXXX</MerchantIdentifier>
</Header>
<MessageType>Product</MessageType>
<PurgeAndReplace>false</PurgeAndReplace>
<Message>
<MessageID>1</MessageID>
<OperationType>Update</OperationType>
<Product>
<SKU>56789</SKU>
<StandardProductID>
<Type>ASIN</Type>
<Value>B0EXAMPLEG</Value>
</StandardProductID>
<ProductTaxCode>A_GEN_NOTAX</ProductTaxCode>
<DescriptionData>
<Title>Example Product Title</Title>
<Brand>Example Product Brand</Brand>
<Description>This is an example product description.</Description>
<BulletPoint>Example Bullet Point 1</BulletPoint>
<BulletPoint>Example Bullet Point 2</BulletPoint>
<MSRP currency="USD">25.19</MSRP>
<Manufacturer>Example Product Manufacturer</Manufacturer>
<ItemType>example-item-type</ItemType>
</DescriptionData>
<ProductData>
<Health>
<ProductType>
<HealthMisc>
<Ingredients>Example Ingredients</Ingredients>
<Directions>Example Directions</Directions>
</HealthMisc>
</ProductType>
</Health>
</ProductData>
</Product>
</Message>
</AmazonEnvelope>
Step 3. Upload the feed data
You can upload the feed that you constructed in Step 2. Construct a feed using the information returned in Step 1. Create a feed document. The following sample code demonstrates one way to upload the feed content. You can also use the principles demonstrated in the sample code to guide you in building applications in other programming languages or using other HttpClient libraries.
The sample upload
method shown in the UploadExample
class accepts your feed content as the first argument, and the url
value that you saved in Step 1 as the second argument.
Upload sample code (Java)
// UploadExample.java
// This example is for use with the Selling Partner API for Feeds, Version: 2021-06-30
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import com.squareup.okhttp.MediaType;
import com.squareup.okhttp.OkHttpClient;
import com.squareup.okhttp.Request;
import com.squareup.okhttp.RequestBody;
import com.squareup.okhttp.Response;
/**
* Example that uploads content.
*/
public class UploadExample {
public static void main(String args[]) {
String url = "<URL from the createFeedDocument operation>";
String content = "<your feed content>";
UploadExample obj = new UploadExample();
obj.upload(content.getBytes(StandardCharsets.UTF_8), url);
}
/**
* Upload content to the given URL.
*
* @param source the content to upload
* @param url the URL to upload content
*/
public void upload(byte[] source, String url) {
OkHttpClient client = new OkHttpClient();
// The contentType must match the input provided to the createFeedDocument operation. This example uses text/xml, but your contentType may be different depending upon on your chosen feedType (text/plain, text/csv, and so on).
String contentType = String.format("text/xml; charset=%s", StandardCharsets.UTF_8);
try {
Request request = new Request.Builder()
.url(url)
.put(RequestBody.create(MediaType.parse(contentType), source))
.build();
Response response = client.newCall(request).execute();
if (!response.isSuccessful()) {
System.out.println(
String.format("Call to upload document failed with response code: %d and message: %s",
response.code(), response.message()));
}
} catch (IOException e) {
System.out.println(e.getMessage());
}
}
}
Step 4. Create a feed
Call the createFeed
operation to specify the feed document identifier, the feed type, the marketplaces that you want the feed to be applied to, and any optional parameters that you want.
- Call the
createFeed
operation, passing the following parameters:
Body parameters:
Name | Description | Required |
---|---|---|
feedType | The type of feed that you are submitting. For more information, see Feed Type Values. Type: string | Yes |
marketplaceIds | A list of identifiers for marketplaces that you want the feed to be applied to. Type: < string > array | Yes |
inputFeedDocumentId | The document identifier returned by the Type: string | Yes |
feedOptions | Additional options to control the feed. These vary by feed type. Type: string | No |
Request example
POST https://sellingpartnerapi-na.amazon.com/feeds/2021-06-30/feeds
{
"feedType":"POST_PRODUCT_DATA",
"marketplaceIds":[
"ATVPDKIKX0DER",
"A2EUQ1WTGCTBG2"
],
"inputFeedDocumentId":"amzn1.tortuga.3.920614b0-fc4c-4393-b0d9-fff175300000.T29XK4YL08B2VM"
}
Request example for an Easy Ship order
POST https://sellingpartnerapi-na.amazon.com/feeds/2021-06-30/feeds
{
"feedType":"POST_EASYSHIP_DOCUMENTS",
"marketplaceIds":["A21TJRUUN4KGV"],
"feedOptions":
{
"AmazonOrderId":"902-3159896-1390916",
"DocumentType":"ShippingLabel"
},
"inputFeedDocumentId":"amzn1.tortuga.3.06438a22-2b6f-4138-a120-362c096d5e04.TKXDFQFUMYD86"
}
Response
A successful response includes the following element:
Name | Description | Required |
---|---|---|
feedId | The identifier for the feed. This identifier is unique only in combination with a seller ID. Type: string | Yes |
Response example
{
"feedId": "23492394"
}
- Save the
feedId
value. Pass this value in the getFeed operation in Step 5. Confirm feed processing.
Step 5. Confirm feed processing
Confirm feed processing by periodically calling the getFeed
operation until the feed moves into one of the following terminal states: DONE
, CANCELLED
, or FATAL
. When the feed moves into the DONE
state, proceed to Step 6. Get information for retrieving the feed processing report.
Feeds can take up to eight hours to process
Under high load conditions it is not uncommon for feeds to take up to eight hours to process. Product data feeds are processed sequentially; the most recent feed will be queued in the processing system until previous feed submissions have completed. Substantial processing delays can occur when multiple product feeds contain only a few items each instead of a single product feed with all items.
- Call the
getFeed
operation, passing the following parameter:
Path parameter:
Name | Description | Required |
---|---|---|
feedId | The identifier for the feed. Get this identifier from the result of the call to the Type: string | Yes |
Request example:
GET https://sellingpartnerapi-na.amazon.com/feeds/2021-06-30/feeds/23492394
Response
A successful response includes the following elements:
Name | Description | Required |
---|---|---|
feedId | The identifier for the feed document. This identifier is unique only in combination with a seller ID. Type: string | Yes |
feedType | The feed type. Type: string | Yes |
marketplaceIds | A list of identifiers for the marketplaces that the feed is applied to. Type: < string > array | No |
createdTime | The date and time when the feed was created, in ISO 8601 date time format. Type: string (date-time) | Yes |
processingStatus | The processing status of the feed. Type: ProcessingStatus | Yes |
processingStartTime | The date and time when feed processing started, in ISO 8601 date time format. Type: string (date-time) | No |
processingEndTime | The date and time when feed processing completed, in ISO 8601 date time format. Type: string (date-time) | No |
resultFeedDocumentId | The identifier for the feed document. This identifier is unique only in combination with a seller ID. Type: string | No |
Response Example
{
"payload":
{
"processingEndTime":"2020-08-10T16:56:55+00:00",
"processingStatus":"DONE",
"marketplaceIds":[
"ATVPDKIKX0DER"
],
"feedId":"23492394",
"feedType":"POST_PRODUCT_DATA",
"createdTime":"2020-08-10T16:55:32+00:00",
"processingStartTime":"2020-08-10T16:55:40+00:00",
"resultFeedDocumentId":"amzn1.tortuga.3.ed4cd0d8-447b-4c22-96b5-52da8ace1207.T3YUVYPGKE9BMY"
}
}
-
Check the value of the
processingStatus
attribute.-
If
processingStatus
isIN_QUEUE
orIN_PROGRESS
, feed processing is not yet complete. Retry the getFeed operation untilprocessingStatus
reaches one of the following terminal states:DONE
,CANCELLED
, orFATAL
. -
If
processingStatus
isDONE
, feed processing is complete. Go to Step 6. Get information for retrieving the feed processing report. -
If
processingStatus
isCANCELLED
, the feed was cancelled before it started processing. If you want to submit the feed again, start again at Step 1. Create a feed document. -
If
processingStatus
isFATAL
, the feed was stopped due to a fatal error. Some, none, or all of the operations within the feed might have completed successfully. In some (but not all) cases Amazon generates a feed processing report. If Amazon generates a report, it could be in a different format from a feed processing report for a successfully completed feed. Go to Step 6. Get information for retrieving the feed processing report to attempt to retrieve a feed processing report. In rare cases Amazon might stop a feed for reasons unrelated to the feed. If you can find no errors in the feed to correct, try submitting the feed again.
-
Note: The getFeed
operation only serves information for feed requests that were created within the last 90 days.
Step 6. Get information for retrieving the feed processing report
The feed processing report indicates which records in the feed that you submitted were successful and which records generated errors. In this step you get a presigned URL for downloading the feed processing report as well as the information required to decrypt the document's contents. In some cases the object may be compressed, in which case compressionAlgorithm
is returned in addition to the URL. The URL expires after 5 minutes.
- Call the
getFeedDocument
operation, passing the following parameter:
Path parameter
Name | Description | Required |
---|---|---|
feedDocumentId | The identifier of the feed document. Use the Type: string | Yes |
Request example
GET https://sellingpartnerapi-na.amazon.com/feeds/2021-06-30/documents/amzn1.tortuga.3.ed4cd0d8-447b-4c22-96b5-52da8ace1207.T3YUVYPGKE9BMY
Response
A successful response includes the following elements:
Name | Description | Required |
---|---|---|
feedDocumentId | The identifier for the feed document. This identifier is unique only in combination with a seller ID. Type: string | Yes |
url | A presigned URL for the feed document. If `compressionAlgorithm` is not returned, you can download the report directly from this URL. This URL expires after 5 minutes. Type: string | Yes |
compressionAlgorithm | If the feed document contents have been compressed, the compression algorithm used is returned in this property and you must decompress the feed when you download. Otherwise, you can download the feed directly. Refer to [Step 7. Download and decrypt the feed processing report](doc:feeds-api-v2021-06-30-use-case-guide#step-7-download-the-feed-processing-report) in the use case guide, where sample code is provided. Type: | No |
Response example:
{
"feedDocumentId": "amzn1.tortuga.3.ed4cd0d8-447b-4c22-96b5-52da8ace1207.T3YUVYPGKE9BMY",
"url": "https://tortuga-prod-na.s3.amazonaws.com/%2FNinetyDays/amzn1.tortuga.3.920614b0-fc4c-4393-b0d9-fff175300000.T29XK4YL08B2VM?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20200919T035824Z&X-Amz-SignedHeaders=<headers>&X-Amz-Expires=300&X-Amz-Credential=<credential>&X-Amz-Signature=<signature>"
}
- Save the
url
and optionalcompressionAlgorithm
values to pass in Step 7. Download the feed processing report.
Step 7. Download the feed processing report
You can download the feed processing report using the information returned in the previous step. The following Java sample code can help. You can also use the principles demonstrated in the Java sample code to guide you in building applications in other programming languages.
-
Use the following as inputs for the sample code:
- The
url
and optionalcompressionAlgorithm
values from the previous step are arguments for theurl
andcompressionAlgorithm
parameters of thedownload
method of theDownloadExample
class.
- The
Note: It's the developer's responsibility to always maintain encryption at rest. Unencrypted feed processing report content should never be stored on disk, even temporarily, because feed processing reports can contain sensitive information. The sample code that we provide demonstrates this principle.
Download sample code (Java)
// DownloadExample.java
// This example is for use with the Selling Partner API for Reports, Version: 2021-06-30
// and the Selling Partner API for Feeds, Version: 2021-06-30
import java.io.BufferedReader;
import java.io.Closeable;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.nio.charset.Charset;
import java.util.zip.GZIPInputStream;
import com.squareup.okhttp.MediaType;
import com.squareup.okhttp.OkHttpClient;
import com.squareup.okhttp.Request;
import com.squareup.okhttp.Response;
import com.squareup.okhttp.ResponseBody;
/**
* Example that downloads a document.
*/
public class DownloadExample {
public static void main(String args[]) {
String url = "<URL from the getFeedDocument/getReportDocument response>";
String compressionAlgorithm = "<compressionAlgorithm from the getFeedDocument/getReportDocument response>";
DownloadExample obj = new DownloadExample();
try {
obj.download(url, compressionAlgorithm);
} catch (IOException e) {
//Handle exception here.
} catch (IllegalArgumentException e) {
//Handle exception here.
}
}
/**
* Download and optionally decompress the document retrieved from the given url.
*
* @param url the url pointing to a document
* @param compressionAlgorithm the compressionAlgorithm used for the document
* @throws IOException when there is an error reading the response
* @throws IllegalArgumentException when the charset is missing
*/
public void download(String url, String compressionAlgorithm) throws IOException, IllegalArgumentException {
OkHttpClient httpclient = new OkHttpClient();
Request request = new Request.Builder()
.url(url)
.get()
.build();
Response response = httpclient.newCall(request).execute();
if (!response.isSuccessful()) {
System.out.println(
String.format("Call to download content was unsuccessful with response code: %d and message: %s",
response.code(), response.message()));
return;
}
try (ResponseBody responseBody = response.body()) {
MediaType mediaType = MediaType.parse(response.header("Content-Type"));
Charset charset = mediaType.charset();
if (charset == null) {
throw new IllegalArgumentException(String.format(
"Could not parse character set from '%s'", mediaType.toString()));
}
Closeable closeThis = null;
try {
InputStream inputStream = responseBody.byteStream();
closeThis = inputStream;
if ("GZIP".equals(compressionAlgorithm)) {
inputStream = new GZIPInputStream(inputStream);
closeThis = inputStream;
}
// This example assumes that the download content has a charset in the content-type header, e.g.
// text/plain; charset=UTF-8
if ("text".equals(mediaType.type()) && "plain".equals(mediaType.subtype())) {
InputStreamReader inputStreamReader = new InputStreamReader(inputStream, charset);
closeThis = inputStreamReader;
BufferedReader reader = new BufferedReader(inputStreamReader);
closeThis = reader;
String line;
do {
line = reader.readLine();
// Process line by line.
} while (line != null);
} else {
//Handle content with binary data/other media types here.
}
} finally {
if (closeThis != null) {
closeThis.close();
}
}
}
}
}
Step 8. Check the feed processing report for errors
Check the feed processing report for errors generated during processing. If there are no errors, your feed submission is complete. If there are errors, correct them and submit the corrected feed, starting at Step 1. Create a feed document. Repeat the process until there are no errors in the feed processing report.
Using multiple marketplaces
If you are registered in multiple marketplaces, then you have multiple marketplaceId
values associated with your seller ID. For a list of marketplaceId
values, refer to Marketplace IDs. You can submit a feed that is applied to one or several marketplaceId
values. If you are in the EU or NA region, you can submit feeds to support multiple marketplaces if you have registered using a single, unified seller account.
If you sell in multiple marketplaces, you can manage your inventory levels using the same SKUs across multiple marketplaces. This eliminates the need for you to manually keep inventory levels across several marketplaces in sync. For more information on selling in multiple marketplaces, see Selling on Amazon's European Marketplaces.
Understanding how marketplaceId
values are used
marketplaceId
values are usedYou specify what marketplaces you want a feed to be applied to by supplying a list of marketplaceId
values to the marketplaceIds
parameter when you call the createFeed
operation. For example, an EU multiple-marketplace seller could specify that a feed be applied to both their FR and DE marketplaces by specifying the marketplaceIds
parameter as follows:
[
"A13V1IB3VIYZZH",
"A1PA6795UKMFR9"
]
For EU and NA sellers, you do not need to use a specific country endpoint, such as https://sellingpartnerapi-eu.amazon.com
, to indicate what marketplace a feed is to be applied to. You can apply changes to a given EU or NA marketplace by specifying that marketplaceId
when submitting a feed. For a list of marketplaceId
values, see Marketplace IDs.
Best practices
For best practices using the Feeds API, refer to Feeds API Best Practices.
Updated about 1 month ago