Amazon E-Commerce Service (ECS) requires that you make only one request per second. To assist you with maximizing your results in a minimum number of requests, ECS provides two ways to combine requests.
Batch requests - multiple requests for the same operation can be combined in one request; for example, you might combine a search for books and a search for DVDs into a single request.
Multi-Operation requests - multiple different operations can be combined into a single request; for example, you might do a product lookup and search for products in a single request.
Note:
The limit for batch requests and multi-operation requests is currently two.
Errors in batch or multi-operation requests require special handling, as described below.
A batch request allows you to combine requests (or sub-requests) for the same operation into one single request to ECS. Batch requests allow you to share parameters across each of the sub-requests, so that you do not have to include redundant parameters values in your sub-requests. For example, if you want to search for books and DVDs with titles containing "dog", you may include the Title parameter with the value of "dog" in the request's shared parameters and avoid repeating the parameter in both sub-requests.
To create a batch request:
Assemble the standard operation parameters: Service, Operation, AWSAccessKeyId, AssociateTag (optional). For batch operations, these parameters are the same for both sub-operation requests.
Assemble the shared parameters. For example, if both requests were to search for books, then both might require the SearchIndex parameter to be set to Books.
Assemble the parameters specific to the first request. For example, building on the books search example, you could include the Author parameter and set it to "Larson".
Assemble the parameters specific to the second request. For example, you could include the Title parameter and set it to "Horton Hears".
Here's a REST request for the example described above:
REST Examples [Show]
See the following sections for more information about how to structure REST and SOAP requests.
For batch requests, REST parameter definitions have been extended as shown in the table below to permit the specification of the parameters for both operations.
Operation parameters for batch requests (REST)
| Parameter | Description |
|---|---|
| Parameters that Specify the Batch Operation | Parameters that specify the batch operation. The only parameters that are treated this way in batch requests are the required parameters Service, Operation, and AWSAccessKeyId and the optional parameter AssociateTag. |
| Operation.1.Parameter | Parameters for the first request. Standard operations and parameters are permitted here. For example, ItemSearch.1.Keywords or SellerLookup.1.SellerId. |
| Operation.2.Parameter | Parameters for the second request. Standard operations and parameters are permitted here. For example, ItemSearch.2.Keywords or SellerLookup.2.SellerId. |
| Operation.Shared.Parameter | Parameters that are common to both requests. Standard operations and parameters are permitted here. For example, ItemSearch.Shared.Keywords or SellerLookup.Shared.ResponseGroup. |
For example, if you wanted to do two ItemLookup operations, one for an ASIN and another for a SKU, with the results formatted via the same XSL stylesheet, you might use the following parameters in a REST request:
Example of parameters for a batched request for ItemLookup
| Parameter | Value |
|---|---|
| Operation | ItemLookup |
| ItemLookup.1.IdType | ASIN |
| ItemLookup.1.ItemId | [ASIN to search for] |
| ItemLookup.2.IdType | SKU |
| ItemLookup.2.ItemId | [SKU to search for] |
| ItemLookup.2.MerchantId | [Merchant ID associated with SKU] |
| ItemLookup.2.SearchIndex | SportingGoods |
| ItemLookup.Shared.Style | [XSL style sheet to use for both requests] |
| ItemLookup.Shared.ResponseGroup | Small,Offers |
For SOAP batch operations are implemented by including a Request element for parameters that are specific to the first and second requests.
Shared parameters are contained inside a Shared element.
Multi-operation requests allow you to specify multiple operations in a single request. It's important to note that the requests are accepted and executed in parallel and are not chained. More specifically, if the first request is a search, the results of the search cannot be fed into the second request.
For multi-operation requests, as for batch requests, REST parameter definitions have been extended to permit the specification of the parameters for both operations.
The types of operation required are specified as a comma-separated list to the Operation parameter:
Operation=Operation1,Operation2
For example,
Operation=ItemLookup,ListSearch
would specify that the first operation was an ItemLookup and the second was a ListSearch.
You must specify the parameters for the first request in the form Operation1.1.parameter and for the second request in the form Operation2.1.parameter. For example, if the operations are
Operation=ItemLookup,ItemSearch
then the parameters are specified as ItemLookup.1.parameter and ItemSearch.1.parameter.
For example, if you wanted to do an ItemLookup and a ListSearch operation, you might use the following parameters in a REST request:
Example of parameters for a multi-operation request for an ItemLookup and a ListSearch operations (REST)
| Parameter | Value |
|---|---|
| Operation | ItemLookup,ListSearch |
| ItemLookup.1.IdType | ASIN |
| ItemLookup.1.ItemId | [ASIN to search for] |
| ItemLookup.1.ResponseGroup | Request,Medium,Variations |
| ListSearch.1.ListType | WeddingRegistry |
| ListSearch.1.Name | [Name to search for] |
When requests are combined in a single request, there can be two types of errors:
| Type of error | Result |
|---|---|
| Syntax error in the request (e.g., an invalid response group or a mis-spelled parameter) | The request will be rejected and neither operation will be completed. |
| Validly formed request that returns no data (e.g., a keyword is mis-spelled) | The return data will show the error block for the operation with the error and the return data for the other operation. |