Skip to main content
POST
/
blocks
/
{blockId}
/
products
Blocks API: Get Block Products
curl --request POST \
  --url https://app.uselayers.com/api/storefront/v1/blocks/{blockId}/products \
  --header 'Accept: <accept>' \
  --header 'Content-Type: <content-type>' \
  --header 'X-Storefront-Access-Token: <x-storefront-access-token>' \
  --data '
{
  "anchor_id": "<string>",
  "anchor_handle": "<string>",
  "attributes": [
    "<string>"
  ],
  "filter_group": {},
  "pagination": {
    "page": 123,
    "limit": 123
  },
  "facets": [
    "<string>"
  ],
  "retrieveFacetCount": true,
  "includeFacetRanges": true,
  "context": {
    "geo": {
      "country": "<string>",
      "province": "<string>",
      "city": "<string>"
    },
    "productsInCart": [
      {
        "title": "<string>",
        "price": 123,
        "type": "<string>",
        "productId": "<string>",
        "variantId": "<string>",
        "options": {}
      }
    ],
    "productsPurchased": [
      {
        "title": "<string>",
        "price": 123,
        "type": "<string>",
        "productId": "<string>",
        "variantId": "<string>",
        "options": {}
      }
    ],
    "priorSearches": [
      {
        "searchQuery": "<string>",
        "hadClick": true,
        "hadResults": true
      }
    ],
    "marketing": {
      "source": "<string>",
      "medium": "<string>",
      "campaign": "<string>",
      "term": "<string>"
    },
    "customer": {
      "signedIn": true,
      "returning": true,
      "numberOfOrders": 123,
      "averageOrderValue": 123,
      "daysBetweenOrders": 123,
      "daysSinceLastOrder": 123,
      "daysSinceOldestOrder": 123,
      "totalSpent": 123
    },
    "shoppingChannel": "<string>",
    "custom": {}
  }
}
'
POST /storefront/v1/blocks/01HQXYZ123ABC456DEF789/products

{
  "anchor_id": "8234567890123",
  "pagination": {
    "page": 1,
    "limit": 12
  },
  "context": {
    "geo": {
      "country": "US",
      "province": "California"
    },
    "productsInCart": [
      {
        "title": "Nike Air Force 1",
        "productId": "8234567890123",
        "variantId": "45678901234567"
      }
    ],
    "shoppingChannel": "web"
  },
  "identity": {
    "sessionId": "abc123",
    "deviceId": "device-uuid"
  }
}

​
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
​
Accept
string
default:"application/json"
required

​
Path Parameters

​
blockId
string
required
The unique identifier (ULID) of the block you wish to retrieve products for.

​
Body

​
anchor_id
string
The anchor identifier for the block. Required for product and collection anchor types.
  • Product anchors: Product ID (e.g., "8234567890123")
  • Collection anchors: Collection ID (e.g., "456789012345") or collection handle (e.g., "summer-collection"). The system automatically resolves both numeric IDs and string handles.
  • Cart anchors: Not required (uses context.productsInCart instead)
  • None anchors: Not required (global blocks)
​
anchor_handle
string
Deprecated: Use anchor_id instead. For collection anchors, anchor_id now accepts both collection IDs and handles.
​
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
​
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.
​
context
object
Contextual information about the customer’s session, behavior, and environment. Automatically collected by the Storefront Pixel; must be manually provided for headless integrations. See Contextual Information for implementation guidance.

​
Response

​
results
Array of Objects
​
totalResults
number
The total number of results. When a maximum products safeguard is configured, this value is capped to the maximum. When variant breakouts are enabled, this reflects the count of tiles (both product and variant tiles) rather than just products.
​
page
number
The current page number.
​
totalPages
number
The total number of pages. Calculated from totalResults and the requested page size. When a maximum products safeguard is configured, this reflects the capped total. When variant breakouts are enabled, the calculation is based on tile count.
​
resultsPerPage
number
The number of results per page (matches the limit parameter from the request).
​
facets
object
If retrieveFacetCount is true then an object with keys and values of the specified attributes. When variant breakouts are enabled, facet counts reflect tile counts rather than product counts. Empty values and literal "null" strings are automatically excluded from facet results.
​
facetRanges
object
If includeFacetRanges is true then an object with keys of the facet attribute code and value is an object with min/max.
​
attributionToken
string
The attribution token.
​
block
object
Information about the block that generated these recommendations.
​
_training
boolean
Present and set to true when the block’s interaction strategy data is still being computed. In this state, the primary block returns empty results and the fallback chain is used instead. Once the strategy data is ready, this field is no longer included in the response.
​
_meta
object

​
How Blocks Work

Blocks are configurable product recommendation widgets that can be placed throughout your storefront. Each block has:
  1. Anchor Type: Determines where the block appears (product pages, collection pages, cart, or globally)
  2. Strategy: Defines how products are selected (interaction-based, similar products, or manual collection)
  3. Rules: Optional conditional logic that modifies block behavior based on context
  4. Safeguards: Constraints like minimum/maximum products and out-of-stock handling
  5. Fallback Chain: Alternative blocks to use if the primary block doesn’t return enough products

​
Anchor Types

Display recommendations on product pages. Requires anchor_id (product ID) or context.productsInCart with product information.Common strategies:
  • Frequently bought together
  • Customers also viewed
  • Similar products
Display recommendations on collection pages. Requires anchor_id which can be either a collection ID or collection handle. The collection is resolved dynamically from the API request.Common strategies:
  • Browsed then bought (collection interaction)
  • Browsed then viewed (collection interaction)
  • Trending in collection (collection interaction)
  • Similar products
  • Manual collection with custom sort order
Display recommendations in the cart. Uses context.productsInCart to find related products.Common strategies:
  • Frequently bought together
  • Complete the look
Global blocks that can appear anywhere (homepage, static pages). No anchor required.Common strategies:
  • Manual collection (e.g., “Best Sellers”, “New Arrivals”)

​
Strategy Types

Use behavioral data to find products that customers frequently interact with together.Available strategies:
  • frequently_bought_together: Products purchased together in the same order
  • customers_also_viewed: Products viewed together in the same session
  • customers_also_added_to_cart: Products added to cart together in the same session
Requirements:
  • Requires sufficient historical interaction data
  • Data is computed periodically based on configured time windows (7d, 30d, 90d, etc.)
Data readiness: If the strategy data has not been computed yet (for example, on a newly configured strategy), the block returns empty results with a _training flag set to true. In this state, the fallback chain is used automatically. Once the data is ready, the block returns recommendations normally.
Use behavioral data to find products related to a collection based on customer behavior. These strategies analyze how shoppers who browse a collection interact with products.Available strategies:
  • browsed_then_bought: Products frequently purchased by shoppers who browsed the collection
  • browsed_then_viewed: Products frequently viewed by shoppers who browsed the collection
  • collection_trending: Products currently trending within the collection based on recent activity
Requirements:
  • Requires sufficient historical browsing and interaction data
  • Data is computed periodically based on configured time windows (7d, 30d, 90d)
  • Only available for collection anchor blocks
Use vector similarity to find visually and semantically similar products.Available strategies:
  • similar_products: Products with similar embeddings based on images and text
Supported anchors: Product, Collection. For collection anchors, the system automatically selects a representative product from the collection to find similar products.Requirements:
  • Requires product embeddings to be generated
  • Works best with rich product images and descriptions
Curate products using a collection or hand-picked product IDs, with optional custom sorting.Configuration:
  • Hand-picked products: Select specific products by ID in the dashboard. The order you define is preserved in the response.
  • Collection anchor blocks: Collection is determined dynamically from the anchor_id parameter in the API request
  • None anchor blocks: Collection is selected in the dashboard configuration
  • Optionally apply a sort order
  • Apply additional filters via rules
When hand-picked product IDs are configured, they take priority over collection-based selection.Use cases:
  • “Best Sellers” block
  • “New Arrivals” block
  • Curated seasonal collections
  • Hand-picked “Staff Picks” or “Editor’s Choice” blocks

​
Block Rules

Blocks support conditional rules that modify behavior based on context. Rules are evaluated in order, and the first matching rule’s actions are applied.

​
Rule Actions

Add additional filtering to the block’s product results.Example: Only show products from a specific vendor when the anchor product is from that vendor.
Hide the block entirely when conditions are met. The fallback chain will be used instead.Example: Hide “Frequently Bought Together” block if the anchor product is out of stock.
Switch to a different strategy when conditions are met.Example: Use “Similar Products” strategy for mobile users instead of “Frequently Bought Together”.
Modify the block’s safeguards (min/max products, hide out of stock) based on conditions.Example: Show more products (increase maximum) for VIP customers.

​
Safeguards

Safeguards ensure blocks display appropriately:
  • Minimum Products: If fewer products are available, the fallback chain is used
  • Maximum Products: Caps the total number of products returned across all pages, with consistent pagination metadata
  • Hide Out of Stock: Automatically filters out unavailable products

​
Fallback Chain

If a block doesn’t return enough products (based on minimum safeguard), the system automatically tries fallback blocks in order. This ensures customers always see recommendations. Each fallback entry supports one of two modes:
  • Replace (default): If the fallback block meets the minimum products requirement, its results replace the primary block’s results entirely.
  • Fill: The fallback block’s products are appended to the primary block’s results (deduplicated by product ID). This allows you to “top up” a partially filled block rather than replacing it completely. The response’s totalResults accounts for deduplication across all sources.
Example fallback chain:
  1. Primary: “Frequently Bought Together” (interaction-based)
  2. Fallback 1 (fill mode): “Similar Products” — appends additional products if the primary doesn’t return enough
  3. Fallback 2 (replace mode): “Best Sellers” (manual collection) — used entirely if the combined results are still below minimum

​
Error Handling

​
error
string
Error message when the request fails.
Common errors:
The specified block ID doesn’t exist or is not active.
{
  "error": "Block not found"
}
The block exists but couldn’t generate recommendations (e.g., missing anchor_id for product anchor).
{
  "error": "Unable to get products for block"
}
Invalid or missing authentication token.
POST /storefront/v1/blocks/01HQXYZ123ABC456DEF789/products

{
  "anchor_id": "8234567890123",
  "pagination": {
    "page": 1,
    "limit": 12
  },
  "context": {
    "geo": {
      "country": "US",
      "province": "California"
    },
    "productsInCart": [
      {
        "title": "Nike Air Force 1",
        "productId": "8234567890123",
        "variantId": "45678901234567"
      }
    ],
    "shoppingChannel": "web"
  },
  "identity": {
    "sessionId": "abc123",
    "deviceId": "device-uuid"
  }
}

​
See Also