Storefront Catalog extension

The Storefront Catalog extension adds Shopify-specific fields to the base UCP catalog tools. When this extension is active, responses include additional fields on products and variants, and requests accept an additional filter.

Extension name: dev.shopify.catalog.storefront
Version: 2026-04-08
Extends: dev.ucp.shopping.catalog.search, dev.ucp.shopping.catalog.lookup

This extension is scoped to a single merchant's storefront. For the cross-merchant extension, see Global Catalog extension.

Anchor to Product fieldsProduct fields

When this extension is active, products in search_catalog, lookup_catalog, and get_product responses include:

Field	Type	Description
`gift_card`	boolean	Whether this product is a gift card — a digital product, not a physical item.
`collections`	Array[Collection]	Merchant-curated collections this product belongs to.

Anchor to CollectionsCollections

Each collection object contains:

Field	Type	Description
`id`	string	Collection GID (e.g., `gid://shopify/Collection/123`).
`handle`	string	URL-safe slug for the collection.
`title`	string	Collection display name.
`description`	Description	Collection description in HTML format.
`url`	string	Canonical collection page URL (if available).
`media`	Array[Media]	Collection image (if available).

Anchor to Variant fieldsVariant fields

Variants include checkout prerequisites and purchase options:

Field	Type	Description
`requires.shipping`	boolean	Whether a shipping address is needed. When `false`, checkout can skip address collection.
`requires.selling_plan`	boolean	Whether a selling plan must be selected. When `true`, include a `selling_plan_id` on the checkout line item.
`checkout_url`	string	Direct checkout URL for this variant.
`selling_plans`	Array[SellingPlan]	Available purchase options (subscriptions). Only on `get_product` responses — use `requires.selling_plan` in search to detect availability.

Anchor to Selling plansSelling plans

Each selling plan includes:

Field	Type	Description
`id`	string	Selling plan GID.
`name`	string	Plan display name (e.g., "Subscribe & save 15%").
`group`	string	Selling plan group name.
`recurring`	boolean	Whether this plan involves recurring deliveries.
`description`	string	Optional plan description.
`options`	Array	Plan options with `name` and `value`.
`price`	object	Price adjustment with `type`, `value`, and `currency`.

Anchor to FiltersFilters

When this extension is active, search_catalog and lookup_catalog accept an additional filter:

Field	Type	Default	Description
`available`	boolean	`true`	When `true` (default), only sale-ready items are returned. Set to `false` to include unavailable items.

{

"catalog": {

"query": "shirts",

"filters": {

"available": false

}

Anchor to Example responseExample response

A lookup response with the storefront extension active, showing a physical product and a gift card:

{

"ucp": {

"version": "2026-04-08",

"capabilities": {

"dev.ucp.shopping.catalog.lookup": [{"version": "2026-04-08"}],

"dev.shopify.catalog.storefront": [{"version": "2026-04-08"}]

}

"products": [

{

"id": "gid://shopify/Product/101",

"title": "Classic Blue Oxford Shirt",

"description": {"html": "<p>Tailored cotton oxford shirt.</p>"},

"price_range": {

"min": {"amount": 7500, "currency": "USD"},

"max": {"amount": 7500, "currency": "USD"}

"collections": [

{

"id": "gid://shopify/Collection/shirts",

"handle": "shirts",

"title": "Shirts",

"description": {"html": "<p>Dress and casual shirts.</p>"}

}

"variants": [

{

"id": "gid://shopify/ProductVariant/201",

"title": "Size M",

"price": {"amount": 7500, "currency": "USD"},

"availability": {"available": true},

"requires": {"shipping": true},

"checkout_url": "https://example.myshopify.com/cart/201:1",

"inputs": [{"id": "gid://shopify/Product/101", "match": "featured"}]

}

]

{

"id": "gid://shopify/Product/102",

"title": "$50 Gift Card",

"gift_card": true,

"price_range": {

"min": {"amount": 5000, "currency": "USD"},

"max": {"amount": 5000, "currency": "USD"}

"variants": [

{

"id": "gid://shopify/ProductVariant/202",

"title": "$50 Gift Card",

"price": {"amount": 5000, "currency": "USD"},

"availability": {"available": true},

"requires": {"shipping": false},

"checkout_url": "https://example.myshopify.com/cart/202:1",

"inputs": [{"id": "gid://shopify/Product/102", "match": "featured"}]

}

]

}

]

}

Physical product has requires.shipping: true; gift card has gift_card: true and requires.shipping: false.

Was this page helpful?