Browse API: Browse Collection Page

Authorization

X-Storefront-Access-Token

string

required

Token-based authentication header in the form of <YOUR_LAYERS_TOKEN>.

Headers

Content-Type

string

default:"application/json"

required

string

default:"application/json"

required

Path Parameters

collection_handle

string

required

The handle of the collection you wish to browse.

Body

sort_order_code

string

required

Code of the sort order.

dynamicLinking

object

Dynamic Linking allows you to promote specific products to the top of the first page of results. This feature takes priority over merchandising rules and sort orders.

Show Properties

products

array

required

Array of product identifiers (handles or IDs) in the order you want them to appear. The first item will be position 1, second item position 2, etc.

Handles: String values (e.g., "summer-dress-blue")
IDs: Numeric values (e.g., 8234567890123)
Mixed: You can combine both handles and IDs in the same array

Behavior:

Only applies on the first page of results (page 1)
Non-existent or unavailable products are silently skipped
Subsequent products shift up to fill any gaps
Takes priority over merchandising rules and sort orders

Example:

{
  "dynamicLinking": {
    "products": ["summer-dress-blue", 8234567890123, "classic-tee-white"]
  }
}

defaultSelectedOptions

array

Specify which product variants should be selected by default in the first_or_matched_variant field. This is useful for scenarios like defaulting to a specific birthstone option in a jewelry collection.

Show Properties

optionCode

string

required

The product option code to match (e.g., "birthstone", "color"). Option codes are automatically normalized (e.g., "Birth Stone" becomes "birth_stone").

value

string

required

The option value to match (e.g., "February", "Blue").

Behavior:

Uses OR logic - selects the first variant matching ANY of the specified option values
Falls back to the first variant by position if no match is found
Automatically skipped when any option or variant filters are applied (filters take precedence)
Only affects the first_or_matched_variant field in the response

Example:

{
  "defaultSelectedOptions": [
    {
      "optionCode": "birthstone",
      "value": "February"
    }
  ]
}

Multiple options example (OR logic):

{
  "defaultSelectedOptions": [
    {
      "optionCode": "birthstone",
      "value": "February"
    },
    {
      "optionCode": "birthstone",
      "value": "March"
    }
  ]
}

This will select variants with either February OR March birthstone, preferring the first match found.

attributes

string[]

Product attributes to include in the response. By default, all attributes are included. Available attributes include: id, title, handle, body_html, vendor, product_type, tags, images, available, created_at, updated_at, published_at, price_range, options, original_options, metafields, named_tags, calculated, category, featured_media, is_gift_card, has_variants_that_require_components, combined_listing_parent_product_id, combined_listing_role, first_or_matched_variant, and variants. See the Product Schema for detailed descriptions.

filter_group

object

Refer to our dedicated Filter Expressions guide to learn more about filter expressions.

pagination

Pagination Object

Show pagination

page

int

The current page of results to fetch.

limit

int

The max results to fetch per page

facets

string[]

Facets to be included. Accepts both exact facet codes (e.g., "vendor", "options.Size") and wildcard patterns (e.g., "options.*", "metafields.product.*").Wildcard patterns expand to all matching attribute codes. For example, "options.*" expands to all option facets like "options.Size" and "options.Color". Wildcards must match at least one attribute code to be valid.Examples:

// Exact facet codes
"facets": ["vendor", "options.Size", "options.Color"]

// Wildcard pattern
"facets": ["options.*"]

// Mixed exact and wildcard
"facets": ["vendor", "options.*", "metafields.product.*"]

retrieveFacetCount

boolean

If the count of each facet value should be calculated

includeFacetRanges

boolean

If you want a min/max range for numeric facets such as price.

discountEntitlements

array

Apply discounts to products, variants, or collections. When provided, price-based sorting and filtering will use discounted prices. See the Discount Entitlements guide for detailed usage.

Show Discount Entitlement Object

entitled

object

required

Defines which products qualify for the discount.

Show entitled

all

boolean

When true, applies discount to all products. When false, uses products, variants, or collections arrays.

products

string[]

Array of product IDs or handles that qualify for the discount.

variants

string[] | number[]

Array of variant IDs that qualify for the discount.

collections

string[]

Array of collection handles that qualify for the discount.

discount

object

required

Defines the discount to apply.

Show discount

type

string

required

The discount type: PERCENTAGE or FIXED_AMOUNT.

value

number

required

The discount value. For PERCENTAGE, this is the percentage (e.g., 10 for 10% off). For FIXED_AMOUNT, this is the currency amount.

identity

object

User identity information for tracking and personalization. Automatically managed by the Storefront Pixel; required for headless integrations.

Show Properties

deviceId

string

Persistent browser identifier that remains constant across sessions. Used to recognize returning visitors for long-term personalization. Automatically generated and managed by the Storefront Pixel.

sessionId

string

Temporary session identifier. Typically corresponds to the Shopify session ID and expires after inactivity or when the browser is closed.

customerId

string

Shopify customer ID for authenticated users. Only present when the user is signed in to their account.

Response

results

Array of Objects

Show Properties

number

The unique identifier of the product.

title

string

The title of the product.

body_html

string

The HTML content describing the product.

vendor

string

The vendor of the product.

product_type

string

The type of the product.

created_at

number

The timestamp when the product was created.

handle

string

The handle of the product.

updated_at

number

The timestamp when the product was updated.

published_at

number

The timestamp when the product was published.

Variant Breakouts

When variant breakouts are configured for a collection, results may include both product tiles and variant tiles. Each result includes a __typename field to identify the tile type:

__typename

string

Identifies the type of tile in the results:

"Product" - A standard product tile
"Variant" - An individual variant tile from a product with a configured breakout option

Variant Tile Fields

Variant tiles include additional fields to identify the specific variant:

product_id

number

The parent product ID. Use this to link back to the full product or group variants from the same product.

variant_id

number

The specific variant ID. For variant tiles, this matches the id field.

For variant tiles, the id field contains the variant ID (not the product ID). The title field is formatted as "{product title} - {option value}" by default (e.g., “Amethyst Ring - Rose Quartz”), but this can be configured per breakout. If the breakout’s “Include Option Value in Title” setting is disabled, the title will be the original product title. See the Variant Breakouts documentation for more details.

{
    "results": [
        {
            "id": 7003338965178,
            "title": "SUPREME SEALLINE SEE POUCH SMALL",
            "body_html": "The Supreme Sealline See Pouch Small is a versatile and waterproof storage solution that seamlessly marries utility and style. With its clear window for easy visibility and the iconic Supreme branding, it's a sought-after accessory for those who appreciate keeping their essentials dry while making a fashion statement, whether at the beach or in the city..",
            "vendor": "SUPREME",
            "product_type": "Accessories",
            "created_at": 1644047925,
            "handle": "supreme-pouch-44370ss18a32-sm",
            "updated_at": 1698280024,
            "published_at": 1644047925,
            "tags": [
                "consignment",
            ],
            "images": [
                {
                    "alt": "SUPREME POUCH",
                    "src": "https://cdn.shopify.com/s/files/1/0588/3677/9194/products/ss18_supreme_tnf_pouch_blk_2-l_5fb1316e-22f7-4702-9953-57f3fbdda5be.jpg?v=1644047927",
                    "width": 800,
                    "height": 534,
                    "variant_ids": []
                }
            ],
            "metafields": {
                "product": {
                    "alias": "SEALLINE SEE POUCH SMALL",
                    "colorway": "BLACK",
                    "styleCode": "SS18A30 BLACK",
                    "yearOfRelease": 2018,
                    "searchColor": [
                        "black"
                    ]
                }
            },
            "available": true,
            "price_range": {
                "from": 30,
                "to": 30
            }
        }
    ],
    "totalResults": 1000,
    "page": 1,
    "totalPages": 20,
    "facets": {
        "vendor": {
            "ADIDAS": 30,
            "JORDAN": 336,
            "NEW BALANCE": 15,
            "NIKE": 384,
            "REEBOK": 4,
            "SUPREME": 624,
            "VANS": 32
        }
    },
    "attributionToken": "2y10smI2dB7XZXXFJsLUELltgueq8NRdcRD3U8djkLqxQmaVMvg1lSCf2"
}

Browse

Search

Visual Discovery

Blocks

Analytics

Utilities

Browse API: Browse Collection Page

Authorization

Headers

Path Parameters

Body

Response

Variant Breakouts

Variant Tile Fields

Browse

Search

Visual Discovery

Blocks

Analytics

Utilities

​Authorization

​Headers

​Path Parameters

​Body

​Response

​Variant Breakouts

​Variant Tile Fields

Authorization

Headers

Path Parameters

Body

Response

Variant Breakouts

Variant Tile Fields