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 (opens new window) for a list of available feed types.

Workflow for submitting a feed

Here are the high-level steps for submitting a feed:

1. Call the createFeedDocument (opens new window) 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.

2. Upload your feed document contents to the URL from the previous step.

3. Call the createFeed (opens new window) operation. Use the inputFeedDocumentId parameter to pass in the feedDocumentId 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.

4. Periodically poll the Amazon SQS queue for the FEED_PROCESSING_FINISHED notification event, which provides information when the feed processing is CANCELLED, DONE or FATAL.

   Amazon returns the resultFeedDocumentId value in the notification when the feed moves into the DONE state.

5. Call the getFeedDocument (opens new window) operation. Use the feedDocumentId parameter to pass in the resultFeedDocumentId value from the previous step.

   Amazon returns the feedDocumentId value, a URL for downloading the feed processing report, and the compression algorithm.

6. Download the feed processing report.

7. 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

• S3 presigned URL. A URL for an AWS S3 bucket to which you can upload an object without AWS security credentials or permissions. You get an S3 presigned URL in Step 1. Create a feed document and Step 6. Get information for retrieving the feed processing report.

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:

1. A feed to submit. See Feed Type Values (opens new window) for a list of available feed types.

2. Authorization from the seller for whom you are making calls. See the Authorizing Selling Partner API applications (opens new window) for more information.

3. A working Java Development Kit (JDK) installation.

Step 1. Create a feed document

Call the createFeedDocument operation to create a feed document.

1. Call the createFeedDocument (opens new window) 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 contentType value in Step 3. Upload the feed data. Otherwise your feed data upload will fail. 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	The presigned URL for uploading the feed contents. 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>"
}

2. 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. This feedDocumentId value expires after two days. If you pass in an expired feedDocumentId value to the createFeed 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 (opens new window). Used to promote consistency among feeds. All other XSDs reference the elements and data types in the Base XSD.
• Envelope (opens new window). Used to wrap all other data with message-level protocol data. Consists of a header and one or more messages.
• Header (opens new window). 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 (opens new window) 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:

<?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>M_EXAMPLE_123456</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.

1. Call the createFeed (opens new window) 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 createFeedDocument operation in Step 1. Create a feed document. 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"
}

2. Save the feedId value. Pass this value in the getFeed operation in Step 5. Confirm feed processing.

Step 5. Confirm feed processing

After you call the createFeed operation, Amazon receives the request and begins to process the feed. You must confirm that processing has completed before you continue.

We recommend that you use the Notifications API (opens new window) to subscribe to the event FEED_PROCESSING_FINISHED to be notified when the feed processing status changes. This reduces the number of calls you make to the getFeed (opens new window) operation for processing status checks.

The FEED_PROCESSING_FINISHED notification is sent whenever any feed submitted using the Selling Partner API for Feeds reaches a feed processing status of DONE, CANCELLED, or FATAL.

To subscribe to the FEED_PROCESSING_FINISHED notification type, refer to the Notifications API Use Case Guide (opens new window). For more information refer to FEED_PROCESSING_FINISHED notification event. (opens new window)

The following processingStatus values confirm that processing is complete:

• DONE - feed processing is complete. Go to Step 6. Get information for retrieving the feed processing report.

• CANCELLED - the feed was cancelled before it began to process. If you want to resubmit the feed, go to Step 1. Create a feed document.

• FATAL - the feed was abandoned 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 retrieve a feed processing report. In rare cases, Amazon might abandon a feed for reasons unrelated to the feed. If you can find no errors in the feed to correct, try submitting the feed again.

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.

1. Call the getFeedDocument (opens new window) operation, passing the following parameter:

Path parameter:

Name	Description	Required
feedDocumentId	The identifier of the feed document. Use the resultFeedDocumentId value returned in Step 5. Confirm feed processing. 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. This URL expires after 5 minutes. Type: string	Yes
compressionAlgorithm	If present, the feed document contents are compressed using the indicated algorithm. Type: compressionAlgorithm	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>"
}

2. Save the url and optional compressionAlgorithm 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.

1. Use the following as inputs for the sample code:

   • The url and optional compressionAlgorithm values from the previous step are arguments for the url, and compressionAlgorithm parameters of the download method of the DownloadExample class.

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.

Best practices

For best practices using the Feeds API, refer to Feeds API Best Practices (opens new window).