Skip to main content
POST
https://app.uselayers.com/api/storefront/v1
/
storefront
/
v1
/
blocks
/
{blockId}
/
products
Blocks API: Get Block Products
curl --request POST \
  --url https://app.uselayers.com/api/storefront/v1/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,
  "discountEntitlements": [
    {
      "entitled": {
        "all": true,
        "products": [
          "<string>"
        ],
        "variants": [
          {}
        ],
        "collections": [
          "<string>"
        ]
      },
      "discount": {
        "type": "<string>",
        "value": 123
      }
    }
  ],
  "identity": {
    "deviceId": "<string>",
    "sessionId": "<string>",
    "customerId": "<string>"
  }
}
'
POST /storefront/v1/blocks/01HQXYZ123ABC456DEF789/products

{
  "anchor_id": "8234567890123",
  "pagination": {
    "page": 1,
    "limit": 12
  },
  "context": {
    "productsInCart": [
      {
        "productId": "8234567890123",
        "variantId": "45678901234567",
        "quantity": 1
      }
    ]
  }
}

​
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.
​
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.
​
identity
object
User identity information for tracking and personalization. Automatically managed by the Storefront Pixel; required for headless integrations.

​
Response

​
results
Array of Objects
​
totalResults
number
The total number of results. 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 based on tile count when variant breakouts are enabled.
​
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.
​
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.
​
_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:
  • 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.)
Use vector similarity to find visually and semantically similar products.Available strategies:
  • similar_products: Products with similar embeddings based on images and text
Requirements:
  • Requires product embeddings to be generated
  • Works best with rich product images and descriptions
Curate a specific collection with optional custom sorting.Configuration:
  • 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
Use cases:
  • “Best Sellers” block
  • “New Arrivals” block
  • Curated seasonal collections

​
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: Limits the number of products returned
  • 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. Example fallback chain:
  1. Primary: “Frequently Bought Together” (interaction-based)
  2. Fallback 1: “Similar Products” (similarity-based)
  3. Fallback 2: “Best Sellers” (manual collection)

​
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": {
    "productsInCart": [
      {
        "productId": "8234567890123",
        "variantId": "45678901234567",
        "quantity": 1
      }
    ]
  }
}

​
See Also