Operations in Amazon E-Commerce Service (ECS) take a variety of parameters. The parameters that are common to all operations, for both SOAP and REST, are listed below.
The parameters in the table below are required for every ECS operation request.
Required parameters for every ECS operation
| Parameter | Value | Description |
|---|---|---|
| Service | AWSECommerceService | Specifies the ECS service |
| AWSAccessKeyId | Your Amazon-assigned Access Key ID | You can register for an Access Key ID from the Amazon Web site if you do not have one. Every ECS 4.0 request must contain either an Access Key ID or a Subscription ID but not both. |
| SubscriptionId | Your Amazon-assigned subscription ID | Every ECS 4.0 request must contain either an Access Key ID or a Subscription ID but not both. Starting with version 2006-03-08, ECS stopped distributing Subscription IDs. If you already have one, it will continue to work. |
| Operation | Operation you wish to perform | One of the ECS operation types. |
| Version | Version of ECS 4.0 WSDL | This parameter is optional, The default is 2005-10-05. If you want another version, including the latest, you must specify it in your request. |
General parameters that are optional to any ECS request
| Parameter | Value | Description |
|---|---|---|
| Marketplace | Reserved for future use. | |
| AssociateTag | An Amazon-assigned Associate tag | Use the AssociateTag parameter to specify your Associate ID. The AssociateTag allows product URLs returned by ECS to be tagged as originating from your Associates Web site. Be sure to specify the tag value correctly, as no error is generated for incorrect tag values. If you use those product URLs to link to Amazon, the Associate account connected to the AssociateTag you specify will be credited for traffic and items sold through your links. Since you do not need to be an Associate to use ECS, AssociateTag is not a required parameter. If you do not include AssociateTag in your requests, a default Associate tag will be embedded in the product URLs in ECS responses. |
| MerchantId | An alphanumeric identity assigned by Amazon to a merchant. | Use the MerchantId parameter to specify one or more merchants. MerchantId is an alphanumeric identity that specifies a merchant. It can have three settings: All, in which all merchants are included in the response, an alphanumeric identity that specifies a single merchant, or FeaturedBuyBoxMerchant, which returns the merchant identified as the “Buy Box Winner” on a specific detail page. The "Buy Box Winner" is the merchant associated with the sale of the item listed in the Buy Box, which is the box on an item's detail page that enables you to add an item to a shopping cart. The default value for MerchantId is “Amazon.” |
| ResponseGroup | Specifies what data is to be returned by the current operation; allows you to control the volume and content of returned data. For details about using ResponseGroup with each operation, check the operation pages. |
If you are using an XSL stylesheet to specify the output you want returned by ECS, you may need to include the following (optional) parameters:
| Parameter | Value | Description |
|---|---|---|
| Style | Default Value: XML Valid Values: XML A URL to a stylesheet | The Style parameter applies to REST requests only. Use the Style parameter to control the format of the data returned by ECS in REST responses. Set this parameter to "XML" to generate a pure XML response. Set this parameter to the URL of an XSLT stylesheet to have ECS transform the XML response to another format you specify. If you omit this parameter, ECS will return a pure XML response by default. |
| ContentType | Default Value: text/xml Valid Values: text/xml, text/html | The ContentType parameter is valid for REST requests only. The ContentType set in your request is returned as the content type in the HTTP headers of the response that ECS returns. Generally ContentType should only be changed when it is being used in conjunction with an XSLT stylesheet specified with the Style parameter. When you use a stylesheet to transform your ECS response to HTML, set this parameter to text/html. |
| Version | A WSDL Namespace date |
For REST requests, use the Version parameter to retrieve a particular version of the ECS WSDL. The value of the Version parameter is the date that is part of the WSDL's namespace. For example, if the namespace is http://webservices.amazon.com/AWSECommerceService/2006-03-08/ AWSECommerceService.wsdl then you should set the Version parameter to 2006-03-08. Each time changes are made to ECS (for example, changed operation parameters, response groups, or behavior), a new WSDL is created with a new date. For SOAP requests, this parameter is ignored because the version is retrieved from the WSDL namespace. If the Version parameter is omitted in a REST request, ECS uses the default namespace. The default namespace may change as new versions of ECS are released. If you use XSLT to transform ECS output, you should use the Version parameter to ensure that your stylesheets continue to work correctly when the default namespace is changed. |
Another optional parameter is provided, that you may need in some environments:
| Parameter | Value | Description |
|---|---|---|
| XMLEscaping | Default Value: Single Valid Values: Single, Double | Use the XMLEscaping parameter to specify whether responses are XML-encoded in a single pass or a double pass. By default, XMLEscaping is Single, and ECS responses are encoded only once in XML. For example, if the response data includes an ampersand character (&), the character is returned in its regular XML encoding (&). If XMLEscaping is Double, the same ampersand character is XML-encoded twice (&). The Double value for XMLEscaping is useful in some clients, such as PHP, that do not decode text within XML elements. |
For help in debugging, you may want to use this optional parameter:
| Parameter | Value | Description |
|---|---|---|
| Validate | True | Use the Validate parameter to have ECS test your request without actually executing it. If this parameter is not specified, the default value is False (i.e., requests are executed normally). When present, Validate must equal True. If the request is valid, the response will contain an element called IsValid with a value of True. If the request is invalid, the response will contain 1) an element called IsValid with a value of False and 2) the errors that would be returned if the request were actually executed. Notes: Since the request is not actually executed, only a subset of the errors for the request may be returned. This is because some errors (e.g., no_exact_matches) are only generated during execution of a request. The IsValid element will always be present in any response, regardless of whether the Validate parameter was in the request. |
We also recommend that you include the Request response group for help with debugging. The Request response group echoes back the parameters used to generate the response and allows you to verify that your request was received correctly.