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. 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:
-
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, refer to 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 can be compressed, in which case
compressionAlgorithm
is returned in addition to the URL. The URL expires after five 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. Refer to Feed Type Values for a list of available feed types.
-
Authorization from the seller for whom you are making calls. Refer to 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 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 is located 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>
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.
- 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, refer to 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 thegetFeed
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 thegetFeed
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 can be compressed, in which case compressionAlgorithm
is returned in addition to the URL. The URL expires after five 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 five 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 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 is your 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
Note
The JSON Listings Feed (
JSON_LISTINGS_FEED
) only supports a single marketplace per feed. When using theJSON_LISTINGS_FEED
, you must send a feed for each marketplace.
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
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, 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:
- Download and save the adjustments template.
- Open the adjustments template and review the Instructions and Definitions tabs. This template has validation macros that can help you complete the template.
- Select the Adjustments tab in the excel file.
- 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
.
- Save the file as a text (
.txt
) file. - Follow the Tutorial: Submit a feed to upload the tab delimited file and create a feed.
Input fields
Field name | Definition | Accepted Values | Example |
---|---|---|---|
order-id | Amazon's unique, displayable identifier for an order, provided in your OrderReport . | Alphanumeric text formatted as ###-#######-####### . | 123-1234567-1234567 |
order-item-id | Amazon's unique, displayable identifier for an item within an order, provided in your OrderReport . | Alphanumeric text, 14 characters. | 12345678901234 |
adjustment-reason-code | The reason for the refund or adjustment. | - NoInventory - CustomerReturn - GeneralAdjustment - CouldNotShip - DifferentItem - Abandoned - CustomerCancel - PriceError | CustomerReturn |
item-price-adj | The amount refunded to the buyer for the item. All amounts are aggregates of the quantity, not unit prices. Amounts are signed; positive amounts are refunded to the buyer and negative amounts are charged to the buyer (for example, restocking fees). Adjustments can be made within the amount authorized by the customer, but no adjustment can exceed the authorized amount. | A number with up to 20 digits to the left of the decimal point and two digits required to the right of the decimal point. Do not use commas. | 22.49 |
shipping-price-adj | The amount refunded to the buyer for the item's shipment. All amounts are aggregates of the quantity, not unit prices. Amounts are signed; positive amounts are refunded to the buyer and negative amounts are charged to the buyer. Adjustments can be made within the amount authorized by the customer, but no adjustment can exceed the authorized amount. | A number with up to 20 digits to the left of the decimal point and two digits required to the right of the decimal point. Do not use commas. | 4.99 |
item-tax-adj | The amount refunded to the buyer for the item tax. All amounts are aggregates of the quantity, not unit prices. Amounts are signed; positive amounts are refunded to the buyer and negative amounts are charged to the buyer. Adjustments can be made within the amount authorized by the customer, but no adjustment can exceed the authorized amount. | A number with up to 20 digits to the left of the decimal point and two digits required to the right of the decimal point. Do not use commas. | 2.25 |
shipping-tax-adj | The amount refunded to the buyer for the item's shipment tax. All amounts are aggregates of the quantity, not unit prices. Amounts are signed; positive amounts are refunded to the buyer and negative amounts are charged to the buyer. Adjustments can be made within the amount authorized by the customer, but no adjustment can exceed the authorized amount. | A number with up to 20 digits to the left of the decimal point and two digits required to the right of the decimal point. Do not use commas. | 0.5 |
gift-wrap-price-adj | The amount refunded to the buyer for the item's gift wrap tax. All amounts are aggregates of the quantity, not unit prices. Amounts are signed; positive amounts are refunded to the buyer and negative amounts are charged to the buyer. Adjustments can be made within the amount authorized by the customer but, no adjustment can exceed the authorized amount. | A number with up to 20 digits to the left of the decimal point and two digits required to the right of the decimal point. Do not use commas. | 4.99 |
gift-wrap-tax-adj | The amount refunded to the buyer for the item's gift wrap tax. All amounts are aggregates of the quantity, not unit prices. Amounts are signed; positive amounts are refunded to the buyer and negative amounts are charged to the buyer. Adjustments can be made within the amount authorized by the customer but, no adjustment can exceed the authorized amount. | A number with up to 20 digits to the left of the decimal point and two digits required to the right of the decimal point. Do not use commas. | 0.45 |
item-promotion-adj | The amount to be refunded for the item's promotion. All amounts are aggregates of the quantity, not unit prices. Amounts are signed; positive amounts are refunded to the buyer and negative amounts are charged to the buyer. Adjustments can be made within the amount authorized by the customer, but no adjustment can exceed the authorized amount. | A number with up to 20 digits to the left of the decimal point and two digits required to the right of the decimal point. Do not use commas. | 2.25 |
item-promotion-id | Merchant-specified promotion ID. | Alphanumeric text, up to 80 characters. | FREESHIPHOLIDAY |
ship-promotion-adj | The amount to be refunded for the item's shipping promotion. All amounts are aggregates of the quantity, not unit prices. Amounts are signed; positive amounts are refunded to the buyer and negative amounts are charged to the buyer. Adjustments can be made within the amount authorized by the customer, but no adjustment can exceed the authorized amount. | A number with up to 20 digits to the left of the decimal point and two digits required to the right of the decimal point. Do not use commas. | 1.75 |
ship-promotion-id | Merchant-specified promotion ID. | Alphanumeric text, up to 80 characters. | DOLLAROFFPROMO |
quantity-cancelled | Quantity cancelled of the order-item being adjusted. | A positive integer. | 1 |
currency | The currency code for the adjustments. This must be the same as the currency code for the adjusted order. | - USD - GBP - EUR - JPY - CAD | USD |
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
Error | Possible reasons | Possible solutions |
---|---|---|
Error attempting to issue refund for order | Invalid order-id or order-item-id field | Check the order. The order you're trying to refund might not exist in the system, or it might be in an invalid state (for example, already refunded, cancelled, or completed). |
Invalid currency code | Invalid currency field | Ensure that the currency code is properly formatted. |
Missing pricing currency unit | Missing currency field | Double check the currency field provided in the template. |
Invalid amount issued for refund item | Invalid shipping-price-adj , shipping-tax-adj , or ship-promotion-adj values in the template | There is an issue with the amount specified for refunding a shipping-related item in an order. Verify the shipping-price-adj , shipping-tax-adj , and ship-promotion-adj values in the template. |
base component is only provided and tax is missing for component Shipping | Invalid item-tax-adj or shipping-tax-adj field | There is an issue with the tax calculation for a shipping component in your system. item-tax-adj or shipping-tax-adj is missing in the template. Verify these fields. |
Order ID missing for refund | Missing order-id field | Verify the order-id field. |
Invalid amount issued for promotion | Invalid item-promotion-adj , item-promotion-id , ship-promotion-adj , or ship-promotion-id field | The fields related to price and promotion might be invalid. Re-verify these fields. |
Invalid OrderID or AmazonOrderID | Invalid order-id field | Verify the order-id . |
Could not issue refund because there are several returns associated to return item in order | The provided order is invalid for refund as there are multiple returns associated with this order | Re-verify the order. |
Invalid amount issued for refund item for base component (?!Shipping) | Invalid shipping-price-adj or shipping-tax-adj | Re-verify the shipping-price-adj and shipping-tax-adj fields in the template. |
Note
A refund can still be denied after a successful submission if certain issues arise, such as buyer abuse or the use of an invalid payment method.
Best practices
For best practices using the Feeds API, refer to Feeds API Best Practices.
Updated about 1 month ago