Products API

The Best Buy Developer API provides a simple, REST-based interface for our entire product catalog-past and present. This includes pricing, availability, specifications, descriptions, and images for more then one million current and historical products. In addition, we offer full archives, updated daily, to make it easier to establish our full catalog locally. Most product information is updated near real-time including product pricing.

PLEASE NOTE: Music and movie data may be used only where an ability to purchase the related music or movies from BESTBUY.COM is provided to end users. Developers using music and movie data to redirect to BESTBUY.COM must become members of the Best Buy Affiliate Program to allow the sale of music and movies through BESTBUY.COM under the terms of the Affiliate Program.

How-Tos

Some examples of how to search and return product information include:

Search for products based on a description or SKU

To search based on description, you can use one of our description attributes including longDescription, shortDescription, description or name. To search based on SKU there is a single SKU attribute. In the example below we are searching the longDescription for iPhone*. We have appended iPhone with a wildcard * so we can search for iPhones with any suffix. We also are looking for any products that have a SKU with a value of 7619002, note the or |. Finally, you may notice in our example we have updated the number of results that can be returned per page to be 15 and to return page 5 of the total 184 pages. Additional information on how to specify the number of results that should be returned per page and which page to return can be found in our Pagination section.

Search for products based on review criteria

To search based on review criteria you can use the customerReviewAverage and/or the customerReviewCount. You can also limit the product information returned using our show functionality. HINT: You can specify any additional attributes as part of your search or information return using most attributes in the Products API. In the example below we are searching for all products that have a customer review average greater then four and a customer review count greater then 100. In addition, we are limiting the product information returned to just be customer review average, customer review count, name, sku and forcing a format of json (default is xml when using the Products API).

Search for products based on a list of attribute values

To search for products based on list of attribute values, we recommend using the in operator. Most attributes can be used with the in operator. The most common attribute used is SKU. Using the in operator will also help to avoid Query Per Second errors (QPS). Additional information is available in our Rate Limit section. In the example below use the in operator to search for products any products that are a part of the list of SKUs.

Using the Keyword Search to find products:

Using our Keyword Search functionality you can search across several common attributes using a single call. These attributes include:

name

manufacturer

shortDescription

longDescription

features.feature

details.value

In the example below we use Keyword Search to find all products that contain "touchscreen" and "apple" as part of the Keyword Search attributes. We then limit those products to those that are currently selling for under 500 dollars AND are only within the Computer and Tablet category. HINT: Use our Categories API to find different categories.

The customerReviewAverage attribute provides an average of all the ratings submitted for a product by reviewers.The customer can rate the product on a scale of 1-5 where 5 is the highest. Ratings may be returned using decimals (example 3.5).

The customerTopRated attribute identifies if the product is top rated, based on the ratings given by the reviewers. If the Avg rating >= 4.5 and Qty of ratings >= 15, customerTopRated is set to be "true", else is set to "false".

The longDescription attribute provides a detailed description about a product with HTML formatting (if applicable.)

Type

string

Related Attributes

longDescription, shortDescription, shortDescriptionHtml, description

Example

"The 1.5" color screen and 28 infrared LEDs on this Barska BG11753 6.0MP trail camera allow you to capture and view images and videos during the day or at night. A water-resistant casing guards the camera against moisture damage."

Pricing and Sales Ranking

As part of the Best Buy Pricing attributes we make it easy to identify the product price, if a product is on sale, how much you can save and even when we made our last pricing changes. We also provide sales ranking over given time periods so you can have an idea of the best-sellers.

The lowPriceGuarantee attribute identifies whether a product qualifies for the Best Buy Low Price Guarantee. More information on the Best Buy Low Price Guarantee can be found at BESTBUY.COM Low Price Guarantee

The onSale attribute is a calculated field based on a comparison of regularPrice and salePrice. If the salePrice is less than the regularPrice, the onSale attribute will return 'true'. If salePrice is equal to regularPrice, then the onSale attribute will return 'false'.

The priceRestriction attribute identifies if there are pricing restriction requirements related to the display of the sale price of a product. The MAP restriction identifies the Minimum Advertised Price. This means the actual selling price may not be shown until the product is added to the cart. The ICR restricts identifies the In-Checkout Rebate price. This means the actual selling price may not be shown until the customer is ready to checkout. For those products that have MAP or ICR display restrictions, the lowest salePrice will only show to those developers that have a privileged key. There are guidelines for displaying these values that you should have received along with your privileged key. If you don't have a privileged key then these requirements will not apply to you.

Type

string

Notes

If the priceRestriction field is ICR or MAP the salePrice may be the same as the regularPrice. If you are referring customers to BESTBUY.COM or Commerce Express for check-out all pricing display requirements will be handled for you. The customer will be shown and charged the lowest price as part of check-out.

The priceWithPlan.newTwoYearPlan attribute is returned as part of a mobile phone plan collection. The priceWithPlan.newTwoYearPlan identifies the mobile phone price when purchased with a new 2-year plan.

The priceWithPlan.upgradeTwoYearPlan attribute is returned as part of a mobile phone plan collection. The priceWithPlan.upgradeTwoYearPlan identifies the mobile phone price when purchased as part of an upgrade plan.

The priceWithPlan.newTwoYearPlanSalePrice attribute is returned as part of a mobile phone plan collection. The priceWithPlan.newTwoYearPlanSalePrice identifies the mobile sale phone price when purchased with a new 2-year plan.

The priceWithPlan.upgradeTwoYearPlanSalePrice attribute is returned as part of a mobile phone plan collection. The priceWithPlan.upgradeTwoYearPlanSalePrice identifies the mobile phone sale price when purchased as part of an upgrade plan.

The priceWithPlan.newTwoYearPlanRegularPrice attribute is returned as part of a mobile phone plan collection. The priceWithPlan.newTwoYearPlanRegularPrice identifies the mobile phone price when purchased with a new 2-year plan.

The priceWithPlan.upgradeTwoYearPlanRegularPrice attribute is returned as part of a mobile phone plan collection. The priceWithPlan.upgradeTwoYearPlanRegularPrice identifies the mobile phone price when purchased as part of an upgrade plan.

The salePrice attribute identifies the current selling price of a product.

Type

currency

Notes

The salePrice may return true even though the salePrice=regularPrice. This is due the actual sale price not being returned due to pricing restrictions. The customer will see the actual sale price as part of the check out process. See the priceRestriction attribute for additional information.

The friendsAndFamilyPickup attribute identifies if product is part of the Best Buy friends and family pickup offering. Additional information can be found by going to Best Buy Friends and Family Information

The orderable attribute provides additional information about the product ordering status. The available statuses include Available, ComingSoon, InStoreOnly, NotOrderable, PreOrder, SpecialOrder, SoldOut. The Available status identifies products that are available for sale (does not determine if they are for sale exclusively online or in a store.) The ComingSoon status identifies products that are coming but not yet ready for sale. The InStoreOnly attribute identifies products that can only be purchased in a store (see inStoreAvailability for more information.) The NotOrderable status identifies product that are available for sale at this time. The PreOrder status identifies products that are available for purchased but will not be fulfilled (or shipped) until a later date. The SpecialOrder status identifies those products that require special delivery (see the SpecialOrder attribute for more details.) The SoldOut status identifies products that are not currently available for sale because they have been sold out.

Type

string

Notes

The orderable must be equal to Available, SpecialOrder or PreOrder to be purchased through the BESTBUY.COM website. If orderable is equal to any other statuses the product cannot be purchased online at this time

The specialOrder attribute identifies whether a product will have special handling for fulfillment and delivery. An example of special handling instructions could include message such as “We cannot deliver to P.O. boxes or APO/FPO addresses.”

Links

The Links attributes provide a way for you to redirect customers to a BESTBUY.COM product detail page or create a BESTBUY.COM cart on their behalf while including the product in the cart. For our affiliate partners we provide this same functionality but use a special link so you can get credit for your sale. Additional information on the affiliate program can be found here.

The linkShareAffilitateAddToCartUrl attribute is for those participating in the Best Buy affiliate program. Affiliates add their (LID) to their query request and the URL generated will direct the customer to the BESTBUY.COM with this item in their cart and credit the affiliate with the sale.

Type

string

Notes

Attribute is not querable; Must specify LinkShare ID in query. LID="yourLinkShareAffiliateId"

The linkShareAffilitateUrl attribute is for those participating in the Best Buy affiliate program. Affiliates add their (LID) to their query request and the URL generated will direct the customer to the BESTBUY.COM product detail page and credit the affiliate with the sale.

Type

string

Notes

Attribute is not querable; Must specify LinkShare ID in query. LID="yourLinkShareAffiliateId"

Categorizations

Best Buy provides multiple ways to group products based on your needs.

The department, class and subclass attributes provide categorization structure or groupings of products. These attributes are returned as separate attributes but are related. The department attribute provides the more general categorization while the class and subclass attributes narrow the focus to be more specific. The class and subclass attributes are less volatile than category attributes and are the recommended attributes for grouping products.

The categoryPath attributes provide a hierarchal view of a product returned as a collection. The collections start with the most general categorization, while subsequent categories narrow to be more specific. The number of categories returned can be 3+ layers deep. The products within the categories also tend to be slightly more volatile than department, class and subclass groupings.

The list attributes are used for specific events like Valentine's day. These lists are curated by a Best Buy merchant teams for customer visibility for a specific event or purpose.

The categoryPath.id attribute is part of a hierarchical structure used to group similar products together. This product will return a collection of one to many children of all categories a product is associated with in the form of the category id

The categoryPath.name attribute is part of a hierarchical structure used to group similar products together. This product will return a collection of one to many children of all the categories a product is associated with in the form of the category name

The lists.endDate attribute represent the end date that the product would be associated to a list. Lists represent a curated group of products that are grouped together by Best Buy using a common identifier. Lists are returned as a collection including a list name, lists.listId, start and end date. An example of a list would be HolidayBuyingGuide2014.

The lists.listId attribute provides an identifier for the list. Lists represent a curated group of products that are grouped together by Best Buy using a common identifier. Lists are returned as a collection including a list name lists.listId, start and end date. An example of a list would be HolidayBuyingGuide2014.

The lists.startDate attribute represent the start date that the product would be associated to a list. Lists represent a curated group of products that are grouped together by Best Buy using a common identifier. Lists are returned as a collection including a list name lists.listId, start and end date. An example of a list would be HolidayBuyingGuide2014.

Offers and Deals

The Best Buy offer attributes provide a comprehensive view into all of the deals at Best Buy. This includes what is in our Sunday circular (also available online) and our "Deal of the Day," to name a few. We provide images and offer descriptions to further support you when listing Best Buy products. Offer information is grouped together in a collection. Each product can have one or more offers associated to it. Each offer has an identifier, start/end dates and any supporting information.

Offer types can include the following: Special offers identified by Best Buy marketing managers. Featured offers consist of a set of special offers as defined by the BESTBUY.COM marketing teams. Weekly digital inserts identify products that are a part of weekly insert that can be found in a Sunday newspaper (this information is also available on http://www.bestbuy.com under "Weekly Deals".) Typically there are between 400-1000 products that are a part of our weekly digital inserts. "Deal of the Day" consists of a small group of products being promoted for one day only.

GeekSquad Plans/Services

The GeekSquad plans and service attributes provide both a high-level overview of the GeekSquad plans that can be purchased for a product and also provide the details for a specific service plan. Additional information about GeekSquad can be found on the GeekSquad website

If you would like to find out the high-level information about GeekSquad protection plans available for a product, the attributes include:

protectionPlans.name

protectionPlans.productId

protectionPlans.regularPrice

protectionPlans.salePrice

protectionPlans.sku

protectionPlans.term

protectionPlans.type

Some examples of how to return available GeekSquad protection plans for a product include:

If you would like to find out more information about a specific GeekSquad protection plan, this can be done by looking at the protectionPlans.sku that is returned for a product. You can also look at overall detailed protection plans available by looking at type="blacktie". Keep in mind that not all plans can be purchased for all products. We systematically identify what plans can be associated to a product by looking at the department/class/subclass of a product and its price. The price must be between the protectionPlanHighPrice and the protectionPlanLowPrice. The attributes that will describe a detailed plan include:

protectionPlanDetails.states

protectionPlanDetails.termsAndConditions

protectionPlanHighPrice

protectionPlanLowPrice

protectionPlanTerm

protectionPlanType

Some examples of how to return GeekSquad protection plan details include:

The attribute protectionPlans.Name identifies the name of the GeekSquad protection plan that is associated to originating SKU. Returns as part of a collection identifying high level information about a plan for a particular SKU. There can be multiple plans per product.

The attribute protectionPlans.productId identifies the ID of the GeekSquad protection plan that is associated to originating SKU. Returns as part of a collection identifying high level information about a plan for a particular SKU. There can be multiple plans per product.

The attribute protectionPlans.regularPrice identifies the regular price of the GeekSquad protection plan that is associated to originating SKU. Returns as part of a collection identifying high level information about a plan for a particular SKU. There can be multiple plans per product.

The attribute protectionPlans.salePrice identifies the sale price of the GeekSquad protection plan that is associated to originating SKU. Returns as part of a collection identifying high level information about a plan for a particular SKU. There can be multiple plans per product.

The attribute protectionPlans.sku identifies the SKU of the GeekSquad protection plan that is associated to originating SKU. Returns as part of a collection identifying high level information about a plan for a particular SKU. There can be multiple plans per product.

The attribute protectionPlans.term identifies the term of the GeekSquad protection plan that is associated to originating SKU. Returns as part of a collection identifying high level information about a plan for a particular SKU. There can be multiple plans per product.

The attribute protectionPlans.type identifies the type of the GeekSquad protection plan that is associated to originating SKU. Returns as part of a collection identifying high level information about a plan for a particular SKU. There can be multiple plans per product.

The attribute protectionPlanDetails.state identifies the supporting states for originating GeekSquad protection plan. This attribute is used to provide a detailed explanation for the originating GeekSquad protection plan. There is one detailed explanation of the Terms and Conditions per GeekSquad protection plan SKU.

The attribute protectionPlanDetails.termsAndConditions identifies all terms and conditions associated to the originating GeekSquad protection plan. This attribute is used to provide a detailed explanation for the originating GeekSquad protection plan. There is one detailed explanation per GeekSquad protection plan SKU.

The attribute protectionPlanHighPrice identifies the upper limit of the selling price of the product to which the GeekSquad Protection Plan is associated. This attribute is used to provide a detailed explanation for the originating GeekSquad protection plan.

The attribute protectionPlanLowPrice identifies the lower limit of the selling price of the product to which the GeekSquad Protection Plan is associated. This attribute is used to provide a detailed explanation for the originating GeekSquad protection plan.

The attribute protectionPlanTerm identifies the term (length) of the originating GeekSquad protection plan. This attribute is used to provide a detailed explanation for the originating GeekSquad protection plan.

The attribute protectionPlanType identifies the type of protection plan associated to the originating GeekSquad protection plan. This attribute is used to provide a detailed explanation for the originating GeekSquad protection plan.

Listing Products

We offer various metadata to support you when listing Best Buy products. This information will include information such as if a product is active, if it is new or refurbished or the type of product (music, movie, hardgood, bundle, game, blacktie, or software) to name a few.

The active attribute identifies if products are currently supported in the BESTBUY.COM catalog. If you want inactive products you must specify active=false or for a mix of active and inactive products use active=*.

The type attribute identifies the "type" of product being sold. There are seven types of products including: hardgood, music, movie, game, blackTie, software and bundle. The "hardgood" type represents products that are not of type music, movie, game, blackTie, software or bundle. The "music" type will include music products that are both material and digital (downloadable.) An example of type=music product would include a Beethoven CD. The "movie" type represents products that can also be material and digital (downloadable.) An example of type=movie would include a Batman DVD. The "game" will include game products that also can be material and digital (download.) An example of type=game would include SkyLander SwapForce. The "blacktie" type represents extended warranty services provided by the Best Buy GeekSquad team. An example of type=blacktie would include 1-Year Accidental Damage Protection Plan - Geek Squad. The "software" type represents products that can also be material and digital (download.) An example would include Adobe Acrobat. The "bundle" represents a grouping of products. They can be both material and digital. An example would include a bundle of a computer desktop, a monitor and virus protection.

Best Buy Specific Attributes

The Best Buy specific attributes are those attributes that are most useful for internal Best Buy specific projects. Questions about the use of these attributes can be directed to our Best Buy Developer API Team via email at developer@bestbuy.com.

We do not support your browser. Neither does Microsoft.

We're glad that you're excited about Best Buy's APIs. However, you're using a browser that's too old to view our new developer site. We encourage you to switch to a newer browser, preferably a recent version of Chrome, Firefox, or Internet Explorer.