Amazon Product Advertising API 5.0

https://webservices.amazon.com/paapi5/documentation
Admin
Amazon Product Advertising API 5.0 is a web service that provides access to Amazon's product data...
Tokens:98,858
Snippets:808
Trust Score:9.9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Python Dependencies

Source: https://webservices.amazon.com/paapi5/documentation/quick-start/using-sdk.html

Install Python SDK dependencies locally using the provided setup script. This command installs the package and its dependencies.

```bash
sudo python setup.py install
```

--------------------------------

### GetBrowseNodes Request Example - Marketplace

Source: https://webservices.amazon.com/paapi5/documentation/getbrowsenodes.html

Example of how to specify the target Marketplace for a GetBrowseNodes request.

```json
{"Marketplace":"www.amazon.com"}
```

--------------------------------

### Install Node.js Dependencies

Source: https://webservices.amazon.com/paapi5/documentation/quick-start/using-sdk.html

Before running Node.js samples, install all project dependencies using npm. This ensures all required modules are available in the node_modules folder.

```bash
npm install
```

--------------------------------

### Example Request for SearchRefinements

Source: https://webservices.amazon.com/paapi5/documentation/search-refinements.html

An example request to the SearchRefinements resource for the US marketplace within the 'All' category, searching for 'Harry Potter'.

```json
{
   "PartnerTag": "xyz-20",
   "PartnerType": "Associates",
   "ItemCount": 1,
   "Keyword": "Harry Potter",
   "Resources" : [ "SearchRefinements" ]
}
```

--------------------------------

### GetVariations - Pagination Example

Source: https://webservices.amazon.com/paapi5/documentation/get-variations.html

This example demonstrates how to get the next set of variations using the VariationPage parameter when the total number of variations exceeds the default page size.

```APIDOC
## POST /v1/variations/get (with VariationPage)

### Description
Get next set of variations for an ASIN using VariationPage parameter.

### Method
POST

### Endpoint
/v1/variations/get

### Parameters
#### Request Body
- **ASIN** (string) - Required - The ASIN of the product.
- **Resources** (array of strings) - Required - A list of resources to retrieve for the variations.
- **VariationPage** (integer) - Optional - Specifies the page number of variations to retrieve. Use this to paginate through results.
- **PartnerTag** (string) - Required - Your Amazon Associates tag.
- **PartnerType** (string) - Required - The type of partner (e.g., "Associates").
- **Marketplace** (string) - Required - The marketplace ID (e.g., "www.amazon.co.uk").
- **Operation** (string) - Required - The operation to perform, must be "GetVariations".

### Request Example
```json
{
 "ASIN": "B00422MCUS",
 "Resources": [
  "ItemInfo.Title",
  "VariationSummary.Price.HighestPrice",
  "VariationSummary.Price.LowestPrice",
  "VariationSummary.VariationDimension"
 ],
 "VariationPage": 2,
 "PartnerTag": "xyz-20",
 "PartnerType": "Associates",
 "Marketplace": "www.amazon.co.uk",
 "Operation": "GetVariations"
}
```

### Response
#### Success Response (200)
- **VariationsResult** (object) - Contains the results of the GetVariations operation.
  - **Items** (array of objects) - A list of variation items for the specified page.
  - **VariationSummary** (object) - Summary information about the variations, including total page count.

#### Response Example
```json
{
 "VariationsResult": {
  "Items": [
   {
    "ASIN": "B075TFCB3R",
    "DetailPageURL": "https://www.amazon.co.uk/dp/B075TFCB3R?tag=xyz-20&linkCode=ogv&th=1&psc=1",
    "ItemInfo": {
     "Title": {
      "DisplayValue": "Tommy Hilfiger Men's RFID Blocking 100% Leather Ranger Passcase Wallet Bi-Fold, Navy/Black, One Size",
      "Label": "Title",
      "Locale": "en_GB"
     }
    },
    "VariationAttributes": [
     {
      "Name": "size_name",
      "Value": "One Size"
     },
     {
      "Name": "color_name",
      "Value": "Navy/Black"
     }
    ]
   },
   {
    "ASIN": "B0743JLQKT",
    "DetailPageURL": "https://www.amazon.co.uk/dp/B0743JLQKT?tag=xyz-20&linkCode=ogv&th=1&psc=1",
    "ItemInfo": {
     "Title": {
      "DisplayValue": "Tommy Hilfiger Men's Ranger Leather Passcase Wallet, Gray",
      "Label": "Title",
      "Locale": "en_GB"
     }
    },
    "VariationAttributes": [
     {
      "Name": "size_name",
      "Value": "One Size"
     },
     {
      "Name": "color_name",
      "Value": "Gray"
     }
    ]
   },
   {
    "ASIN": "B0743JL719",
    "DetailPageURL": "https://www.amazon.co.uk/dp/B0743JL719?tag=xyz-20&linkCode=ogv&th=1&psc=1",
    "ItemInfo": {
     "Title": {
      "DisplayValue": "Tommy Hilfiger Men's Ranger Leather Passcase Wallet, Burgundy",
      "Label": "Title",
      "Locale": "en_GB"
     }
    },
    "VariationAttributes": [
     {
      "Name": "size_name",
      "Value": "One Size"
     },
     {
      "Name": "color_name",
      "Value": "Burgundy"
     }
    ]
   }
  ],
  "VariationSummary": {
   "PageCount": 2,
   "Price": {
    "HighestPrice": {
     "Amount": 30.87,
     "Currency": "GBP",
     "DisplayAmount": "£30.87"
    },
    "LowestPrice": {
     "Amount": 17.03,
     "Currency": "GBP",
     "DisplayAmount": "£17.03"
    }
   },
   "VariationCount": 13,
   "VariationDimensions": [
    {
     "DisplayName": "Size",
     "Name": "size_name",
     "Values": [
      "One Size"
     ]
    },
    {
     "DisplayName": "Colour",
     "Name": "color_name",
     "Values": [
      "Brown",
      "Navy",
      "Black",
      "Burgundy",
      "Cognac",
      "Gray",
      "Green",
      "Logan - Tan",
      "Navy/Black",
      "Red",
      "Rfid-black",
      "Rfid-navy",
      "Tan"
     ]
    }
   ]
  }
 }
}
```
```

--------------------------------

### Example PHP Snippet

Source: https://webservices.amazon.com/paapi5/documentation/play-around-using-scratchpad.html

This is an example of a PHP snippet generated by the Scratchpad. It can be used to integrate with the Product Advertising API.

```php
<?php

require_once __DIR__ . '/vendor/autoload.php';

use Amazon
extProps
est	ypes\*;
use Amazon\nextProps\rest\api\*;

// Configure API key authorization: APIKeyAuth
// ... (API Key configuration omitted for brevity)

$api = new DefaultApi();

try {
    $searchItemsRequest = new SearchItemsRequest();
    $searchItemsRequest->setPartnerTag('your-partner-tag-20');
    $searchItemsRequest->setPartnerId('your-partner-id');
    $searchItemsRequest->setMarketplace('US');
    $searchItemsRequest->setOperation('SearchItems');
    $searchItemsRequest->setSourceEnvironment('us.amazon-adsystem.com');

    $itemIds = new ItemIds();
    $itemIds->setItemIds(['B08H75RTZ8']);
    $searchItemsRequest->setItemIds($itemIds);

    // Add other parameters as needed, e.g., Resources
    $searchItemsRequest->setResources([Resources::ITEM_INFO_TITLE, Resources::OFFERS_LISTINGS]);

    $result = $api->searchItems($searchItemsRequest);

    print_r($result);

} catch (ApiException $e) {
    echo 'Error calling PA-API: ' . $e->getMessage() . PHP_EOL;
    print_r($e->getTrace());
}

?>
```

--------------------------------

### GetVariations Example

Source: https://webservices.amazon.com/paapi5/documentation/get-variations.html

Example of how to request variations for a parent ASIN.

```APIDOC
## POST /api/v1/variations

### Description
Get variations for a parent ASIN.

### Method
POST

### Endpoint
/api/v1/variations

### Request Body
- **ASIN** (string) - Required - The parent ASIN.
- **Resources** (array of strings) - Required - List of resources to retrieve.
- **VariationPage** (integer) - Optional - The page number for variations.
- **PartnerTag** (string) - Required - Your partner tag.
- **PartnerType** (string) - Required - Your partner type.
- **Marketplace** (string) - Required - The marketplace ID.
- **Operation** (string) - Required - The operation type, e.g., "GetVariations".

### Request Example
```json
{
 "ASIN": "B00422MCUS",
 "Resources": [
  "ItemInfo.Title",
  "VariationSummary.Price.HighestPrice",
  "VariationSummary.Price.LowestPrice",
  "VariationSummary.VariationDimension"
 ],
 "VariationPage": 1,
 "PartnerTag": "xyz-20",
 "PartnerType": "Associates",
 "Marketplace": "www.amazon.co.uk",
 "Operation": "GetVariations"
}
```

### Response
#### Success Response (200)
- **VariationsResult** (object) - Container for variations result.
  - **Items** (array) - Container for item information.
  - **VariationSummary** (object) - Container for VariationSummary resource.

#### Response Example
```json
{
 "VariationsResult": {
  "Items": [
   {
    "ASIN": "B00422MCUS",
    "ItemInfo": {
     "Title": {
      "DisplayValue": "Example Product Title"
     }
    },
    "VariationSummary": {
     "Price": {
      "HighestPrice": {
       "Amount": "19.99",
       "Currency": "USD"
      },
      "LowestPrice": {
       "Amount": "15.99",
       "Currency": "USD"
      }
     },
     "VariationDimension": [
      {
       "Name": "Color",
       "Values": ["Red", "Blue"]
      }
     ]
    }
   }
  ]
 }
}
```
```

--------------------------------

### Example Response with SearchIndexes

Source: https://webservices.amazon.com/paapi5/documentation/search-refinements.html

An example response containing SearchRefinements, specifically showing SearchIndexes for a search in the US marketplace for 'Harry Potter'. The most relevant search indexes are listed first.

```json
{
  "SearchResult": {
    "Items": [
      {
        "ASIN": "0545162076",
        "DetailPageURL": "https://www.amazon.com/dp/0545162076?tag=dgfd&linkCode=osi&th=1&psc=1"
      }
    ],
    "SearchRefinements": {
      "SearchIndex": {
        "Id": "SearchIndex",
        "DisplayName": "Department",
        "Bins": [
          {
            "Id": "Books",
            "DisplayName": "Books"
          },
          {
            "Id": "MoviesAndTV",
            "DisplayName": "Movies & TV"
          },
          {
            "Id": "Fashion",
            "DisplayName": "Clothing, Shoes & Jewelry"
          },
          {
            "Id": "HomeAndKitchen",
            "DisplayName": "Home & Kitchen"
          },
          {
            "Id": "Beauty",
            "DisplayName": "Beauty & Personal Care"
          }
          / * More relevant Search Indexes */
        ]
      }
    },
    "SearchURL": "https://www.amazon.com/s/?field-keywords=Harry+Potter&search-alias=aps&tag=xyz-20&linkCode=osi",
    "TotalResultCount": 146
  }
}
```

--------------------------------

### GetBrowseNodes Request Example - Resources

Source: https://webservices.amazon.com/paapi5/documentation/getbrowsenodes.html

Example of how to specify multiple Resources in a GetBrowseNodes request to retrieve both ancestor and children browse node information.

```json
{"Resources":["BrowseNodes.Ancestor", "BrowseNodes.Children"]}
```

--------------------------------

### GetBrowseNodes Request Example - PartnerTag

Source: https://webservices.amazon.com/paapi5/documentation/getbrowsenodes.html

Example of how to specify the PartnerTag in a GetBrowseNodes request. This is a required parameter.

```json
{"PartnerTag":"xyz-20"}
```

--------------------------------

### GetBrowseNodes Request Example - PartnerType

Source: https://webservices.amazon.com/paapi5/documentation/getbrowsenodes.html

Example of how to specify the PartnerType in a GetBrowseNodes request. This is a required parameter.

```json
{"PartnerType":"Associates"}
```

--------------------------------

### Example HTTP Request Header for SearchItems

Source: https://webservices.amazon.com/paapi5/documentation/sending-request.html

This is an example of a complete HTTP request header for a SearchItems operation. Ensure all header keys and values are case-sensitive and match the required format.

```http
POST / HTTP/1.1
host: webservices.amazon.com
content-type: application/json; charset=utf-8
content-encoding: amz-1.0
x-amz-date: 20160925T120000Z
x-amz-target: com.amazon.paapi5.v1.ProductAdvertisingAPIv1.SearchItems
Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE, SignedHeaders=content-type;host;x-amz-date;x-amz-target, Signature=&5d672d79c15b13162d9279b0855cfba6789a8edb4c82c400e06b5924a6f2b5d7;
```

--------------------------------

### Example Java Snippet

Source: https://webservices.amazon.com/paapi5/documentation/play-around-using-scratchpad.html

This is an example of a Java snippet generated by the Scratchpad. It can be used to integrate with the Product Advertising API.

```java
import java.math.BigDecimal;
import java.time.Instant;
import java.util.ArrayList;

import com.amazon.paapi5.v1.api.DefaultApi;
import com.amazon.paapi5.v1.Configuration;
import com.amazon.paapi5.v1.model.*;
import com.amazon.paapi5.v1.ApiException;
import com.amazon.paapi5.v1.serializer.Serializer;

public class SearchItems {

    public static void main(String[] args) {
        // Configure API key authorization: APIKeyAuth
        // ... (API Key configuration omitted for brevity)

        DefaultApi api = new DefaultApi();

        try {
            SearchItemsRequest searchItemsRequest = new SearchItemsRequest();
            searchItemsRequest.setPartnerTag("your-partner-tag-20");
            searchItemsRequest.setPartnerId("your-partner-id");
            searchItemsRequest.setMarketplace("US");
            searchItemsRequest.setOperation("SearchItems");
            searchItemsRequest.setSourceEnvironment("us.amazon-adsystem.com");

            ItemIds itemIds = new ItemIds();
            itemIds.setItemIds(java.util.Arrays.asList("B08H75RTZ8"));
            searchItemsRequest.setItemIds(itemIds);

            // Add other parameters as needed, e.g., Resources
            searchItemsRequest.setResources(java.util.Arrays.asList(Resources.ITEM_INFo_TITLE, Resources.OFFERS_LISTINGS));

            SearchItemsResponse result = api.searchItems(searchItemsRequest);

            System.out.println("API Response: " + Serializer.toJson(result));

        } catch (ApiException e) {
            System.err.println("Error calling PA-API: " + e.getMessage());
            e.printStackTrace();
        }
    }
}
```

--------------------------------

### GetItems Request Example

Source: https://webservices.amazon.com/paapi5/documentation/get-items.html

Sample JSON payload for a GetItems request, demonstrating required and optional parameters.

```APIDOC
## GetItems Request Example

### Description
The following is the sample json payload for `GetItems` request.

### Request Example
```json
{
  "ItemIds": ["B0199980K4","B000HZD168","B01180YUXS","B00BKQTA4A"],
  "ItemIdType": "ASIN",
  "LanguagesOfPreference": ["en_US"],
  "Marketplace": "www.amazon.com",
  "PartnerTag": "xyz-20",
  "PartnerType": "Associates",
  "Resources": ["Images.Primary.Small","ItemInfo.Title","ItemInfo.Features",
"Offers.Summaries.HighestPrice","ParentASIN"]
}
```
```

--------------------------------

### GetBrowseNodes Request Example - LanguagesOfPreference

Source: https://webservices.amazon.com/paapi5/documentation/getbrowsenodes.html

Example of how to specify LanguagesOfPreference in a GetBrowseNodes request. Only a single language is currently supported.

```json
{"LanguagesOfPreference":["en_US"]}
```

--------------------------------

### GetBrowseNodes Request Example - BrowseNodeIds

Source: https://webservices.amazon.com/paapi5/documentation/getbrowsenodes.html

Example of how to specify BrowseNodeIds in a GetBrowseNodes request. Multiple IDs can be provided.

```json
{"BrowseNodeIds": ["3040", "3045"]}
```

--------------------------------

### Example cURL Snippet

Source: https://webservices.amazon.com/paapi5/documentation/play-around-using-scratchpad.html

This is an example of a cURL snippet generated by the Scratchpad. It can be copied and pasted into a terminal to see the API response.

```bash
curl "https://webservices.amazon.com/paapi5/searchitems? партнертаг=ваша партнерская метка-20& маркетплейс=US& партнертип=Ваш тип партнера& операцию=SearchItems& ключа доступа=ВАШ КЛЮЧ ДОСТУПА& секретный ключ=ВАШ СЕКРЕТНЫЙ КЛЮЧ& itemids=B08H75RTZ8"
```

--------------------------------

### GetVariations - Initial Request

Source: https://webservices.amazon.com/paapi5/documentation/get-variations.html

This example shows an initial request to the GetVariations operation to retrieve variation information for a given ASIN.

```APIDOC
## POST /v1/variations/get

### Description
Retrieves variation information for a given ASIN. This is the initial request to get the first set of variations.

### Method
POST

### Endpoint
/v1/variations/get

### Request Body
- **ASIN** (string) - Required - The Amazon Standard Identification Number (ASIN) of the product.
- **Resources** (array of strings) - Required - A list of resources to retrieve for the variations.
- **PartnerTag** (string) - Required - Your Amazon Associates tag.
- **PartnerType** (string) - Required - The type of partner (e.g., "Associates").
- **Marketplace** (string) - Required - The marketplace ID (e.g., "www.amazon.co.uk").
- **Operation** (string) - Required - The operation to perform, must be "GetVariations".

### Request Example
```json
{
  "ASIN": "B01MG81M6E",
  "Resources": [
    "ItemInfo.Title",
    "VariationSummary.Price.HighestPrice",
    "VariationSummary.Price.LowestPrice",
    "VariationSummary.VariationDimension"
  ],
  "PartnerTag": "xyz-20",
  "PartnerType": "Associates",
  "Marketplace": "www.amazon.co.uk",
  "Operation": "GetVariations"
}
```

### Response
#### Success Response (200)
- **VariationsResult** (object) - Contains the results of the GetVariations operation.
  - **Items** (array of objects) - A list of variation items.
  - **VariationSummary** (object) - Summary information about the variations.

#### Response Example
```json
{
 "VariationsResult": {
  "Items": [
   {
    "ASIN": "B01MG81M6E",
    "DetailPageURL": "https://www.amazon.co.uk/dp/B01MG81M6E?tag=xyz-20&linkCode=ogv&th=1&psc=1",
    "ItemInfo": {
      "Title": {
        "DisplayValue": "Tommy Hilfiger Men's Ranger Leather Passcase Wallet with Removable Card Holder,Green,One Size",
        "Label": "Title",
        "Locale": "en_GB"
      }
    },
    "VariationAttributes": [
      {
        "Name": "size_name",
        "Value": "One Size"
      },
      {
        "Name": "color_name",
        "Value": "Green"
      }
    ]
   },
   {
    "ASIN": "B0731XHR2W",
    "DetailPageURL": "https://www.amazon.co.uk/dp/B0731XHR2W?tag=xyz-20&linkCode=ogv&th=1&psc=1",
    "ItemInfo": {
      "Title": {
        "DisplayValue": "Tommy Hilfiger mens Ranger Passcase Wallet Wallet - Blue -",
        "Label": "Title",
        "Locale": "en_GB"
      }
    },
    "VariationAttributes": [
      {
        "Name": "size_name",
        "Value": "One Size"
      },
      {
        "Name": "color_name",
        "Value": "Rfid-navy"
      }
    ]
   }
  ],
  "VariationSummary": {
    "PageCount": 2,
    "Price": {
      "HighestPrice": {
        "Amount": 30.87,
        "Currency": "GBP",
        "DisplayAmount": "£30.87"
      },
      "LowestPrice": {
        "Amount": 17.03,
        "Currency": "GBP",
        "DisplayAmount": "£17.03"
      }
    },
    "VariationCount": 13,
    "VariationDimensions": [
      {
        "DisplayName": "Size",
        "Name": "size_name",
        "Values": [
          "One Size"
        ]
      },
      {
        "DisplayName": "Colour",
        "Name": "color_name",
        "Values": [
          "Brown",
          "Navy",
          "Black",
          "Burgundy",
          "Cognac",
          "Gray",
          "Green",
          "Logan - Tan",
          "Navy/Black",
          "Red",
          "Rfid-black",
          "Rfid-navy",
          "Tan"
        ]
      }
    ]
  }
 }
}
```
```

--------------------------------

### Example of SearchRefinements Response

Source: https://webservices.amazon.com/paapi5/documentation/use-cases/using-searchrefinements/using-dynamic-refinements.html

This is an example of the 'SearchRefinements' container in the API response, showing 'OtherRefinements' with 'Id', 'DisplayName', and 'Bins'. The 'Id' of a bin is used for subsequent filtering.

```json
"SearchRefinements": {
   "OtherRefinements": [
    {
     "Id": "Author",
     "DisplayName": "Author",
     "Bins": [
      {
       "DisplayName": "Ray Yao",
       "Id": "Ray Yao"
      },
      {
       "DisplayName": "Herbert Schildt",
       "Id": "Herbert Schildt"
      },
      {
       "DisplayName": "P.J. Deitel",
       "Id": "P.J. Deitel"
      },
      {
       "DisplayName": "H.M. Deitel",
       "Id": "H.M. Deitel"
      },
      {
       "DisplayName": "Jeanne Boyarsky",
       "Id": "Jeanne Boyarsky"
      },
      {
       "DisplayName": "John Lewis",
       "Id": "John Lewis"
      },
      {
       "DisplayName": "Nancy Krulik",
       "Id": "Nancy Krulik"
      }
     ]
    }
   ]
  }
```

--------------------------------

### GetVariations Resources Parameter Example

Source: https://webservices.amazon.com/paapi5/documentation/get-variations.html

Specifies the types of values to return in the response. Multiple resources can be requested. This parameter is optional.

```json
"Resources" : [ "Images.Primary.Small", "ItemInfo.ProductInfo"]
```

--------------------------------

### Sample Request Payload

Source: https://webservices.amazon.com/paapi5/documentation/sending-request.html

An example of a JSON request payload for the Product Advertising API.

```APIDOC
## Sample Request Payload

### Description
This is a sample JSON request payload that can be used with the Product Advertising API.

### Request Body
- **Keywords** (string) - Required - The keywords to search for.
- **Marketplace** (string) - Required - The marketplace to search within (e.g., `www.amazon.com`).
- **PartnerTag** (string) - Required - Your Amazon Associates Tag.
- **PartnerType** (string) - Required - Your Partner Type (e.g., `Associates`).
- **Resources** (array of strings) - Required - A list of resources to retrieve (e.g., `["Images.Primary.Small","ItemInfo.Title","Offers.Listings.Price"]`).
- **SearchIndex** (string) - Required - The search index to use (e.g., `All`).

### Request Example
```json
{
  "Keywords": "Harry",
  "Marketplace": "www.amazon.com",
  "PartnerTag": "xyz-20",
  "PartnerType": "Associates",
  "Resources": ["Images.Primary.Small","ItemInfo.Title","Offers.Listings.Price"],
  "SearchIndex": "All"
}
```
```

--------------------------------

### GetVariations OfferCount Parameter Example

Source: https://webservices.amazon.com/paapi5/documentation/get-variations.html

Specifies the number of offers desired for each item. Currently, only a value of 1 is supported. This parameter is optional.

```json
{"OfferCount":1}
```

--------------------------------

### Run Java Sample

Source: https://webservices.amazon.com/paapi5/documentation/quick-start/using-sdk.html

To run a Java sample, download the SDK, add all necessary JAR files from the dependencies folder to your build path, and then execute the sample code.

```text
Run code samples like _SampleGetItemsApi.java_.
```

--------------------------------

### Run PHP Sample

Source: https://webservices.amazon.com/paapi5/documentation/quick-start/using-sdk.html

To run a PHP sample, ensure you have downloaded the SDK, added your credentials and partner tag to the sample files, and then execute the script using the PHP command-line interpreter.

```bash
php SampleGetItemsApi.php
```

--------------------------------

### Get Browse Node Information Response

Source: https://webservices.amazon.com/paapi5/documentation/getbrowsenodes.html

Example response for a GetBrowseNodes request, showing detailed information for valid browse nodes, including their ancestors and children.

```json
{
  "BrowseNodesResult": {
    "BrowseNodes": [
      {
        "Ancestor": {
          "Ancestor": {
            "Ancestor": {
              "Ancestor": {
                "Ancestor": {
                  "ContextFreeName": "Books",
                  "DisplayName": "Books",
                  "Id": "283155"
                },
                "ContextFreeName": "Subjects",
                "DisplayName": "Subjects",
                "Id": "1000"
              },
              "ContextFreeName": "Children's Books",
              "DisplayName": "Children's Books",
              "Id": "4"
            },
            "ContextFreeName": "Children's Geography & Cultures Books",
            "DisplayName": "Geography & Cultures",
            "Id": "3344091011"
          },
          "ContextFreeName": "Children's Explore the World Books",
          "DisplayName": "Explore the World",
          "Id": "3023"
        },
        "ContextFreeName": "Children's Mexico Books",
        "DisplayName": "Mexico",
        "Id": "3040",
        "IsRoot": false
      },
      {
        "Children": [
          {
            "ContextFreeName": "Subjects",
            "DisplayName": "Subjects",
            "Id": "1000"
          },
          {
            "ContextFreeName": "Books Featured Categories",
            "DisplayName": "Books Featured Categories",
            "Id": "51546011"
          },
          {
            "ContextFreeName": "Specialty Boutique",
            "DisplayName": "Specialty Boutique",
            "Id": "2349030011"
          }
        ],
        "ContextFreeName": "Books",
        "DisplayName": "Books",
        "Id": "283155",
        "IsRoot": true
      }
    ]
  }
}
```

--------------------------------

### Run Node.js Sample

Source: https://webservices.amazon.com/paapi5/documentation/quick-start/using-sdk.html

To run a Node.js sample, after installing dependencies, add your credentials and partner tag to the sample files, and then execute the script using the Node.js runtime.

```bash
node sampleGetItemsApi.js
```

--------------------------------

### Get Parent ASIN

Source: https://webservices.amazon.com/paapi5/documentation/parent-asin.html

This example demonstrates how to retrieve the parent ASIN for a specific item using the ParentASIN resource. The PA-API is deprecated and will be replaced by Creators API.

```APIDOC
## POST /parent-asin

### Description
Retrieves the parent ASIN for a given item. This is useful for understanding product variations.

### Method
POST

### Endpoint
/parent-asin

### Request Body
- **AssociateTag** (string) - Required - Your Amazon Associate Tag.
- **ItemIds** (array of strings) - Required - A list of item IDs (ASINs) for which to retrieve the parent ASIN.
- **Resources** (array of strings) - Required - Specifies the resources to retrieve. Must include "ParentASIN".

### Request Example
```json
{
  "AssociateTag": "xyz-20",
  "ItemIds": ["B00TSUGXKE"],
  "Resources": ["ParentASIN"]
}
```

### Response
#### Success Response (200)
- **ASIN** (string) - The ASIN of the item.
- **ParentASIN** (string) - The parent ASIN of the item.

#### Response Example
```json
{
  "ASIN": "B00TSUGXKE",
  "ParentASIN": "B010BWYDYA"
}
```
```

--------------------------------

### Run Python Sample

Source: https://webservices.amazon.com/paapi5/documentation/quick-start/using-sdk.html

To run a Python sample, after installing dependencies, add your credentials and partner tag to the sample files, and then execute the script using the Python interpreter.

```bash
python sample_get_items_api.py
```

--------------------------------

### Get Variations for a Parent ASIN

Source: https://webservices.amazon.com/paapi5/documentation/get-variations.html

This example shows a JSON payload for retrieving variation information for a parent ASIN. It specifies the ASIN, desired resources, and pagination details.

```json
{
  "ASIN": "B01MG81M6E",
  "Resources": [
    "ItemInfo.Title",
    "VariationSummary.Price.HighestPrice",
    "VariationSummary.Price.LowestPrice",
    "VariationSummary.VariationDimensions"
  ],
  "PartnerTag": "xyz-20",
  "PartnerType": "Associates",
  "Marketplace": "www.amazon.co.uk",
  "Operation": "GetVariations"
}
```

--------------------------------

### Get BrowseNode Children Request Payload

Source: https://webservices.amazon.com/paapi5/documentation/browsenodes.html

Example of a request payload to retrieve the children of a specific browse node using the GetBrowseNodes operation. Ensure 'BrowseNodes.Children' is included in the Resources.

```json
{
   "PartnerTag": "associate-tag-20",
   "PartnerType": "Associates",
   "BrowseNodeIds": ["283155"]
   "Resources": ["BrowseNodes.Children"]
}
```

--------------------------------

### Get Next Set of Variations for an ASIN

Source: https://webservices.amazon.com/paapi5/documentation/get-variations.html

This example demonstrates how to retrieve the next page of variations for an ASIN by using the VariationPage parameter in the request payload. This is useful when a product has many variations.

```json
{
 "ASIN": "B00422MCUS",
 "Resources": [
  "ItemInfo.Title",
  "VariationSummary.Price.HighestPrice",
  "VariationSummary.Price.LowestPrice",
  "VariationSummary.VariationDimension"
 ],
 "VariationPage": 2,
 "PartnerTag": "xyz-20",
 "PartnerType": "Associates",
 "Marketplace": "www.amazon.co.uk",
 "Operation": "GetVariations"
}
```

--------------------------------

### GetItems Operation Sample in Java

Source: https://webservices.amazon.com/paapi5/documentation/with-sdk.html

This sample demonstrates how to call the GetItems API to retrieve product information. Ensure you have your AWS credentials and partner tag configured. The code specifies the desired resources and item IDs for the request.

```java
/*
 * Copyright 2025 Amazon.com, Inc. or its affiliates. All Rights Reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License").
 * You may not use this file except in compliance with the License.
 * A copy of the License is located at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * or in the "license" file accompanying this file. This file is distributed
 * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
 * express or implied. See the License for the specific language governing
 * permissions and limitations under the License.
 */

/*
 * ProductAdvertisingAPI
 *
 * https://webservices.amazon.com/paapi5/documentation/index.html
 */

/*
 * This sample code snippet is for ProductAdvertisingAPI 5.0's GetItems API
 * For more details, refer:
 * https://webservices.amazon.com/paapi5/documentation/get-items.html
 */

package samples;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import com.amazon.paapi5.v1.ApiClient;
import com.amazon.paapi5.v1.ApiException;
import com.amazon.paapi5.v1.ErrorData;
import com.amazon.paapi5.v1.GetItemsRequest;
import com.amazon.paapi5.v1.GetItemsResource;
import com.amazon.paapi5.v1.GetItemsResponse;
import com.amazon.paapi5.v1.Item;
import com.amazon.paapi5.v1.PartnerType;
import com.amazon.paapi5.v1.api.DefaultApi;

public class SampleGetItemsApi {

    /**
     * Returns Item mapped to ASIN
     *
     * @param items Items
     * @return Items mapped to ASIN
     */
    private static Map<String, Item> parse_response(List<Item> items) {
        Map<String, Item> mappedResponse = new HashMap<String, Item>();
        for (Item item : items) {
            mappedResponse.put(item.getASIN(), item);
        }
        return mappedResponse;
    }

    public static void main(String[] args) {
        ApiClient client = new ApiClient();

        // Add your credentials
        // Please add your access key here
        client.setAccessKey("<YOUR-ACCESS-KEY-HERE>");
        // Please add your secret key here
        client.setSecretKey("<YOUR-SECRET-KEY-HERE>");

        // Enter your partner tag (store/tracking id)
        String partnerTag = "<YOUR-PARTNER-TAG-HERE>";

        /*
         * PAAPI Host and Region to which you want to send request. For more
         * details refer:
         * https://webservices.amazon.com/paapi5/documentation/common-request-parameters.html#host-and-region
         */
        client.setHost("webservices.amazon.com");
        client.setRegion("us-east-1");

        DefaultApi api = new DefaultApi(client);

        // Request initialization
        /*
         * Choose resources you want from GetItemsResource enum For more
         * details, refer:
         * https://webservices.amazon.com/paapi5/documentation/get-items.html#resources-parameter
         */
        List<GetItemsResource> getItemsResources = new ArrayList<GetItemsResource>();
        getItemsResources.add(GetItemsResource.ITEMINFO_TITLE);
        getItemsResources.add(GetItemsResource.OFFERSV2_LISTINGS_PRICE);

        // Choose item id(s)
        List<String> itemIds = new ArrayList<String>();
        itemIds.add("B09BWFX1L6");
        itemIds.add("B0CFPJYX7P");

        // Forming the request
        GetItemsRequest getItemsRequest = new GetItemsRequest().itemIds(itemIds).partnerTag(partnerTag)
            .resources(getItemsResources).partnerType(PartnerType.ASSOCIATES);

        try {
            // Sending the request
            GetItemsResponse response = api.getItems(getItemsRequest);

            System.out.println("API called successfully");
            System.out.println("Complete response: " + response);

            // Parsing the request
            if (response.getItemsResult() != null) {
                System.out.println("Printing all item information in ItemsResult:");
                Map<String, Item> responseList = parse_response(response.getItemsResult().getItems());
                for (String itemId : itemIds) {
                    if (response.getItemsResult().getItems() != null) {
                        System.out.println("Printing information about the ASIN: " + itemId);
                        if (responseList.get(itemId) != null) {
                            Item item = responseList.get(itemId);
                            if (item.getASIN() != null) {
                                System.out.println("ASIN: " + item.getASIN());
                            }
                            if (item.getDetailPageURL() != null) {
                                System.out.println("DetailPageURL: " + item.getDetailPageURL());
                            }
                            if (item.getItemInfo() != null && item.getItemInfo().getTitle() != null
                                && item.getItemInfo().getTitle().getDisplayValue() != null) {
                                System.out.println("Title: " + item.getItemInfo().getTitle().getDisplayValue());
                            }
                            if (item.getOffers() != null && item.getOffers().getOffers() != null
                                && !item.getOffers().getOffers().isEmpty()
                                && item.getOffers().getOffers().get(0).getBuyingPrice() != null
                                && item.getOffers().getOffers().get(0).getBuyingPrice().getDisplayValue() != null) {
                                System.out.println("Price: " + item.getOffers().getOffers().get(0).getBuyingPrice().getDisplayValue());
                            }
                        }
                    }
                }
            }
        } catch (ApiException e) {
            System.err.println("Error calling PAAPI 5.0: " + e.getMessage());
            e.printStackTrace();
        }
    }
}
```

--------------------------------

### Get Item Title Request Payload

Source: https://webservices.amazon.com/paapi5/documentation/item-info.html

This is an example request payload for the GetItems operation to retrieve the title of an item in the default locale. It specifies the partner tag, item ID, and the desired resource.

```json
{
    "PartnerTag": "xyz-20",
    "ItemIds": ["B00KL8SM92"],
    "Resources": ["ItemInfo.Title"]
}
```

--------------------------------

### Get Variations for a Child ASIN

Source: https://webservices.amazon.com/paapi5/documentation/get-variations.html

This example demonstrates a JSON payload for retrieving variation information for a specific child ASIN. It includes the child ASIN, requested resources, and other necessary parameters for the GetVariations operation.

```json
{
 "ASIN": "B01M2C97VG",
 "Resources": [
  "ItemInfo.Title",
  "VariationSummary.Price.HighestPrice",
  "VariationSummary.Price.LowestPrice",
  "VariationSummary.VariationDimension"
 ],
 "VariationPage": 1,
 "PartnerTag": "xyz-20",
 "PartnerType": "Associates",
 "Marketplace": "www.amazon.co.uk",
 "Operation": "GetVariations"
}
```

--------------------------------

### Get Variation Dimensions Example

Source: https://webservices.amazon.com/paapi5/documentation/use-cases/organization-of-items-on-amazon/variations/variation-dimensions.html

This JSON structure shows how variation dimensions like 'Size' and 'Color' are defined, including their display names, internal names, and available values. Use this to understand the possible attributes for product variations.

```json
{
  "VariationDimensions": [
    {
      "DisplayName": "Size",
      "Name": "size_name",
      "Values": [
        "29W x 30L",
        "29W x 32L",
        "29W x 34L",
        "30W x 30L",
        "30W x 32L",
        "30W x 34L",
        "31W x 30L",
        "31W x 32L",
        "31W x 34L",
        "32W x 30L",
        "32W x 32L",
        "32W x 34L",
        "32W x 36L",
        "33W x 30L",
        "33W x 32L",
        "33W x 34L",
        "34W x 30L",
        "34W x 32L",
        "34W x 34L",
        "34W x 36L",
        "36W x 30L",
        "36W x 32L",
        "36W x 34L",
        "36W x 36L",
        "38W x 30L",
        "38W x 32L",
        "38W x 34L",
        "40W x 30L",
        "40W x 32L",
        "42W x 30L",
        "42W x 32L",
        "44W x 30L",
        "44W x 32L",
        "31  30",
        "31  32",
        "31  34"
      ]
    },
    {
      "DisplayName": "Color",
      "Name": "color_name",
      "Values": [
        "Overhaul",
        "And",
        "Bedside Blues",
        "Black Stone - Stretch",
        "Blue Stone - Stretch",
        "Covered Up - Stretch",
        "Indigo Black",
        "Native Cali - Stretch",
        "Wave Allusions - Stretch",
        "Jagger",
        "Figure Four - Stretch",
        "Tumbled Rigid",
        "Medium Chipped",
        "Outtake",
        "Bebop - Stretch",
        "Indie Blue",
        "Scraped Rigid",
        "Chain Reaction - Stretch",
        "Tumbled Rigid 3914",
        "Tumble Rigid"
      ]
    }
  ]
}
```

--------------------------------

### POST / HTTP/1.1 - SearchItems Request Example

Source: https://webservices.amazon.com/paapi5/documentation/sending-request.html

This snippet demonstrates a sample request header for a SearchItems operation using the Product Advertising API.

```APIDOC
## POST / HTTP/1.1 - SearchItems Request Example

### Description
This is an example request header for a SearchItems request to the Product Advertising API.

### Method
POST

### Endpoint
/

### Headers
- **host** (string) - Required - The host value of the target locale (e.g., `webservices.amazon.com` for US Locale).
- **content-type** (string) - Required - The type of the request content in the body, use `application/json; charset=utf-8`.
- **content-encoding** (string) - Required - Provide `amz-1.0` as value.
- **x-amz-date** (string) - Required - The date used to create the signature in ISO 8601 basic format (YYYYMMDD'T'HHMMSS'Z'). Example: `20160925T120000Z`.
- **x-amz-target** (string) - Required - Signifies the target operation, e.g., `com.amazon.paapi5.v1.ProductAdvertisingAPIv1.SearchItems`.
- **Authorization** (string) - Required - Includes signing algorithm, credential scope, signed headers, and the calculated signature.

### Request Example
```http
POST / HTTP/1.1
host: webservices.amazon.com
content-type: application/json; charset=utf-8
content-encoding: amz-1.0
x-amz-date: 20160925T120000Z
x-amz-target: com.amazon.paapi5.v1.ProductAdvertisingAPIv1.SearchItems
Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE, SignedHeaders=content-type;host;x-amz-date;x-amz-target, Signature=&5d672d79c15b13162d9279b0855cfba6789a8edb4c82c400e06b5924a6f2b5d7;
```
```

--------------------------------

### Example 1: SearchRefinements in 'All' Category

Source: https://webservices.amazon.com/paapi5/documentation/search-refinements.html

Demonstrates a search request in the US marketplace within the 'All' category and the resulting SearchRefinements, including relevant SearchIndexes.

```APIDOC
## Example 1: SearchRefinements in 'All' Category

### Description
This example shows a search request for 'Harry Potter' in the US marketplace when the search is not confined to a specific category (i.e., within the 'All' SearchIndex). The response includes `SearchRefinements` with relevant `SearchIndex` options.

### Request
```json
{
   "PartnerTag": "xyz-20",
   "PartnerType": "Associates",
   "ItemCount": 1,
   "Keyword": "Harry Potter",
   "Resources" : [ "SearchRefinements" ]
}
```

### Response
```json
{
  "SearchResult": {
    "Items": [
      {
        "ASIN": "0545162076",
        "DetailPageURL": "https://www.amazon.com/dp/0545162076?tag=dgfd&linkCode=osi&th=1&psc=1"
      }
    ],
    "SearchRefinements": {
      "SearchIndex": {
        "Id": "SearchIndex",
        "DisplayName": "Department",
        "Bins": [
          {
            "Id": "Books",
            "DisplayName": "Books"
          },
          {
            "Id": "MoviesAndTV",
            "DisplayName": "Movies & TV"
          },
          {
            "Id": "Fashion",
            "DisplayName": "Clothing, Shoes & Jewelry"
          },
          {
            "Id": "HomeAndKitchen",
            "DisplayName": "Home & Kitchen"
          },
          {
            "Id": "Beauty",
            "DisplayName": "Beauty & Personal Care"
          }
          /* More relevant Search Indexes */
        ]
      }
    },
    "SearchURL": "https://www.amazon.com/s/?field-keywords=Harry+Potter&search-alias=aps&tag=xyz-20&linkCode=osi",
    "TotalResultCount": 146
  }
}
```

### Notes
The `SearchIndex` results are ordered by relevance, with the most relevant appearing first. For instance, 'Books' is shown as the most relevant category for the 'Harry Potter' search.
```

--------------------------------

### Sample Deal Ending Soon Response

Source: https://webservices.amazon.com/paapi5/documentation/offersV2.html

This JSON structure provides details for a deal that is nearing its end, including early access information, a countdown badge, and specific timing for start and end.

```json
{
  "DealDetails": {
    "AccessType": "PRIME_EARLY_ACCESS",
    "Badge": "Ends in ",
    "EarlyAccessDurationInMilliseconds": 1800000,
    "EndTime": "2025-02-21T05:35Z",
    "PercentClaimed": 35,
    "StartTime": "2025-02-20T18:05Z"
  }
}
```

--------------------------------

### Sample BrowseNodeInfo Response

Source: https://webservices.amazon.com/paapi5/documentation/browsenodeinfo.html

This JSON snippet shows a sample response for a GetItems request, detailing the BrowseNodes associated with an item.

```json
{
  "ItemsResult": {
    "Items": [
      {
        "ASIN": "059035342X",
        "BrowseNodeInfo": {
          "BrowseNodes": [
            {
              "Id": "3060",
              "DisplayName": "Orphans & Foster Homes",
              "ContextFreeName": "Children's Orphans & Foster Homes Books",
              "IsRoot": false,
              "SalesRank": 2
            },
            {
              "Id": "3153",
              "DisplayName": "Friendship",
              "ContextFreeName": "Children's Friendship Books",
              "IsRoot": false,
              "SalesRank": 4
            },
            {
              "Id": "15356791",
              "DisplayName": "School",
              "ContextFreeName": "Children's School Issues",
              "IsRoot": false,
              "SalesRank": 15
            }
          ]
        }
      }
    ]
  }
}
```
Tokens:
Raw