Skip to main content
When making requests to the Search, Browse, Blocks, or Similar Products API, you can use the attributes parameter to specify which product fields to include in the response. This lets you optimize response payload size by requesting only the data you need.
Only attributes marked as visible on storefront can be requested in the attributes parameter or used in filters. Attributes marked as not visible (such as internal calculated fields) will be rejected if included in API requests. See Visible on Storefront for more details.

​
Core product attributes

The following attributes are available for all products and can be requested in the attributes[] parameter:
AttributeDescription
idUnique product identifier (always included)
titleProduct title
handleURL-friendly product handle
body_htmlProduct description HTML
vendorProduct vendor/brand
product_typeProduct type classification
tagsArray of product tags
imagesArray of product images
availableProduct availability status
created_atProduct creation timestamp
updated_atProduct last update timestamp
published_atProduct publication timestamp
price_rangeProduct price range object
optionsAvailable product options (filtered by availability)
original_optionsAll product options (unfiltered)
options_v2Enhanced options array with swatch and linked metafield data
metafieldsProduct metafields object
named_tagsParsed key:value tags object
calculatedCalculated attributes object
categoryShopify Product Taxonomy category
featured_mediaFeatured product media
is_gift_cardGift card indicator
has_variants_that_require_componentsBundle product indicator
combined_listing_parent_product_idParent product ID for combined listings
combined_listing_roleRole in combined listing (PARENT/CHILD)

​
Special attributes

AttributeDescription
first_or_matched_variantReturns the first available variant or the variant matching applied filters. Must be explicitly requested.
variantsReturns an array of all product variants ordered by position. Each variant has the same fields as first_or_matched_variant. Must be explicitly requested.

​
Example API request

{
  "attributes": [
    "id",
    "title",
    "handle",
    "images",
    "price_range",
    "vendor",
    "first_or_matched_variant"
  ],
  "sort_order_code": "best-selling"
}

​
Example response with selected attributes

{
  "results": [
    {
      "id": 7003338965178,
      "title": "Premium Cotton T-Shirt",
      "handle": "premium-cotton-t-shirt",
      "images": [
        {
          "alt": "Premium Cotton T-Shirt - Front",
          "src": "https://cdn.shopify.com/s/files/product-front.jpg",
          "width": 800,
          "height": 800,
          "variant_ids": []
        }
      ],
      "price_range": {
        "from": 29.99,
        "to": 34.99,
        "compare_at_price": 39.99
      },
      "vendor": "Brand Name",
      "first_or_matched_variant": {
        "id": 41234567890123,
        "title": "Small / Blue",
        "price": "29.99",
        "sku": "TSHIRT-BLU-S",
        "compare_at_price": "39.99",
        "available": true,
        "position": 1,
        "selected_options": [
          {"name": "Size", "value": "Small"},
          {"name": "Color", "value": "Blue"}
        ]
      }
    }
  ],
  "totalResults": 150,
  "page": 1,
  "totalPages": 15
}
By default, if no attributes parameter is provided, all available attributes are included in the response. Specifying attributes helps reduce response payload size and improve performance.

​
See also