Product Search API v1 reference
Amazon Business API for Products
Overview
An API for getting data about products available to Amazon Business customers. This includes information such as the product title, the merchant selling the product, and the current price.
Version information
Version : 2020-08-26
License information
License : Amazon Software License
License URL : https://aws.amazon.com/asl/
URI scheme
Host : api.business.amazon.com
Schemes : HTTPS
Tags
- products : Get data about a particular product.
External Docs
Description : Learn more about Amazon Business
URL : https://business.amazon.com
Operations
searchProductsRequest
productsRequest
searchOffersRequest
getProductsByAsins
Paths
Search for a list products by keyword, and by other additional filter criteria.
GET /products/2020-08-26/products
Operation: searchProductsRequest
Description
Search for a list of products by querying on their attributes and indexed fields.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Query | keywords optional | A list of keywords to use for finding products based on indexed data. | string |
| Query | productRegion required | The region where the customer wants to purchase the product. | enum (ProductRegion) |
| Query | shippingRegion optional | This field determines the region where to ship the product based on the value in the shippingPostalCode. | string |
| Query | locale required | The locale of the request in the form of an IETF language tag. Each ProductRegion supports one or more locales. This value should comply with java.util.Locale. | string |
| Query | shippingPostalCode optional | The shipping postal or zip code for customer's request. This parameter doesn't hold geocode. | string |
| Query | facets optional | A list of data facets to include in the response. Separate each facet with a comma. | < string > array(csv) |
| Query | pageNumber optional | The zero-based number of the page being requested. If not specified, a default value of 0 will be used. When passed, the value must be equal or greater than zero, and strictly less than the number of pages returned in the response. The maximum number of pages that can be fetched is 13. | integer |
| Query | pageSize optional | The number of items desired in SearchProductsResult response. If not specified, a default value of 24 will be used. Maximum items that can be fetched in single request is 24. | integer |
| Query | groupTag optional | A value that identifies the group within the business account that a customer belongs to. The customer can set this in Amazon Business account information. GroupTag is necessary only if the account associated with x-amz-user-email belongs to more than one group. | string |
| Query | category optional | This field restricts the returned result to this specified category. Categories can be found under refinements->categories->id of this API call's response. Sample categories: 'Electronics', 'Appliances', or 'Baby' | string |
| Query | subCategory optional | This field restricts the returned result to this specified subcategory ID. Subcategory IDs can be found under refinements->subcategories->id of this API call's response when a category or subcategory is specified. Note: there can be multiple levels of subcategories in a category. Sample subcategory IDs: '4997' or '4799' | string |
| Query | availability optional | This field restricts the returned results to one of the following specified availability IDs: 2661600011 (In Stock only) 2661601011 (Include Out of Stock) | string |
| Query | deliveryDay optional | The deliveryDay feature is used to refine the keyword search results. By default, the search returns results with all the available delivery dates. In the returned result refinement, there should be one 'Get It Today' ID, and one 'Get It Tomorrow' ID. If the customer sets the deliveryDay with 'Get It Today' ID, the results will return products that could arrive today or zero matching if no product could arrive today. If the customer sets the deliveryDay with 'Get It Tomorrow' ID, the results will return products that could arrive tomorrow or zero matching if no product could arrive tomorrow. | string |
| Query | eligibleForFreeShipping optional | The eligibleForFreeShipping is used to refine the keyword search results. By default, the search should return results with both 'Free Shipping' and not 'Free Shipping by Amazon Business.' In the returned result refinement, there should be one eligibleForFreeShipping Id. It represents 'Free Shipping by Amazon Business.' If the customer sets the eligibleForFreeShipping as this ID, the result will only return products with 'Free Shipping by Amazon Business.' | string |
| Query | primeEligible optional | The prime eligible refinement is used to filter prime eligible products. By default, the search returns results with prime eligible and non-prime eligible products. | string |
| Query | upc optional | This field restricts the returned result to this specified Universal Product Code (UPC). UPC is printed on product packaging. | string |
| Query | isbn optional | This field restricts the returned results to this specified ISBN (International Standard Book Number). ISBN is a 13-digit number that uniquely identifies a book. | string |
| Query | sku optional | This field restricts the returned results to this specified Stock Keeping Unit (SKU). SKU is a merchant-specific identifier. | string |
| Query | ean optional | This field restricts the returned results to this specified EAN (European Article Number). EAN is a 13-digit product identifier. | string |
| Query | partNumber optional | This field restricts the returned results to this specified part number. Part number is a unique number issued by manufacturers to identify individual products. | string |
| Query | oemPartNumber optional | This field restricts the returned results to this specified OEM (Original Equipment Manufacturer) part number. OEM part number is an identifier that indicates the original manufacturer of the part of the product. | string |
| Query | searchRefinements optional | A list of search refinements to refine keyword search for relevant results. Separate each refinement with a comma. It is recommended that you do not hard-code this value in the request. Instead, the search refinements value should be dynamically retrieved from a previous API response and used in consequent request. | < string > array(csv) |
| Header | x-amz-user-email required | The email address of the customer requesting this resource. | string |
| Query | inclusionsForProducts optional | A list specifying the product fields for inclusion in the response object. Excluding this query parameter results in response returning all inclusions except upcValues and eanValues. | < string > array(csv) |
| Query | inclusionsForOffers optional | A list specifying the offer fields for inclusion in the response object. Excluding this parameter results in response returning all inclusions. | < string > array(csv) |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | Search success Headers : x-amzn-RateLimit-Limit (string) : The rate limit (requests per second) for this operation. x-amzn-requestid (string) : A unique request reference identifier. | SearchProductsResult |
| 400 | The service was unable to process the request. Reasons for the error are described in an error response object. Headers : x-amzn-RateLimit-Limit (string) : The rate limit (requests per second) for this operation. x-amzn-requestid (string) : A unique request reference identifier. | ErrorResponse |
For additional error status codes, descriptions and schemas, see Error responses and schemas.
Produces
application/json
Retrieves product data based on an ASIN identifier.
GET /products/2020-08-26/products/{productId}
Operation: productsRequest
Description
Retrieves a product with its ASIN identifier.
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
| Path | productId required | The Amazon Standard Item Identifier (ASIN) for the product. | string | - |
| Query | productRegion required | The region where the customer wants to purchase the product. | enum (ProductRegion) | - |
| Query | shippingRegion optional | This field determines the region where to ship the product based on the value in the shippingPostalCode. | string | - |
| Query | locale required | The locale of the request, in the form of an IETF language tag. Each ProductRegion supports one or more locales. This value should comply with java.util.Locale. | string | - |
| Query | shippingPostalCode optional | The shipping postal or zip code for the customer's request. This parameter doesn't support geocode. | string | - |
| Query | quantity optional | The number of units the customer intends to purchase. This helps Amazon Business determine quantity-based discounts if an eligible offer is present. Defaults to 1. | integer | 1 |
| Query | facets optional | A list of data facets to include in the response. Separate each facet with a comma. | < string > array(csv) | - |
| Header | x-amz-user-email required | The email address of the customer requesting this resource. | string | - |
| Query | inclusionsForProducts optional | A list specifying the product fields for inclusion in the response object. Excluding the query parameter results in the response including all inclusions except upcValues and eanValues. | < string > array(csv) | - |
| Query | inclusionsForOffers optional | A list specifying the offer fields for inclusion in the response object. Excluding this query parameter results in the response including all inclusions. | < string > array(csv) | - |
| Query | groupTag optional | A value that identifies the group within the business account that a customer belongs to. The customer can set this in Amazon Business account information. GroupTag is necessary only if the customer account belongs to more than one group. | string | - |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | Product successfully retrieved. | ProductsResult |
| 400 | The service was unable to process your request. Reasons for the error are described in an error response object. | ErrorList |
For additional error status codes, descriptions and schemas, see Error responses and schemas.
Produces
application/json
Paginated and filtered search for offers of a specific product.
GET /products/2020-08-26/products/{productId}/offers
Operation: searchOffersRequest
Description
Search for offers of a specific product.
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
| Path | productId required | The Amazon Standard Item Identifier (ASIN) for the product. | string | - |
| Query | productRegion required | The region where the customer wants to purchase the product. | enum (ProductRegion) | - |
| Query | shippingRegion optional | This field determines the region where to ship the product based on the value in the shippingPostalCode. | string | - |
| Query | locale required | The locale of the request, in the form of an IETF language tag. Each ProductRegion supports one or more locales. This value should comply with java.util.Locale. | string | - |
| Query | shippingPostalCode optional | The shipping postal or zip code for customer's request. This parameter doesn't hold geocode. | string | - |
| Query | pageNumber optional | The zero-based number of the page being requested. If not specified, a default value of 0 will be used. When passed, the value must be equal or greater than zero, and less than the number of pages returned in the response. The maximum number of pages that can be fetched is 13. | integer | - |
| Query | pageSize optional | The number of items desired for each page in the response. If not specified, a default value of 24 will be used. Maximum items that can be fetched in single request is 24. | integer | - |
| Query | groupTag optional | A value that identifies the group within the business account that a customer belongs to. The customer can set this in Amazon Business account information. GroupTag is necessary only if the customer account belongs to more than one group. | string | - |
| Query | filterIds optional | A list of filter ids for use to query results. | < string > array(csv) | - |
| Query | quantity optional | The number of units the customer intends to purchase. This helps Amazon Business determines quantity-based discounts if an eligible offer is present. Defaults to 1. | integer | 1 |
| Header | x-amz-user-email required | The email address of the customer requesting this resource | string | - |
| Query | inclusionsForOffers optional | A list specifying the offer fields for inclusion in the response object. Excluding this query parameter results in the response including all inclusions. | < string > array(csv) | - |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | Search success Headers : x-amzn-RateLimit-Limit (string) : The rate limit (requests per second) for this operation. x-amzn-requestid (string) : A unique request reference identifier. | OffersResult |
| 400 | The service was unable to process the request. Reasons for the error are described in an error response object. Headers : x-amzn-RateLimit-Limit (string) : The rate limit (requests per second) for this operation. x-amzn-requestid (string) : A unique request reference identifier. | ErrorResponse |
For additional error status codes, descriptions and schemas, see Error responses and schemas.
Produces
application/json
The result for list of ASIN search.
POST /products/2020-08-26/products/getProductsByAsins
Operation: getProductsByAsins
Description
Retrieves products for the ASIN identifier present in the list of ASINs.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Body | productsByAsins optional | The request object to use when searching for a list of ASINs. | ProductsByAsinsRequest |
| Header | x-amz-user-email required | The email address of the customer requesting this resource. | string |
| Query | inclusionsForProducts optional | A list specifying the product fields for inclusion in the response object. Excluding this query parameter results in the response including all inclusions except upcValues and eanValues. | < string > array(csv) |
| Query | inclusionsForOffers optional | A list specifying the offer fields for inclusion in the response object. Excluding this query parameter results in the response including all inclusions. | < string > array(csv) |
| Query | groupTag optional | A value that identifies the group within the business account that a customer belongs to. The customer can set this in Amazon Business account information. GroupTag is necessary only if the customer account belongs to more than one group. | string |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | Products successfully retrieved. | ProductsByAsinsResponse |
| 400 | The service was unable to process your request. Reasons for the error are described in an error response object. | ErrorList |
For additional error status codes, descriptions and schemas, see Error responses and schemas.
Produces
application/json
Error Responses and Schemas
This table contains HTTP status codes and associated information for error responses.
| HTTP Code | Description | Schema |
|---|---|---|
| 401 | The request's authorization header isn't formatted correctly or doesn't contain a valid authorization input. Headers: x-amzn-RateLimit-Limit (string):The rate limit (requests per second) for this operation. x-amzn-requestid (string):A unique request reference identifier. | ErrorResponse |
| 403 | Indicates that access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature. Headers: x-amzn-RateLimit-Limit (string):The rate limit (requests per second) for this operation. x-amzn-requestid (string):A unique request reference identifier. | ErrorResponse |
| 404 | The resource specified doesn't exist. Headers: x-amzn-RateLimit-Limit (string):The rate limit (requests per second) for this operation. x-amzn-requestid (string):A unique request reference identifier. | ErrorResponse |
| 429 | The frequency of requests was greater than allowed. Headers: x-amzn-RateLimit-Limit (string):The rate limit (requests per second) for this operation. x-amzn-requestid (string):A unique request reference identifier. | ErrorResponse |
| 500 | Encountered an unexpected condition which prevented the server from fulfilling the request. Headers: x-amzn-RateLimit-Limit (string):The rate limit (requests per second) for this operation. x-amzn-requestid (string):A unique request reference identifier. | ErrorResponse |
| 503 | Temporary overloading or maintenance of the server. Headers: x-amzn-RateLimit-Limit (string):The rate limit (requests per second) for this operation. x-amzn-requestid (string):A unique request reference identifier. | ErrorResponse |
Definitions
AsinType
The type of ASIN returned in the request.
Type : enum
| Value | Description |
|---|---|
| STANDARD | Available for direct purchase. |
| VARIATION_PARENT | Not available for direct purchase but is linked to one or more VARIATION_CHILD. |
| VARIATION_CHILD | Has specific settings for certain attributes such as the size and color of a shirt. This type of ASIN can have different prices and can be offered by different merchants. |
Category
The search category is used to give information about relevant categories a product belongs to. Use category to limit the results for a particular category in subsequent requests.
| Name | Description | Schema |
|---|---|---|
| displayName required | Display name is used to share more human friendly readable description of category. | string |
| id required | Identifies a search category within a product region. | string |
ErrorResponse
The response returned for unsuccessful request.
| Name | Description | Schema |
|---|---|---|
| errors optional | A list of errors encountered while processing the request. | ErrorList |
ErrorList
A list of errors in the response.
Type : < Error > array
Error
Provides the error detail as part of the error response.
| Name | Description | Schema |
|---|---|---|
| code required | The error code in the error response. | enum (Code) |
| message required | A message that describes the error condition. | string |
| details optional | Additional details that can help the customer understand or fix the issue. | string |
BuyingRestriction
If present, this object shows restrictions that would prevent the customer from buying the product.
| Name | Description | Schema |
|---|---|---|
| title required | A displayable string which explains the restriction. | string |
| type required | The type of buying restrictions that exist for a product. Possible value: PROFESSIONAL_USE | string |
Link
Parent structure that holds the URL and its display text.
| Name | Description | Schema |
|---|---|---|
| text optional | The display text to use for the link. | string |
| url required | The URL of the link. | string |
Fragment
Common structure to denote information like badges and guided buying policies.
| Name | Description | Schema |
|---|---|---|
| title optional | The fragment title or header. | string |
| message optional | A custom message or description for the fragment, such as an admin note for a guided buying policy. | string |
| type required | Locale-independent identifier for the fragment. | enum (Type) |
| link optional | URL link to the fragment’s detail page. | Link |
| fragments optional | List of fragments to share additional information. | < Fragment > array |
Merchant
Information about the merchant selling the product.
| Name | Description | Schema |
|---|---|---|
| merchantId required | The unique id of the merchant selling the product. | string |
| name required | The displayable name of the merchant selling the product. | string |
| meanFeedbackRating required | The mean of the total ratings given to the merchant selling the product. | number (double) |
| totalFeedbackCount required | The total number of reviews for the merchant selling the product. | number (integer) |
| certificates required | List of merchant-owned certifications, such as “Registered Small Business” or “Women-Owned Business Enterprise.” | < string > array |
Fulfiller
Information about the fulfiller of the product.
| Name | Description | Schema |
|---|---|---|
| name required | The displayable name of the product fulfiller. | string |
| fulfillmentType required | The fulfillment system to use for the purchased product. | enum (FulfillmentType ) |
Condition
Information about the condition of the product.
| Name | Description | Schema |
|---|---|---|
| conditionValue required | The possible condition of the product being sold by the merchant. | ConditionValue |
| conditionNote required | Additional details on the product's condition. | string |
| subCondition required | The possible sub condition of the product being sold by the merchant. | SubCondition |
ConditionValue
The possible condition of the product being sold by the merchant.
Type : enum
| Value | Description |
|---|---|
| NEW | A brand-new, unused item in perfect condition. |
| USED | A used item may be fairly worn or in perfect condition but still works perfectly. |
| COLLECTIBLE | Collectible items are rare, signed, out of print or distribution, or unique. The Seller should provide details why the product is collectible. |
| REFURBISHED | A product that's professionally restored to working condition before resale. The product is inspected, cleaned, and repaired to meet manufacturer specifications. The product might not be in its original packaging. The manufacturer warranty or warranty of the refurbishing service company might apply. The warranty should be in the Condition comments. |
| OTHER | Refers to the condition of the product that isn't new, used, collectible, refurbished, or unknown. |
| UNKNOWN | The condition of the product is unknown. |
SubCondition
The possible sub condition of the product being sold by the merchant.
Type : enum
| Value | Description |
|---|---|
| ACCEPTABLE | The product is fairly worn but it continues to work perfectly. The signs of wear can include scratches, dents, and other aesthetic problems. The product might be marked or have identifying information on it, and show other signs of previous use. |
| CLUB | A product or service that is communal or has collective ownership-consumption arrangement. |
| GOOD | The product shows wear from consistent use but remains in good condition. The product might be marked or have identifying information on it, and show other signs of previous use. The product works perfectly. |
| LIKE_NEW | An item in perfect working condition. The original plastic wrap might be missing. The original packaging might have minor damage or item might have been repackaged. All accessories are present. |
| NEW | An apparently untouched product in perfect condition. The original plastic wrap might be missing but the original packaging is intact and pristine; instructions are included. There are absolutely no signs of wear. Suitable for presenting as a gift. |
| OEM | Original Equipment Manufacturer (OEM) is defined as a company that provides parts for the finished products of other companies. |
| OPEN_BOX | The product is in the box either with original, visible, or slightly visible UPC. |
| REFURBISHED | A refurbished product in used condition. The manufacturer warranty no longer applies. |
| UNKNOWN | The condition of the product is unknown. |
| VERY_GOOD | A well-cared product with limited use but still in great condition. The product is complete, unmarked, and undamaged but might show some limited signs of wear. The product works perfectly. |
Offer
An offer for a product being sold by a merchant. This object contains details that would help a buyer decide whether to purchase or not to purchase a product.
| Name | Description | Schema |
|---|---|---|
| availability required | Displays the available dates to ship the product after purchased. | string |
| buyingGuidance required | [DEPRECATED: Please use buyingGuidanceV2 instead] Some organizations establish guided buying policies to inform Amazon Business whether their organization supports the purchase of specified types of products. If an organization hasn't configured such policies, an API call returns the value "NONE" for the BuyingGuidance property. | enum (BuyingGuidance) |
| buyingGuidanceV2 required | Some organizations establish guided buying policies to inform Amazon Business whether their organization supports the purchase of specified product types. If an organization hasn't configured such policies, an API call returns a Fragment object with value "NONE" for the title property. | BuyingGuidanceV2 |
| buyingRestrictions required | When present, entries in this property describe the reasons a buyer is restricted from buying a product. | < BuyingRestriction > array |
| fulfillmentType required | [DEPRECATED: Please use fulfiller instead] The fulfillment system to use for the purchased product purchase. | enum (FulfillmentType) |
| merchant required | Information about the merchant selling the product. | Merchant |
| offerId required | The Amazon Business offer identifier to use when purchasing a product. | string |
| price required | The actual price the customers pay for the product. | Price |
| shippingOptions required | The options for shipping a product offer. | < ShippingOption > array |
| listPrice required | The actual price the customers pay for the product. | Price |
| productCondition required | The possible condition of the product being sold by the merchant. | enum (ProductCondition) |
| productConditionNote required | Additional details on the product's condition. | string |
| condition required | Information about the condition of the product. | Condition |
| quantityLimits required | The number of items allowed to purchase a product in a single order. Some products have both a min and max quantity. | OfferQuantityLimits |
| quantityPrice optional | Provides information about the different prices a customer can get for higher quantities. | QuantityPrice |
| taxExclusivePrice required | The price of the product without tax. | TaxExclusivePrice |
| deliveryInformation required | Information regarding the estimated delivery time and delivery price. | string |
| badges required | The available badges for a product offer, such as Invoice by Amazon (IBA) or Japan Consumption Tax (JCT). | Badge |
ShippingOption
The available options for shipping a product offer.
| Name | Description | Schema |
|---|---|---|
| shippingCost required | The cost related to shipping an item. | ShippingDetails |
| deliveryRange required | The delivery window for shipping a product offer. | DeliveryDateRange |
| deliveryInformation required | String representation of the estimated delivery time and delivery price. | string |
| thresholdCost required | The threshold for free shipping. When the total cost of the order exceeds this cost, shipping is free. | ThresholdPrice |
ShippingDetails
The charges related to shipping a product offer.
| Name | Description | Schema |
|---|---|---|
| value required | An object that contains numerical amount value and the currency code. | Money |
DeliveryDateRange
Indicates the minimum and maximum delivery date and time to ship a product offer.
| Name | Description | Schema |
|---|---|---|
| max required | The maximum local delivery date and time to ship a product offer. | string (date-time) |
| min required | The minimum local delivery date and time to ship a product offer. | string (date-time) |
ThresholdPrice
The threshold for free shipping. The shipping cost is applicable when the value of the order is below this cost. When the order value exceeds this cost, shipping is free.
| Name | Description | Schema |
|---|---|---|
| value required | An object that contains numerical amount value and the currency code. | Money |
OfferQuantityLimits
The number of items allowed to purchase a product in a single order. Some products have both a min and max quantity.
| Name | Description | Schema |
|---|---|---|
| maxQuantity required | The largest number of products the customer can buy in an order. | integer (int64) |
| minQuantity required | The smallest number of products the customer can buy in an order. | integer (int64) |
Money
An object that holds the numerical value and the currency code associated with the money.
| Name | Description | Schema |
|---|---|---|
| amount required | The numerical value of the money. | number (double) |
| currencyCode required | The currency code for that price amount depending on the requested locale | string |
Price
The actual price the customers pay for the product.
| Name | Description | Schema |
|---|---|---|
| value required | An object that contains numerical amount value and the currency code. | Money |
| formattedPrice required | A displayable version of the price and currency code. | string |
| priceType required | A description of the type of price. Some prices are indicative of special business pricing for a customer. | string |
TaxExclusivePrice
The price of the product without tax.
| Name | Description | Schema |
|---|---|---|
| taxExclusiveAmount required | An object that contains numerical amount value and the currency code. | Money |
| displayString required | A displayable message about the tax exclusion. | string |
| formattedPrice required | A displayable version of the price and currency code. | string |
| label required | A displayable description of the type of tax exclusion. | string |
Badge
The available badge for a product offer.
| Name | Description | Schema |
|---|---|---|
| name required | [DEPRECATED: Please use fragment instead] The name of a badge for a product offer. | string |
| fragment required | Information about the badge. This object may contain HTML italics tags in the response. When implementing this API, you can either display fields as HTML or rich content, or use an HTML parser to get plain text. | Fragment |
EditorialReview
An editorial review for the product.
| Name | Description | Schema |
|---|---|---|
| content required | The editorial review content. | string |
| source required | The editorial review content source. | string |
Taxonomy
A taxonomy data entry for the product.
| Name | Description | Schema |
|---|---|---|
| taxonomyCode required | The taxonomy code. | string |
| title required | A displayable string with the name of product category. | string |
| type required | The taxonomy types supported by Amazon Business. | enum (Type) |
ISBN
International Standard Book Number (ISBN) associated with the product.
| Name | Description | Schema |
|---|---|---|
| isbn10 optional | A 10-digit ISBN associated with the product. | string |
| isbn13 optional | A 13-digit ISBN associated with the product. | string |
BookInformation
Book details (if applicable).
| Name | Description | Schema |
|---|---|---|
| isbn optional | A 10 or 13-digit ISBN associated with the product. | ISBN |
| publicationDate optional | The date the book was published. | string (date-time) |
| publishedLanguage optional | The language used for publishing the book. | string |
Contributor
A contributor's entry for the product.
| Name | Description | Schema |
|---|---|---|
| name optional | The name of the contributor. | string |
| roles optional | The role or roles of the contributor in the context of the product. | < string > array |
MediaInformation
If applicable, media type information of the product.
| Name | Description | Schema |
|---|---|---|
| editions optional | Available editions of the product. | < string > array |
| mediaFormats optional | Available formats of the media product. | < string > array |
CustomerReviewsSummary
Information on the product's rating count and star rating.
| Name | Description | Schema |
|---|---|---|
| numberOfRatings optional | The number of customer ratings for a product. | integer |
| starRating required | The star rating for a product. | number (double) |
DimensionValue
The value of a dimension and its index.
exp. {index:0, displayString:red}
| Name | Description | Schema |
|---|---|---|
| index optional | index of the value | integer |
| displayString optional | The string of the dimension value in its readable form. exp. red, sm, 12-packs | string |
Dimension
A dimension with its index, categorical name in its readable form, and a list of values.
exp. [{index:0, displayString:color, dimensionValues: [{index:0, displayString:red}, ...]}, ...]
| Name | Description | Schema |
|---|---|---|
| index optional | The index of the dimension. | integer |
| displayString optional | The categorical name of the dimension in its readable form. exp. color, size | string |
| dimensionValues optional | The value of a dimension and its index. exp. {index:0, displayString:red} | < DimensionValue > array |
VariationValue
Contains index that maps to a dimension and value maps to a dimensionValue to represent the variation properties for a child product.
exp. {index:0, value: 0}
| Name | Description | Schema |
|---|---|---|
| index optional | The index of the dimension. | integer |
| value optional | The value that maps to dimensionValue. | integer |
Variation
A child product (variation) that contains its ASIN and a list of variationValues showing its variation properties.
exp. [ASIN: B07J3G6312: [{index:0, value: 0}, ...]]
| Name | Description | Schema |
|---|---|---|
| asin optional | The ASIN of the child product. exp. B07J3G6312 | string |
| variationValues optional | Contains index that maps to a dimension and value maps to a dimensionValue to represent the variation properties for a child product. exp. {index:0, value: 0} | < VariationValue > array |
ProductVariations
Variations (Child products) for the products including all of the categorical dimensions and their values. exp.
Dimensions: [{index:0, displayString:color, dimensionValues: [{index:0, displayString:red}, ...]}, ...], Variations: [ASIN: B07J3G6312: [{index:0, value: 0}, ...]]
should be interpret as B07J3G6312: [color: red]
| Name | Description | Schema |
|---|---|---|
| dimensions required | A list of dimensions with their index, categorical names in their readable form, and lists of values for these dimensions. exp. [{index:0, displayString:color, dimensionValues: [{index:0, displayString:red}, ...]}, ...] | < Dimension > array |
| variations required | A list of child products (variations) which contain their ASINs and lists of variationValues showing their variation properties. exp. [ASIN: B07J3G6312: [{index:0, value: 0}, ...], ...] | < Variation > array |
Products Result
The result of a request for product data.
| Name | Description | Schema |
|---|---|---|
| asin required | The Amazon Business ASIN product identifier. | string |
| asinType required | The type ASIN returned in the request. | AsinType |
| signedProductId required | Product id signed with information about the request for which it was returned. | string |
| includedDataTypes required | 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 required | A list descriptive features of the product, typically shown as a bulleted list. | < string > array |
| editorialReviews optional | A list of editorial reviews for the product. | < EditorialReview > array |
| taxonomies required | A list taxonomy classifications for the product. | < Taxonomy > array |
| title required | The title of the product shown at the top of an Amazon Business product page. | string |
| url required | A URL to the product on the Amazon Business website. | string |
| format required | The type of product on the Amazon Business website. For books, this is the binding. | string |
| bookInformation required | If applicable, a book-specific details for the product. | BookInformation |
| byLine required | A product's by-line contributor information such as brand, author, and editor. | < Contributor > array |
| mediaInformation required | If applicable, a media type information for the product. | MediaInformation |
| productOverview required | The general descriptive fields for the product. | < string, string > map |
| productDetails required | The nested key or value pairs indicating additional information for product parts. | < string, < string, string > map > map |
| customerReviewsSummary required | The information on the product's rating count and star rating. | CustomerReviewsSummary |
| productVariations required | 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 required | The description for the given product. | string |
| upcValues required | 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 required | 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 required | Collection of applicable badges for the ASIN. Badges indicate the product’s membership, status, or other identifiers, such as its sustainability features. | < badge > array |
QuantityPrice
Provides information about the different prices a customer can get for higher quantities.
| Name | Description | Schema |
|---|---|---|
| quantityPriceTiers optional | A collection of quantity price tier. | < QuantityPriceTier > array |
QuantityPriceTier
Defines the price for items if the quantity being purchased falls within the quantities specified in quantityDisplay field.
| Name | Description | Schema |
|---|---|---|
| quantityDisplay required | A localized string indicating the quantity range for which the price in the tier applies. | string |
| unitPrice required | The price for each unit of item in this quantity tier. | Money |
| minQuantity optional | [DEPRECATED: Please use unitPrice and quantityDisplay instead] The minimum quantity of items that a customer needs to buy to reach this price tier. | integer (int64) |
| price optional | [DEPRECATED: Please use unitPrice and quantityDisplay instead] | Price |
| savingMessage optional | [DEPRECATED: Please use unitPrice and quantityDisplay instead] The savings message of the tier. This exists only when the tier's price is lower than the basis price of the current buying option. | string |
| taxExclusivePrice optional | [DEPRECATED: Please use unitPrice and quantityDisplay instead] | TaxExclusivePrice |
Refinement Result
The data that describes the refinements used to narrow down results. These values remain the same for all pages in the result.
| Name | Description | Schema |
|---|---|---|
| categories required | A list of categories that matches the search keyword. A category id is sent in the subsequent request to get a shorter list of relevant search results. | < Category > array |
| subCategories required | A list of sub categories that matches a given category. A search subcategory Id is sent in the next request to get a shorter list of relevant products. | < SubCategory > array |
| availabilityOptions required | Two availability ids for 'in stock only' and 'include out of stock' would appear in the search refinement. Availability Id is sent as parameter in the next request to get filtered list of products. The availability filtering returns products whose offers are aligned with the availability ID request. | < Availability > array |
| deliveryDayOptions required | Two delivery day ids for 'Get It Today' and 'Get It by Tomorrow' would appear in the search refinement. | < DeliveryDay > array |
| eligibleForFreeShippingOptions required | One eligibleForFreeShippingOption Id would appear in the search refinement. EligibleForFreeShippingOption ID is sent as parameter in the next request to get a more filtered list of products. This filtering returns products with 'Free Shipping by Amazon Business.' | < EligibleForFreeShipping > array |
| primeEligible required | This can be used as a query parameter to fetch only prime eligible items. | < PrimeEligible > array |
GetProductsByAsins API Search results
The data that describes the results for the list of ASIN search.
| Name | Description | Schema |
|---|---|---|
| matchingProductCount required | The number of products that matches the search query. This number can be larger than the number of matching products the customer can view. The value is the same for all the pages in the result. | integer |
| products required | A list of products that matches the search criteria. | < ProductsResult > array |
| notFoundAsins required | A list of ASIN for which their is no product found. | < string > array |
ProductsByAsinsRequest
The request object to use when searching for a list of ASINs.
| Name | Description | Schema |
|---|---|---|
| productIds required | Accepts a list of ASINs as input. The response will return product information for each of the ASINs provided. The maximum number of ASINs allowed for each call is 30. | < string > array |
| productRegion required | The region where the customer wants to purchase the product. | enum (ProductRegion) |
| shippingRegion optional | This field determines the region where to ship the product based on the value in the shippingPostalCode. | string |
| locale required | The locale of the request in the form of an IETF language tag. Each ProductRegion supports one or more locales. This value should comply with java.util.Locale. Pattern : "^[-_]+$" | string |
| shippingPostalCode optional | The shipping postal or zip code for customer's request. This parameter doesn't support geocode. | string |
| quantity optional | The number of units the customer intends to purchase. This helps Amazon Business determine quantity-based discounts if an eligible offer is present. Defaults to 1. | integer |
| facets optional | A list of data facets to include in the response. Separate each facet with a comma. | < enum (Facets) > array |
Search products result
The data that describes the results of the search query.
| Name | Description | Schema |
|---|---|---|
| matchingProductCount required | The number of products that matches the search query. This number can be larger than the number of matching products the customer can view. The value is the same for all the pages in the result. | integer |
| searchRefinements required | Search refinements are used to share the refinements available for search result. Use searchRefinements in subsequent request to narrow down the results. For example: Search category is a type of search refinement. If a search category refinement is used in the request, the search result will limit to a given search category. | < SearchRefinementResult > array |
| refinements required | Search refinements is used to share the refinements available for search result. Use searchRefinements in subsequent request to narrow down the results. For example: Search category is a type of search refinement. If a search category refinement is used in the request, the search result will limit to a given search category. | RefinementResult |
| numberOfPages required | The number of pages of results. | integer |
| products required | A list of products that matches the search criteria. | < ProductsResult > array |
SearchRefinementResult
Search refinements are used to share the refinements available for search result. Use searchRefinements in subsequent request to narrow down the results. For example: Search category is a type of search refinement. If a search category refinement is used in the request, the search result will limit to a given search category.
| Name | Description | Schema |
|---|---|---|
| selectionType required | SelectionType is used to identify selection allowed for a given refinement. For example: MultiSelect allows to search with multiple values of a refinement. InsteadSelect allows to search with only a single refinement value. | string |
| displayValue required | Human friendly name of a given refinement type. | string |
| refinementValues required | RefinementValues holds items for a given refinement. For example: If "Brand" is a refinement, the refinementValues will have different brands available for a given product. | < RefinementValue > array |
RefinementValue
RefinementValue holds items for a given refinement. For example: If "Brand" is a refinement, the refinementValues will have different brands available for a given product.
| Name | Description | Schema |
|---|---|---|
| displayName required | The name of the item in a refinement. | string |
| searchRefinementValue required | The searchRefinementValue is used to make search request for a given refinement. | string |
SubCategory
The search subcategory provides information on relevant search subcategories for products within a category. Use subcategory to limit the results for a particular search subcategory in subsequent requests.
| Name | Description | Schema |
|---|---|---|
| displayName required | Display name is used to share more human friendly readable description of sub category. | string |
| id required | Identifies a search subcategory across a product region. | string |
Availability
Limits the product offers by 'in stock only' or 'include out of stock'. Use availability to limit the subsequent search requests.
| Name | Description | Schema |
|---|---|---|
| displayName required | Availability display name would be more user friendly to illustrate the meaning of its id. | string |
| id required | Identifies the availability option for the product. Use the Id to filter ASINs belonging to given availability option. | string |
DeliveryDay
The deliveryDay is used to limit the product offers to be Get It Today or Get It by Tomorrow.
| Name | Description | Schema |
|---|---|---|
| displayName required | DeliveryDay display name is used to share more human friendly readable description. | string |
| id required | Identifies the product offers with 'Get It Today' or 'Get It by Tomorrow' option. | string |
EligibleForFreeShipping
The EligibleForFreeShipping is used to limit the product with only 'Free Shipping by Amazon Business.' Use EligibleForFreeShipping to limit the subsequent search requests.
| Name | Description | Schema |
|---|---|---|
| displayName required | EligibleForFreeShipping display name is used to share more human friendly readable description. | string |
| id required | Identifies the search with only 'Free Shipping by Amazon Business.' | string |
PrimeEligible
The prime eligible refinement is used to give information about relevant prime eligible products.
| Name | Description | Schema |
|---|---|---|
| displayName required | The prime eligible refinement is used to give information about relevant prime eligible products. | string |
| id required | Identifies a prime eligible option. | string |
OffersResult
The data that describes the results of the offer query.
| Name | Description | Schema |
|---|---|---|
| offerCount optional | The number of offers for the ASIN after filters are applied. | integer |
| numberOfPages optional | The number of pages of results. | integer |
| featuredOffer optional | A featured offer that is selected based on eligibility requirements and criteria. | Offer |
| offers optional | A list of offers in a page. | < Offer > array |
| filterGroups optional | A list of filter groups. | < OfferFilterGroup > array |
OfferFilterGroup
A grouping of related filters.
| Name | Description | Schema |
|---|---|---|
| displayName optional | Displayable and localized filter group description. | string |
| filters optional | A list of filters for the group. | < OfferFilter > array |
OfferFilter
A filter to apply when getting offers for a product.
| Name | Description | Schema |
|---|---|---|
| id optional | Filter identifier. Pass on filterIds request parameter to apply this filter on the search request. | string |
| displayName optional | Displayable and localized filter description. | string |
BuyingGuidance
Some organizations establish guided buying policies to inform Amazon Business whether their organization supports the purchase of specified types of products. If an organization hasn't configured such policies, an API call returns the value "NONE" for the BuyingGuidance property.
Type : enum
| Value | Description |
|---|---|
| PREFERRED | The product is preferred by the organization. |
| NEGOTIATED | The product has a custom offer that’s included in a pricing deal for your organization and is shown as featured offer. Your organization encourages you to buy this offer. |
| RESTRICTED | Indicates that there might be specific requirements or approvals to purchase the product. |
| BLOCKED | The product violates one or multiple Amazon Business policies. This might include pricing issues and improper product title, image, or description. |
| NONE | The buying guidance isn't configured for the account. |
| UNKNOWN | The buying guidance is unknown. |
BuyingGuidanceV2
Some organizations establish guided buying policies to inform Amazon Business whether their organization supports the purchase of specified product types. If an organization hasn't configured such policies, an API call returns a Fragment object with value "NONE" for the title property.
| Name | Description | Schema |
|---|---|---|
| buyingGuidance required | Collection of applicable buying guidance policies for this product offer. | < Fragment > array |
ProductRegion
The region where the customer wants to purchase the product.
Type : enum
| Value | Description |
|---|---|
| DE | Germany |
| FR | France |
| UK | United Kingdom |
| IT | Italy |
| ES | Spain |
| US | United States of America |
| CA | Canada |
| JP | Japan |
Type
The taxonomy types supported by Amazon Business.
Type : enum
| Value | Description |
|---|---|
| UNSPSC | United Nations Standard Products and Services Code (UNSPSC) taxonomy differs from ECLASS. Products belonging to one category in UNSPSC are in several segments in ECLASS. |
| ECLASS | A standard requirement for a number of European customers, especially in Germany. ECLASS combines different product types together. |
ProductCondition
The possible condition of the product being sold by the merchant.
Type : enum
| Value | Description |
|---|---|
| NEW | A brand-new, unused item in perfect condition. |
| USED | A used item may be fairly worn or in perfect condition but still works perfectly. |
| COLLECTIBLE | Collectible items are rare, signed, out of print or distribution, or unique. The Seller should provide details why the product is collectible. |
| REFURBISHED | A product that's professionally restored to working condition before resale. The product is inspected, cleaned, and repaired to meet manufacturer specifications. The product might not be in its original packaging. The manufacturer warranty or warranty of the refurbishing service company might apply. The warranty should be in the Condition comments. |
| OTHER | Refers to the condition of the product that isn't new, used, collectible, refurbished, or unknown. |
| UNKNOWN | The condition of the product is unknown. |
Facets
Type : enum
| Value | Description |
|---|---|
| OFFERS | Offers for an item in the Amazon Business catalog. |
| IMAGES | Images for an item in the Amazon Business catalog. |
Code
The error code in the error response.
Type : enum
| Value | Description |
|---|---|
| PRODUCT_NOT_FOUND | The product doesn't exist in the product catalog. |
| PAGE_NOT_FOUND | The page or resource can't be found. |
| INVALID_REQUEST_PARAMETER | Some parameters are missing or incorrect. |
| SERVICE_ERROR | The service was unable to process the request. |
| EMAIL_ID_NOT_FOUND | The email ID doesn't exist or there's missing characters or numbers. |
| UNAUTHORIZED | The request lacks valid authentication credentials for the requested resource. |
| REQUEST_RATE_LIMIT_EXCEEDED | The request rate exceeds the maximum allowed transactions per second (TPS) rate. |
Type
Type : enum
| Value | Description |
|---|---|
| SUSTAINABILITY_BADGE | The product is available with sustainability certifications. |
| SUSTAINABILITY_ATTRIBUTE | Attributes associated with sustainability certification of the product. |
| BUSINESS_INVOICE_BADGE | The offer has a business invoice badge. |
| JCT_BADGE | The offer has a Japan Consumption Tax (JCT) badge. |
| PREFERRED | Buying guidance for this product is preferred. |
| RESTRICTED | Buying guidance for this product is restricted. |
| BLOCKED | Buying guidance for this product is blocked. |
| NONE | Buying guidance has not been specified for the product. |
| NEGOTIATED | The product has buying guidance as negotiated. |
| UNKNOWN | Buying guidance for this product is unknown. |
| BESTSELLER_BADGE | The product has a bestseller badge. |
| PRIME_BADGE | The product has a Prime badge. |
FulfillmentType
The fulfillment system to use for the purchased product purchase.
Type : enum
| Value | Description |
|---|---|
| AMAZON_FULFILLMENT | Amazon Business picks, packs, and ships the product directly to the buyer on behalf of the seller. |
| MERCHANT_FULFILLMENT | Sellers pick, pack, and ship the product directly to the buyer. |
| OTHER | Amazon Business or the third-party sellers ship the product from their own sources of inventory directly to buyer. |
Updated about 2 months ago
Did this page help you?