Defining product detail pages

A product detail page displays information about a product that a user has selected from the search results. Product Search API allows you, as an Amazon Business developer, to retrieve information that you can use to populate a detail page for an Amazon Business product within your application. The API returns details such as the product’s title, price, description, specifications, and seller. Optionally, you can also retrieve alternative offers for this product from other sellers. Together, this functionality enables you to develop robust product pages within your application.

👍
For instructions on developing product detail pages using Product Search API data in your UI, see Product Search API customer experience guidelines.

Prerequisites

Before starting this tutorial, complete these steps:

Complete the API onboarding process to register as a developer, create an app client, and retrieve API access and refresh tokens. For more information, see Onboarding overview.
Gain access to the Business Product Catalog role. For more information, see Amazon Business API roles.
Retrieve the Amazon Standard Identification Number (ASIN) for the product you want to display. For more information, see Initiating a product search.

Retrieve product details

Call the productsRequest operation to retrieve product details. In the request, include the following required fields:

📘
To display item details such as price, shipping, and applicable buying policies, include the optional facets query parameter and set it to OFFERS.

Type	Name	Description	Schema	Required
Header	`x-amz-user-email`	An Amazon Business user account's email address. The user account must be part of an Amazon Business group that has granted consent to your application.	string	Yes
Path	`productId`	The Amazon Standard Identification Number (ASIN) for the product.	string	Yes
Query	`productRegion`	The region where the customer wants to purchase the product.	enum (ProductRegion)	Yes
Query	`locale`	The language of the response content. This locale is in the form of an IETF language tag. The format is `[Two-letter ISO 639-1 language code]-[Two-letter ISO 3166-1 alpha-2 country code]`, such as `en-US` for American English or `es-MX` for Mexican Spanish. Each `ProductRegion` supports one or more locales. For example, the United States supports `en-US` and `es-US` for English and Spanish, respectively.	string	Yes
Query	`facets`	A list of data facets to include in the response. Separate each facet with a comma. Include `OFFERS` to display details such as the offer's price, shipping details, and buying policies. Include `IMAGES` to return images of the product.	< string > array(csv)	No

In this example, we’ll search for an Amazon Basics pack of ballpoint pens, which have the ASIN B07BDWD8B7.

GET https://na.business-api.amazon.com/products/2020-08-26/products/B07BDWD8B7?productRegion=US&locale=en_US

import requests

url = "https://na.business-api.amazon.com/products/2020-08-26/products/B07BDWD8B7?productRegion=US&locale=en_US"

headers = {
    "accept": "application/json",
    "x-amz-access-token": "<Access token retrieved in Prerequisites Step 1>",
    "x-amz-user-email": "<Customer email address",
}

response = requests.get(url, headers=headers)

print(response.text)

A successful request returns details about the specified product.

Name	Description	Schema
`asin`	The Amazon Business ASIN product identifier.	string
`asinType`	The type of ASIN returned in the request.	AsinType
`signedProductId`	Product ID signed with information about the request for which it was returned.	string
`includedDataTypes`	A list of additional data groups, as specified in the request. Each facet contains a logic grouping of data about the product.	< string, < object > array > map
`features`	A list of descriptive features of the product, typically shown as a bulleted list.	< string > array
`editorialReviews`	A list of editorial reviews for the product.	< EditorialReview > array
`taxonomies`	A list of taxonomy classifications for the product.	< Taxonomy > array
`title`	The title of the product shown at the top of an Amazon Business product page.	string
`url`	A URL to the product on the Amazon Business website.	string
`format`	The type of product on the Amazon Business website. For books, this is the binding.	string
`bookInformation`	If applicable, book-specific details for the product.	BookInformation
`byLine`	A product's by-line contributor information such as brand, author, and editor.	< Contributor > array
`mediaInformation`	If applicable, a media type information for the product.	MediaInformation
`productOverview`	The general descriptive fields for the product.	< string, string > map
`productDetails`	The nested key or value pairs indicating additional information for product parts.	< string, < string, string > map > map
`customerReviewsSummary`	The information on the product's rating count and star rating. Note that this field is only available for products displayed in eProcurement systems.	CustomerReviewsSummary
`productVariations`	The variations (Child products) for this products and dimensions for all variations exp.{dimensions: {color: {0:red, 1:blue, ...}, size: {0:xs, 1:sm, ...}, ...},variations: {B07J3G6312: [1,0], B07J348978: [0,0], ...}}	ProductVariations
`productDescription`	The description for the given product.	string
`upcValues`	A list of 12-digit Universal Product Codes (UPC) printed on retail product packaging for easy identification. UPC is used only in the US and Canada.	< string > array
`eanValues`	A list of 13-digit European Article Numbers (EAN) printed on retail product packaging for easy identification. EAN is used globally except in US and Canada.	< string > array
`badges`	Collection of applicable badges for the ASIN. Badges indicate the product’s membership, status, or other identifiers, such as its sustainability features.	< badge > array

{
    "asin": "B07BDWD8B7",
    "asinType": "VARIATION_CHILD",
    "signedProductId": "amzn1.business.asin.AHFTA2DIOWQLIKT3TIFGI2LRMFZG423ZORUGOZLEG5ZGMY3BONQTTUAVOLWYQTTYLCGOSRRYQVT4DUTN3AGUJKK44DPYO6ZDVFZ3PX3UZPO3PAQJTKQUH4HEPQNHJWOUMANO6BB5YCN4XZLL7TJTS63P2335ZRJFK5I7DTJJZ3TUFTSLT4UQ",
    "includedDataTypes": {
        "OFFERS": [
            {
                "availability": "In Stock.",
                "buyingGuidance": "NONE",
                "buyingGuidanceV2": {
                    "buyingGuidance": [
                        {
                            "title": "NONE",
                            "message": **null**,
                            "link": **null**,
                            "type": "NONE",
                            "fragments": []
                        }
                    ]
                },
                "buyingRestrictions": [],
                "fulfillmentType": "AMAZON_FULFILLMENT",
                "merchant": {
                    "merchantId": **null**,
                    "name": "Amazon",
                    "meanFeedbackRating": **null**,
                    "totalFeedbackCount": **null**,
                    "certificates": []
                },
                "fulfiller": {
                    "name": "Amazon",
                    "fulfillmentType": "AMAZON_FULFILLMENT"
                },
                "offerId": "Gcr%2BtgH%2F5EmXCG1X5BqcXQRMA4%2Fs9xPmF0IJOjfUDBjqIcMoS4x8yOjtBTcOu6E4nSZ7L9yuGepeW7jhSaCaxVMPZQAkiV14ikzpCQOU4Dl8pGTRnYvtJhyomoKjuGG3%2FW7cKc4f3DJZ7psir%2FTYFu7MD6csq6pr",
                "price": {
                    "value": {
                        "amount": 7.62,
                        "currencyCode": "USD"
                    },
                    "formattedPrice": **null**,
                    "priceType": "BUSINESS"
                },
                "shippingOptions": [
                    {
                        "shippingCost": {
                            "value": {
                                "amount": 6.99,
                                "currencyCode": "USD"
                            }
                        },
                        "deliveryRange": {
                            "max": "2025-04-29T03:00:00Z",
                            "min": "2025-04-29T03:00:00Z"
                        },
                        "deliveryInformation": "FREE delivery Monday, April 28 on orders shipped by Amazon over $35",
                        "thresholdCost": {
                            "value": {
                                "amount": 35.0,
                                "currencyCode": "USD"
                            }
                        }
                    },
                    {
                        "shippingCost": {
                            "value": {
                                "amount": 9.99,
                                "currencyCode": "USD"
                            }
                        },
                        "deliveryRange": {
                            "max": "2025-04-24T03:00:00Z",
                            "min": "2025-04-24T03:00:00Z"
                        },
                        "deliveryInformation": "$9.99 delivery Wednesday, April 23. Order within 8 hrs 23 mins",
                        "thresholdCost": **null**
                    }
                ],
                "badges": [],
                "quantityInStock": **null**,
                "listPrice": {
                    "value": {
                        "amount": 10.31,
                        "currencyCode": "USD"
                    },
                    "formattedPrice": **null**,
                    "priceType": "BUSINESS"
                },
                "productCondition": "NEW",
                "productConditionNote": "",
                "condition": {
                    "conditionValue": "NEW",
                    "conditionNote": "",
                    "subCondition": "UNKNOWN"
                },
                "quantityLimits": {
                    "maxQuantity": 30,
                    "minQuantity": 1
                },
                "quantityPrice": {
                    "quantityPriceTiers": []
                },
                "taxExclusivePrice": {
                    "taxExclusiveAmount": **null**,
                    "displayString": "",
                    "formattedPrice": "",
                    "label": ""
                },
                "deliveryInformation": "FREE delivery Monday, April 28 on orders shipped by Amazon over $35"
            }
        ]
    },
    "features": [
        "SMOOTH WRITING EXPERIENCE: Enjoy consistent ink flow and a 1.2mm point for clear, bold lines with each stroke. These ball point pens provide smooth writing for taking notes",
        "DURABLE AND RELIABLE: Constructed to meet ASTM D4236 and ISO 12757-1 standards, these colorful pens provide lasting quality and performance",
        "COMFORTABLE GRIP DESIGN: These pens for school have a design that provides a comfortable grip for extended writing sessions, making them ideal for students and professionals",
        "CONVENIENT RETRACTABLE FUNCTION: Easily click to retract the pens, keeping your pockets and bags clean",
        "12-PACK VALUE SET: You always have ball point pens for note taking on hand with this convenient 12-pack, ideal for work, home, or as part of your back to school supplies"
    ],
    "editorialReviews": [],
    "taxonomies": [
        {
            "taxonomyCode": "44121704",
            "title": "Ball point pens",
            "type": "UNSPSC"
        },
        {
            "taxonomyCode": "24240503",
            "title": "",
            "type": "ECLASS"
        }
    ],
    "packageTypeNames": [],
    "title": "Amazon Basics Black Ballpoint Pens for Smooth Writing, Retractable, 12-Pack",
    "url": "https://www.amazon.com/dp/B07BDWD8B7?ref_=ab_psdp",
    "format": **null**,
    "bookInformation": {
        "isbn": {
            "isbn10": **null**,
            "isbn13": **null**
        },
        "publicationDate": **null**,
        "publishedLanguage": **null**
    },
    "byLine": [],
    "mediaInformation": {
        "editions": [],
        "mediaFormats": []
    },
    "productOverview": {
        "Date First Available": "May 31, 2018",
        "Closure": "Retractable",
        "Unit Count": "12.0 Count",
        "Recommended Uses For Product": "Writing",
        "Size": "12 Count (Pack of 1)",
        "Age Range Description": "Adult",
        "Writing Instrument Form": "Ballpoint Pen",
        "Global Trade Identification Number": "00192233020808",
        "ASIN": "B07BDWD8B7",
        "UPC": "192233020808",
        "Material Type": "Rubber",
        "Product Dimensions": "5.71 x 0.39 x 0.55 inches",
        "Point Type": "Bold",
        "Drill Point": "Bold",
        "Ink Color": "Black",
        "Ink Base": "Alcohol",
        "Item Height": "0.55 inches",
        "Item Hardness": "H",
        "Manufacturer": "Amazon",
        "Style": "Retractable Ballpoint",
        "Number of Items": "1",
        "Special Feature": "Retractable",
        "Pattern": "Pen",
        "Body Shape": "Round",
        "Model Name": "Amazon Basics",
        "Item dimensions L x W x H": "5.71 x 0.39 x 0.55 inches",
        "Color": "Black",
        "Item Diameter": "0.39 Inches",
        "Item model number": "AH518-12-B",
        "Manufacturer Part Number": "AH518-12-B",
        "Hand Orientation": "Ambidextrous",
        "Material": "Rubber",
        "Model Number": "AH518-12-B",
        "Hardness": "H",
        "Pencil Lead Degree (Hardness)": "H",
        "Line Size": "2mm_and_above",
        "Grip Type": "No Grip",
        "Brand Name": "Amazon Basics",
        "Brand": "Amazon Basics",
        "Additional Features": "Retractable",
        "Item Dimensions": "5.71 x 0.39 x 0.55 inches",
        "Age Range (Description)": "Adult",
        "Closure Type": "Retractable",
        "Item Weight": "0.28 Ounces"
    },
    "productDetails": {},
    "productVariations": {
        "dimensions": [
            {
                "index": 0,
                "displayString": "Color",
                "dimensionValues": [
                    {
                        "index": 0,
                        "displayString": "Assorted Colors"
                    },
                    {
                        "index": 1,
                        "displayString": "Black"
                    }
                ]
            }
        ],
        "variations": [
            {
                "asin": "B07BDV7PDL",
                "variationValues": [
                    {
                        "index": 0,
                        "value": 0
                    }
                ]
            },
            {
                "asin": "B07BDWD8B7",
                "variationValues": [
                    {
                        "index": 0,
                        "value": 1
                    }
                ]
            }
        ]
    },
    "customerReviewsSummary": {
        "numberOfRatings": **null**,
        "starRating": **null**
    },
    "productDescription": "These pens are ideal for back to school supplies, offering a comprehensive color pens set for all your writing needs. Whether you're taking notes, creating a masterpiece, or organizing your thoughts in a journal, these multi color pens have you covered. Each pen features a 1.2mm point, ensuring smooth, consistent writing. With a variety of multicolored pens at your disposal, you can easily highlight important information or add a burst of color to your bullet journals. Included in this 24-pack are essential red pens ballpoint, ideal for editing or emphasizing key points. These pens work efficiently as journal pens or bullet journal pens, offering a seamless writing experience that supports your daily activities. The assortment includes pens colored to suit diverse tastes and preferences, allowing for creativity to flourish. Each pen conforms to ASTM D4236 standards, offering quality performance.",
    "upcValues": [],
    "eanValues": [],
    "modelNumber": **null**,
    "manufacturerName": **null**,
    "bundleQuantity": **null**,
    "badges": []
}

Each request to the productsRequest operation returns the featured offer. This is the main offer that would be displayed on Amazon Business detail pages.

Optionally, if you want to retrieve other offers for a product, such as offers from other sellers, you can call the searchOffersRequest operation to retrieve offers for the ASIN provided in the request.

In this example, we’ll search for other offers of the pens we retrieved earlier by passing their ASIN, B07BDWD8B7, in the productId query parameter.

GET https://na.business-api.amazon.com/products/2020-08-26/products/B07BDWD8B7/offers?productRegion=US&locale=en_US

import requests

url = "https://na.business-api.amazon.com/products/2020-08-26/products/B07BDWD8B7/offers?productRegion=US&locale=en_US"

headers = {
    "accept": "application/json",
    "x-amz-access-token": "<Access token retrieved in Prerequisites Step 1>",
    "x-amz-user-email": "<Customer email address",
}

response = requests.get(url, headers=headers)

print(response.text)

A successful request returns an array of offers for the provided ASIN. The buy box offer is provided in the featuredOffer field, while the remaining offers are returned as an array in the offers field. The API can also return a filterGroups object that contains an array of IDs that can be used to filter the offers by their shipping, condition, and potential discounts in subsequent requests. In this example, the API returns one offer for the provided ASIN.

Name	Description	Schema	Required
`offerCount`	The number of offers for the ASIN after filters are applied.	integer	No
`numberOfPages`	The number of pages of results.	integer	No
`featuredOffer`	A featured offer that is selected based on eligibility requirements and criteria.	Offer	No
`offers`	A list of offers in a page.	< Offer > array	No
`filterGroups`	A list of filter groups.	< OfferFilterGroup > array	No

👍
For guidance on displaying offers for an Amazon Business product in your UI, see Offers layout.

{
    "offerCount": 1,
    "numberOfPages": 1,
    "featuredOffer": {
        "availability": "In Stock.",
        "buyingGuidance": "NONE",
        "buyingGuidanceV2": {
            "buyingGuidance": [
                {
                    "title": "NONE",
                    "message": **null**,
                    "link": **null**,
                    "type": "NONE",
                    "fragments": []
                }
            ]
        },
        "buyingRestrictions": [],
        "fulfillmentType": "MERCHANT_FULFILLMENT",
        "merchant": {
            "merchantId": **null**,
            "name": "TrueColoursOfIndia",
            "meanFeedbackRating": **null**,
            "totalFeedbackCount": **null**,
            "certificates": []
        },
        "fulfiller": {
            "name": "TrueColoursOfIndia",
            "fulfillmentType": "MERCHANT_FULFILLMENT"
        },
        "offerId": "4k8xAQc5kNA%2FN%2BwvO9DpD1rNNtk25G1o9UfIK2aEUtfFudBxmikVMRKZfKIT1tRFYQGGKt0IDXzkD7nD0cnESzPc8bukyP5UTHmLJHCvV5OBol0ZYO4%2BMNFE2y87JGRSVxkp1t6LZhaq7gfLaVRWoBuOTmxeJbcXjy7jVu%2FcDOvJlMGUjSCR1vvMJ01pHlL3",
        "price": {
            "value": {
                "amount": 25.0,
                "currencyCode": "USD"
            },
            "formattedPrice": **null**,
            "priceType": "NEW"
        },
        "shippingOptions": [
            {
                "shippingCost": {
                    "value": {
                        "amount": 0.0,
                        "currencyCode": "USD"
                    }
                },
                "deliveryRange": {
                    "max": "2025-05-10T06:59:59Z",
                    "min": "2025-05-01T07:00:00Z"
                },
                "deliveryInformation": "FREE delivery May 1 - 9",
                "thresholdCost": **null**
            }
        ],
        "badges": [],
        "quantityInStock": **null**,
        "listPrice": {
            "value": **null**,
            "formattedPrice": **null**,
            "priceType": **null**
        },
        "productCondition": "NEW",
        "productConditionNote": "",
        "condition": {
            "conditionValue": "NEW",
            "conditionNote": "",
            "subCondition": "UNKNOWN"
        },
        "quantityLimits": {
            "maxQuantity": 30,
            "minQuantity": 1
        },
        "quantityPrice": {
            "quantityPriceTiers": []
        },
        "taxExclusivePrice": {
            "taxExclusiveAmount": **null**,
            "displayString": "",
            "formattedPrice": "",
            "label": ""
        },
        "deliveryInformation": "FREE delivery May 1 - 9"
    },
    "offers": [],
    "filterGroups": [
        {
            "displayName": "Delivery",
            "filters": [
                {
                    "id": "FREE_SHIPPING",
                    "displayName": "Free delivery"
                }
            ]
        },
        {
            "displayName": "Business Discounts",
            "filters": [
                {
                    "id": "QUANTITY_DISCOUNTS",
                    "displayName": "Quantity discounts"
                }
            ]
        },
        {
            "displayName": "Condition",
            "filters": [
                {
                    "id": "NEW",
                    "displayName": "New"
                }
            ]
        }
    ]
}

Error handling

If your request is not successful, the API returns an errors object that provides information about what went wrong. For more information, see Error responses and schemas.