Available attributes for API requests

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 computed fields, will be rejected if included in API requests. See Visible in API responses for more details.

Core product attributes

The following attributes are available for all products and can be requested in the attributes[] parameter:

Attribute	Description
`id`	Unique product identifier (always included)
`title`	Product title
`handle`	URL-friendly product handle
`body_html`	Product description HTML
`vendor`	Product vendor/brand
`product_type`	Product type classification
`tags`	Array of product tags
`images`	Array of product images
`available`	Product availability status
`created_at`	Product creation timestamp
`updated_at`	Product last update timestamp
`published_at`	Product publication timestamp
`price_range`	Product price range object
`total_inventory`	Sum of every variant’s `inventory_quantity` across all variants and the locations in the store’s inventory location scope (all locations by default). Product-level rollup, not market-scoped.
`options`	Available product options (filtered by availability)
`original_options`	All product options (unfiltered)
`options_v2`	Enhanced options array with swatch and linked metafield data
`metafields`	Product metafields object
`named_tags`	Parsed key:value tags object
`calculated`	Computed attributes object
`category`	Shopify Product Taxonomy category
`featured_media`	Featured product media
`is_gift_card`	Gift card indicator
`has_variants_that_require_components`	Bundle product indicator
`published_on_web`	Whether the product is published to the Online Store sales channel
`published_on_app`	Whether the product is published to your storefront app sales channel
`available_market_ids`	Shopify Market IDs the product is available in (requires markets sync)
`combined_listing_parent_product_id`	Parent product ID for combined listings
`combined_listing_role`	Role in combined listing (PARENT/CHILD)

Special attributes

Attribute	Description
`first_or_matched_variant`	Returns the first available variant or the variant matching applied filters. Must be explicitly requested.
`variants`	Returns an array of all product variants ordered by position. Each variant has the same fields as `first_or_matched_variant`. Must be explicitly requested.
`collection_titles`	Array of collection titles the product belongs to. Excluded by default to keep responses small. Must be explicitly requested. Supported by the Search, Browse, and Blocks APIs.
`selling_plans`	Selling plan groups the product is enrolled in, with the plans, billing and delivery policies, categories, and max discount percentage. Excluded by default. Must be explicitly requested. See Selling plans.

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.

Selecting nested fields

In addition to top-level attributes, the attributes parameter accepts dot-notation paths that let you trim nested objects, slice arrays, and filter collections to just the entries you need. This keeps responses small for storefront tiles and product detail views without making a separate request per shape. Selectors are scoped to the response shape. They do not change which products are returned. Use filters to control the product set; use field selection to control the payload per product.

Field selection is a no-op for plain dotted paths (for example, variants.price) — backward compatible with existing integrations. Modifiers ([], [n], [start:end], [key=value]) opt you into the trimming behavior described below.

Selector forms

Selector	What it does
`title`	Includes the top-level field.
`seo.title`	Includes a single nested field on an object.
`images[:2].src`	Slices the first two images and keeps only the `src` field on each.
`images[0]`	Returns just the first image.
`variants[]`	Includes the full array (equivalent to `variants` for the variants list).
`variants[].id`	Trims every variant object to the listed leaf fields. Combine multiple leaf selectors to keep more than one field.
`variants[sku=ABC123]`	Keeps only variants whose `sku` equals `ABC123`.
`variants[sku=ABC,DEF]`	Keeps variants whose `sku` equals `ABC` or `DEF`. Values are comma-separated.
`metafields[namespace=custom]`	Keeps only product metafields under the `custom` namespace.
`metafields[namespace=custom,greyson]`	Keeps product metafields under any of the listed namespaces.
`metafields.custom`	Dotted form of the whole-namespace selector. Returns everything under `custom`.
`metafields.custom.color`	Returns a single metafield key inside a namespace.
`variants[].inventory[location_id=123]`	Keeps inventory entries for the given location on every variant.
`variants[].metafields.custom.color`	Keeps only the `custom.color` metafield record on every variant.
`variants[].metafields[namespace=custom]`	Keeps variant metafield records under the `custom` namespace.
`first_or_matched_variant.metafields.custom.color`	Keeps only the `custom.color` metafield record on the matched variant.

Multiple selectors that target the same collection are merged. For example, variants[].id plus variants[].price returns variants trimmed to {id, price}.

Slicing and indexing

[start:end] returns the half-open slice, using zero-based positions.
[n] returns the single entry at that position, still wrapped in the array.
[:n] and [n:] are shorthand for “first n” and “from n onward”.
Negative indexes are not supported.

Slices and indexes for variants use the storefront-visible position order. Hidden variants (for example, B2B-only variants when the request is not B2B) are excluded before the slice is applied.

Equality filters

[field=value] keeps only the entries whose field equals value. Values can be unquoted, single-quoted, or double-quoted. Quote them when the value contains spaces or punctuation. Numeric values compare numerically, so price=110 matches a stored 110.00. Pass a comma-separated list to match any of several values: variants[sku=ABC,DEF] keeps variants whose sku equals ABC or DEF. Commas inside a quoted value are treated as part of the value, so variants[sku="A,B"] matches the single SKU A,B. Empty members and trailing commas (for example, variants[sku=ABC,]) are rejected as parse errors. Repeating the same filter across multiple selectors unions the value sets in request order. For example, requesting both metafields[namespace=custom] and metafields[namespace=greyson] returns metafields from both namespaces. Different filter keys on the same collection, or mixing a filter with a positional modifier, still conflict.

For arrays like variants and images, filtering trims the array in place. The parent product is still returned even if no entries match.
For map-shaped fields like product metafields ({namespace: {key: value}}) and variant inventory_levels ({location_id: quantity}), filtering trims the map while preserving its shape.
Filtering on a field that doesn’t exist on the entries (or on a hidden internal column) is a no-op rather than an error, so the response shape stays consistent.

Equality is the only supported operator. Comparison operators (>, <, >=, <=, !=), boolean combinators (AND/OR, &&/||), and IN lists are rejected at validation time.

Trimming metafields

Product metafields is a {namespace: {key: value}} map, and it accepts two selector spellings:

Namespace set — metafields[namespace=custom,greyson] returns only the listed namespaces. Use this when you want one or more whole namespaces in a single selector.
Dotted path — metafields.custom returns the whole custom namespace, and metafields.custom.color returns just the color key inside it. Use dotted form when you want individual keys.

A whole-namespace selector subsumes a key selector for the same namespace, so requesting both metafields.custom and metafields.custom.color returns all of custom. Namespaces and keys must consist of letters, digits, _, -, or .. The bracket-then-dot spelling metafields[namespace=custom].color is rejected with a 400. Use the dotted form to reach into a namespace. Products missing a requested namespace or key drop the entry rather than emit null, and a product with no metafields at all returns metafields: {}.

Trimming variant metafields

Variant metafields is a list of {namespace, key, value, …} records rather than a map. You can trim it on both variants[] and first_or_matched_variant with these selectors:

Selector	What it returns
`variants[].metafields.<namespace>.<key>`	The single matching record on every variant.
`variants[].metafields.<namespace>`	Every record in the namespace on every variant.
`variants[].metafields[namespace=custom,other]`	Every record in any of the listed namespaces on every variant.
`variants[].metafields`	The full list on every variant.
`first_or_matched_variant.metafields.<namespace>.<key>`	The single matching record on the matched variant.
`first_or_matched_variant.metafields.<namespace>`	Every record in the namespace on the matched variant.
`first_or_matched_variant.metafields[namespace=custom]`	Every record in the listed namespaces on the matched variant.

Keep these rules in mind:

Selectors on each root are independent. A variants[].metafields.* selector never trims first_or_matched_variant, and the reverse is also true. Request both when you need both trimmed.
The trimmed value stays a list with the original record shape. A variant with no matching records returns metafields: [].
Namespaces and keys must consist of letters, digits, _, -, or .. Hyphenated and digit-leading keys such as shopify.color-pattern are supported.
The variants[] form requires the [] modifier. A plain dotted path such as variants.metafields.custom.color is a no-op and returns the full list, matching the behavior of other plain dotted paths.
You can combine metafield selectors with other variant leaf selectors, such as variants[].id.

These selectors return a 400 with the field_projection error shape:

Chains deeper than <namespace>.<key>.
Any filter other than [namespace=…], such as [key=…]. Keys repeat across namespaces, so a key alone does not identify a record.
Positional modifiers such as [0] or [:2] on metafields, and modifiers on the namespace or key segment.
A dotted path after [namespace=…], such as variants[].metafields[namespace=custom].color. Use variants[].metafields.custom.color instead.

The same selectors work in browse, search, and blocks responses.

`first_or_matched_variant` and field selection

Trimming or filtering variants does not affect first_or_matched_variant. The matched variant is still derived from the full variant set, so a request like variants[sku=NOPE] combined with first_or_matched_variant returns an empty variants array alongside the regular matched variant.

Validation and errors

Each collection may carry only one array modifier across all selectors in a single request. Mixing two modifiers on the same collection (for example, variants[:2] and variants[sku=ABC] in the same request) returns a 400 with a structured body:

{
  "error": "field_projection",
  "message": "Conflicting modifiers on `variants`. A collection may use only one array modifier (slice, index, `[]`, or filter) across all selectors.",
  "path": "variants[sku=ABC]"
}

The same error shape is returned for malformed paths, unsupported operators, negative indexes, and selectors the projection layer cannot execute. Examples include a positional modifier on metafields and a dotted chain after metafields[namespace=…]. The response points you at the equivalent dotted form that the projection layer can honor. Rejecting these up front avoids silently returning the untrimmed payload. A bracket modifier on a sub-path segment of a map column (for example, selling_plans.groups[name=Subscribe].plans or metafields.custom[key=color]) is a special case. It does not return a 400. The predicate is dropped and the request is served as the equivalent dotted form (for example, selling_plans.groups.plans), which returns the full set of entries rather than a filtered subset. Use the dotted form directly when you want that behavior, and filter the extra entries client-side if you need to narrow the result.

Examples

Return product tiles with the first two images, only the matched variant’s price, and metafields from the custom namespace:

{
  "attributes": [
    "id",
    "title",
    "handle",
    "images[:2].src",
    "price_range",
    "variants[sku=TSHIRT-BLU-S].price",
    "metafields[namespace=custom,greyson]"
  ]
}

Return a single metafield key using the dotted form:

{
  "attributes": [
    "id",
    "title",
    "metafields.custom.color"
  ]
}

Return one metafield from each variant and a different metafield from the matched variant:

{
  "attributes": [
    "id",
    "variants[].id",
    "variants[].metafields.custom.bucket_listing",
    "first_or_matched_variant.metafields.other.bucket_listing"
  ]
}

Each variant keeps only its custom.bucket_listing record, and the matched variant keeps only its other.bucket_listing record. Return inventory at a single location for every variant:

{
  "attributes": [
    "id",
    "variants[].id",
    "variants[].inventory[location_id=123]"
  ]
}

Field selection respects API visibility. Attributes hidden from storefront responses are rejected the same way they would be in a plain attributes request. Selectors can never re-expose a hidden field.

Overview

Metafields

Available attributes for API requests

Core product attributes

Special attributes

Example API request

Example response with selected attributes

Selecting nested fields

Selector forms

Slicing and indexing

Equality filters

Trimming metafields

Trimming variant metafields

`first_or_matched_variant` and field selection

Validation and errors

Examples

See also

​Core product attributes

​Special attributes

​Example API request

​Example response with selected attributes

​Selecting nested fields

​Selector forms

​Slicing and indexing

​Equality filters

​Trimming metafields

​Trimming variant metafields

​first_or_matched_variant and field selection

​Validation and errors

​Examples

​See also

Core product attributes

Special attributes

Example API request

Example response with selected attributes

Selecting nested fields

Selector forms

Slicing and indexing

Equality filters

Trimming metafields

Trimming variant metafields

`first_or_matched_variant` and field selection

Validation and errors

Examples

See also