Feeds API v2021-06-30 Use Case Guide

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. Refer to 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:

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

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

3. Call the createFeed 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 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, refer to Tutorial: Submit a feed.

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. Refer to Feed Type Values for a list of available feed types.

2. Authorization from the seller for whom you are making calls. Refer to Authorizing Selling Partner API applications 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 operation, passing the following parameter:

Body parameter:

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:

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

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

JSON feeds

The following is an example of a JSON feed:

{
  "header": {
    "sellerId": "AXXXXXXXXXXXX",
    "version": "2.0",
    "issueLocale": "en_US"
  },
  "messages": [
    {
      "messageId": 1,
      "sku": "My-SKU-A",
      "operationType": "DELETE"
    },
    {
      "messageId": 2,
      "sku": "My-SKU-B",
      "operationType": "PARTIAL_UPDATE",
      "productType": "LUGGAGE",
      "attributes": {
        "fulfillment_availability": [
          {
            "fulfillment_channel_code": "DEFAULT",
            "quantity": 10
          }
        ]
      }
    },
    {
      "messageId": 3,
      "sku": "My-SKU-C",
      "operationType": "UPDATE",
      "productType": "LUGGAGE",
      "requirements": "LISTING_OFFER_ONLY",
      "attributes": {
        "condition_type": [
          {
            "value": "new_new",
            "marketplace_id": "ATVPDKIKX0DER"
          }
        ],
        "merchant_suggested_asin": [
          {
            "value": "AXXXXXXXXXXXX",
            "marketplace_id": "ATVPDKIKX0DER"
          }
        ],
        "fulfillment_availability": [
          {
            "fulfillment_channel_code": "DEFAULT",
            "quantity": 0
          }
        ],
        "purchasable_offer": [
          {
            "currency": "USD",
            "our_price": [
              {
                "schedule": [
                  {
                    "value_with_tax": 100
                  }
                ]
              }
            ],
            "marketplace_id": "ATVPDKIKX0DER"
          }
        ]
      }
    },
    {
      "messageId": 4,
      "sku": "My-SKU-D",
      "operationType": "PATCH",
      "productType": "LUGGAGE",
      "patches": [
        {
          "op": "replace",
          "path": "/attributes/fulfillment_availability",
          "value": [
            {
              "fulfillment_channel_code": "DEFAULT",
              "quantity": 10
            }
          ]
        }
      ]
    }
  ]
}

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.

Sample code to upload an XML feed (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());
    }

  }
}

Sample code to upload a JSON feed (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 jsonData = "<your JSON data>";

    UploadExample obj = new UploadExample();
    obj.upload(jsonData.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 application/json, but your contentType may be different depending on your chosen feedType (text/plain, text/csv).
    String contentType = String.format("application/json; 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 operation, passing the following parameters:

Body parameters:

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:

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

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.

1. Call the getFeed operation, passing the following parameter:

Path parameter:

Request example:

GET https://sellingpartnerapi-na.amazon.com/feeds/2021-06-30/feeds/23492394

Response

A successful response includes the following elements:

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"
  }
}

2. Check the value of the processingStatus attribute.

   • If processingStatus is IN_QUEUE or IN_PROGRESS, feed processing is not yet complete. Retry the getFeed operation until processingStatus reaches one of the following terminal states: DONE, CANCELLED, or FATAL.

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

   • If processingStatus is CANCELLED, 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 is FATAL, 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.

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 can be compressed, in which case compressionAlgorithm is returned in addition to the URL. The URL expires after five minutes.

1. Call the getFeedDocument operation, passing the following parameter:

Path parameter

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:

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.

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, refer to Selling on Amazon's European Marketplaces.

Understanding how marketplaceId values are used

You 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, refer to Marketplace IDs.

Flat File Order Adjustments Feed

Sellers can use the Flat File Order Adjustments Feed (POST_FLAT_FILE_PAYMENT_ADJUSTMENT_DATA) to update Amazon's system with order adjustment information. The feed allows you to issue a full refund (adjustment) for an order. You must provide a reason for the adjustment, such as Customer Return, and the adjustment amount with specified price components, such as the principle, shipping, and tax.

You must submit refunds using the adjustment template to issue full refunds or make miscellaneous adjustments for multiple orders simultaneously.

Prepare and upload the adjustments file

To prepare and upload the adjustments file:

1. Download and save the adjustments template.
2. Open the adjustments template and review the Instructions and Definitions tabs. This template has validation macros that can help you complete the template.
3. Select the Adjustments tab in the excel file.
4. Enter the information for each order you are refunding:
   • All fields in the Adjustments file are required, except for promotion-related fields. If you are not offering promotions, delete the promotion fields from the file.
   • Hyphens in order numbers (order-id) are required. The feed will not process successfully without hyphens.
   • Format number columns as text to prevent Excel from removing leading zeros.
   • Format date columns as YYYY-MM-DD.
5. Save the file as a text (.txt) file.
6. Follow the Tutorial: Submit a feed to upload the tab delimited file and create a feed.

Input fields

Processing report

Follow Step 6. Get information for retrieving the feed processing report to retrieve the processing report for the uploaded feed.

Check the feed processing report for errors. 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 this process until there are no errors in the feed processing report.

When there are errors, the processing report includes details such as:

• Error code: A specific code that identifies the type of error.
• Error message: A descriptive message explaining the error.
• Timestamp: When the error occurred.
• Affected items: Details about which parts of the feed or specific items caused the error.
• Suggested actions: Guidance on how to correct the error.

Feed platform validation

When the feed platform receives the order adjustment feed, it performs an initial validation to ensure the feed is correctly formatted and complete before forwarding it to the refund feed processor. If there is an issue (missing required fields or incorrect format), the feed platform reports the issue in the processing report and returns it.

The refund feed processor checks that the feed adheres to the expected structure and syntax. This includes:

• Ensuring all required fields are present.
• Checking that data types (such as numbers and dates) are correct.
• Verifying that field values meet predefined criteria (for example, valid order IDs).

Beyond format, the processor checks if the orders in the feed are eligible for a refund. This involves:

• Ensuring the orders exist and are within the refundable time frame.
• Checking for any conditions that might disqualify an order from being refunded. This includes cases where the item is non-refundable or already refunded.

Any validations the feed fails are reported in the processing report.

Finally, the validator ensures that the refund request is valid and meets all criteria before processing. It includes a thorough review of all aspects of the feed to prevent errors in the refund system.

You can poll the system for the status of the feed you submit to confirm processing or get details of any errors. You use the information in the processing report to correct issues and resubmit the feed. By implementing these validation steps and error handling mechanisms, the system ensures that only correctly formatted and eligible refund requests are processed, while providing clear feedback to you to resolve any issues promptly.

Different types of errors

Best practices

For best practices using the Feeds API, refer to Feeds API Best Practices.