openapi: 3.0.3
info:
  title: Best Buy Products API
  description: >-
    Access over one million current and historical Best Buy products with real-time
    pricing, availability, specifications, images, customer reviews, and categorization
    data. Supports detailed queries by SKU, keyword search, and filtering across
    all product attributes.
  version: 1.0.0
  contact:
    url: https://developer.bestbuy.com
  x-generated-from: documentation
servers:
  - url: https://api.bestbuy.com/v1
    description: Best Buy API v1
security:
  - apiKey: []
tags:
  - name: Products
    description: Product catalog queries and retrieval
paths:
  /products:
    get:
      operationId: listProducts
      summary: Best Buy List Products
      description: >-
        Query the Best Buy product catalog with filtering, keyword search, pagination,
        and sorting. Returns product data including pricing, availability, specifications,
        images, and categorization.
      tags:
        - Products
      parameters:
        - name: apiKey
          in: query
          required: true
          description: Your Best Buy developer API key.
          schema:
            type: string
          example: YourAPIKey
        - name: format
          in: query
          required: false
          description: Response format - json or xml.
          schema:
            type: string
            enum:
              - json
              - xml
            default: json
          example: json
        - name: show
          in: query
          required: false
          description: Comma-separated list of attributes to return. Use 'all' for complete data.
          schema:
            type: string
          example: sku,name,salePrice,onSale
        - name: pageSize
          in: query
          required: false
          description: Number of results per page. Maximum 100.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
          example: 10
        - name: page
          in: query
          required: false
          description: Page number for pagination.
          schema:
            type: integer
            minimum: 1
            default: 1
          example: 1
        - name: sort
          in: query
          required: false
          description: Sort attribute and direction, e.g. salePrice.asc or name.dsc.
          schema:
            type: string
          example: salePrice.asc
        - name: search
          in: query
          required: false
          description: Keyword search across product name, manufacturer, descriptions, and features.
          schema:
            type: string
          example: laptop
        - name: cursorMark
          in: query
          required: false
          description: Cursor mark for iterating large datasets (10+ pages). Use * to initiate.
          schema:
            type: string
          example: '*'
      responses:
        '200':
          description: Successful response with product list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductListResponse'
              examples:
                ListProducts200Example:
                  summary: Default listProducts 200 response
                  x-microcks-default: true
                  value:
                    from: 1
                    to: 10
                    total: 125000
                    currentPage: 1
                    totalPages: 12500
                    queryTime: '0.023'
                    totalTime: '0.043'
                    partial: false
                    canonicalUrl: https://api.bestbuy.com/v1/products?format=json&pageSize=10
                    products:
                      - sku: 1234567
                        name: Sample Laptop 15" 16GB RAM
                        regularPrice: 999.99
                        salePrice: 849.99
                        onSale: true
                        manufacturer: SampleBrand
                        modelNumber: SB-1234
                        image: https://pisces.bbystatic.com/image2/BestBuy_US/images/products/1234/1234567_sd.jpg
                        url: https://www.bestbuy.com/site/sample-laptop/1234567.p
                        addToCartUrl: https://www.bestbuy.com/cart/api/v1/addToCart?items%5B0%5D%5BskuId%5D=1234567
                        inStoreAvailability: true
                        onlineAvailability: true
                        type: HardGood
                        categoryPath:
                          - id: abcat0500000
                            name: Computers & Tablets
        '400':
          description: Bad request - invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /products/{sku}:
    get:
      operationId: getProductBySku
      summary: Best Buy Get Product by SKU
      description: >-
        Retrieve a single Best Buy product by its SKU number with full product details
        including pricing, availability, specifications, images, and categorization.
      tags:
        - Products
      parameters:
        - name: sku
          in: path
          required: true
          description: The Best Buy product SKU number.
          schema:
            type: integer
          example: 1234567
        - name: apiKey
          in: query
          required: true
          description: Your Best Buy developer API key.
          schema:
            type: string
          example: YourAPIKey
        - name: format
          in: query
          required: false
          description: Response format - json or xml.
          schema:
            type: string
            enum:
              - json
              - xml
            default: json
          example: json
        - name: show
          in: query
          required: false
          description: Comma-separated list of attributes to return.
          schema:
            type: string
          example: sku,name,salePrice,onSale,shortDescription
      responses:
        '200':
          description: Successful response with product details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
              examples:
                GetProductBySku200Example:
                  summary: Default getProductBySku 200 response
                  x-microcks-default: true
                  value:
                    sku: 1234567
                    name: Sample Laptop 15" 16GB RAM
                    regularPrice: 999.99
                    salePrice: 849.99
                    onSale: true
                    manufacturer: SampleBrand
                    modelNumber: SB-1234
                    shortDescription: High-performance laptop for everyday computing.
                    longDescription: Detailed description of the laptop features and specifications.
                    image: https://pisces.bbystatic.com/image2/BestBuy_US/images/products/1234/1234567_sd.jpg
                    url: https://www.bestbuy.com/site/sample-laptop/1234567.p
                    addToCartUrl: https://www.bestbuy.com/cart/api/v1/addToCart?items%5B0%5D%5BskuId%5D=1234567
                    inStoreAvailability: true
                    onlineAvailability: true
                    type: HardGood
                    class: LAPTOPS/NOTEBOOKS
                    classId: 539
                    subclass: ALL LAPTOPS
                    subclassId: 2408
                    department: COMPUTERS
                    departmentId: 3
                    categoryPath:
                      - id: abcat0500000
                        name: Computers & Tablets
                    customerReviewCount: 450
                    customerReviewAverage: 4.5
        '404':
          description: Product not found for the given SKU.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: query
      name: apiKey
      description: API key obtained by registering at developer.bestbuy.com.

  schemas:
    ProductListResponse:
      title: ProductListResponse
      type: object
      description: Paginated list of Best Buy products.
      properties:
        from:
          type: integer
          description: Starting index of returned results.
          example: 1
        to:
          type: integer
          description: Ending index of returned results.
          example: 10
        total:
          type: integer
          description: Total number of matching products.
          example: 125000
        currentPage:
          type: integer
          description: Current page number.
          example: 1
        totalPages:
          type: integer
          description: Total number of pages available.
          example: 12500
        queryTime:
          type: string
          description: Time taken to execute the query in seconds.
          example: '0.023'
        totalTime:
          type: string
          description: Total response time in seconds.
          example: '0.043'
        partial:
          type: boolean
          description: Whether the response is a partial result.
          example: false
        canonicalUrl:
          type: string
          description: The canonical URL for this query.
          example: https://api.bestbuy.com/v1/products?format=json&pageSize=10
        nextCursorMark:
          type: string
          description: Cursor mark for fetching the next page when using cursor-based pagination.
          example: AoE=
        products:
          type: array
          description: Array of product objects.
          items:
            $ref: '#/components/schemas/Product'

    Product:
      title: Product
      type: object
      description: A Best Buy product with pricing, availability, and metadata.
      properties:
        sku:
          type: integer
          description: Unique Best Buy product identifier (SKU number).
          example: 1234567
        name:
          type: string
          description: Product display name.
          example: Sample Laptop 15" 16GB RAM
        regularPrice:
          type: number
          format: double
          description: Regular (non-sale) price in USD.
          example: 999.99
        salePrice:
          type: number
          format: double
          description: Current sale price in USD.
          example: 849.99
        onSale:
          type: boolean
          description: Whether the product is currently on sale.
          example: true
        manufacturer:
          type: string
          description: Product manufacturer or brand name.
          example: SampleBrand
        modelNumber:
          type: string
          description: Manufacturer model number.
          example: SB-1234
        shortDescription:
          type: string
          description: Brief product description.
          example: High-performance laptop for everyday computing.
        longDescription:
          type: string
          description: Detailed product description.
          example: Detailed description of the laptop features and specifications.
        image:
          type: string
          description: URL of the primary product image.
          example: https://pisces.bbystatic.com/image2/BestBuy_US/images/products/1234/1234567_sd.jpg
        url:
          type: string
          description: URL of the product page on bestbuy.com.
          example: https://www.bestbuy.com/site/sample-laptop/1234567.p
        addToCartUrl:
          type: string
          description: URL for adding this product to the shopping cart.
          example: https://www.bestbuy.com/cart/api/v1/addToCart?items%5B0%5D%5BskuId%5D=1234567
        inStoreAvailability:
          type: boolean
          description: Whether the product is available for in-store purchase.
          example: true
        onlineAvailability:
          type: boolean
          description: Whether the product is available online.
          example: true
        type:
          type: string
          description: Product type (HardGood, Movie, Music, Game, Software, etc.).
          example: HardGood
        class:
          type: string
          description: Product class name.
          example: LAPTOPS/NOTEBOOKS
        classId:
          type: integer
          description: Product class identifier.
          example: 539
        subclass:
          type: string
          description: Product subclass name.
          example: ALL LAPTOPS
        subclassId:
          type: integer
          description: Product subclass identifier.
          example: 2408
        department:
          type: string
          description: Department name.
          example: COMPUTERS
        departmentId:
          type: integer
          description: Department identifier.
          example: 3
        categoryPath:
          type: array
          description: Hierarchical category path from root to this product's category.
          items:
            $ref: '#/components/schemas/CategoryRef'
        customerReviewCount:
          type: integer
          description: Total number of customer reviews.
          example: 450
        customerReviewAverage:
          type: number
          format: double
          description: Average customer review rating out of 5.
          example: 4.5
        priceUpdateDate:
          type: string
          format: date-time
          description: Date and time the price was last updated.
          example: '2026-04-01T10:00:00Z'

    CategoryRef:
      title: CategoryRef
      type: object
      description: A reference to a product category in the hierarchy.
      properties:
        id:
          type: string
          description: Category identifier.
          example: abcat0500000
        name:
          type: string
          description: Category display name.
          example: Computers & Tablets

    ErrorResponse:
      title: ErrorResponse
      type: object
      description: Error response returned when a request fails.
      properties:
        status:
          type: integer
          description: HTTP status code.
          example: 400
        error:
          type: string
          description: Error type or code.
          example: Bad Request
        message:
          type: string
          description: Human-readable description of the error.
          example: Invalid query parameter provided.