---
title: Storefront Catalog Extension
description: >-
  The dev.shopify.catalog.storefront extension adds Shopify-specific fields to
  UCP catalog tools, including gift card classification, collections, checkout
  prerequisites, selling plans, and availability filtering.
source_url:
  html: 'https://shopify.dev/docs/agents/catalog/storefront-catalog-extension'
  md: 'https://shopify.dev/docs/agents/catalog/storefront-catalog-extension.md'
---

# Storefront Catalog Extension

The `dev.shopify.catalog.storefront` extension adds Shopify-specific fields to the base [UCP catalog tools](https://shopify.dev/docs/agents/catalog/storefront-catalog). When this extension is active (negotiated via your [agent profile](https://shopify.dev/docs/agents/profiles)), responses include additional fields on products and variants.

* **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**.

***

## Product 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. |

### Collections

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). |

***

## Variant 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. |
| `selling_plans` | Array\[SellingPlan] | Available purchase options (subscriptions). Only on `get_product` responses — use `requires.selling_plan` in search to detect availability. |

### Selling 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`. |

***

## Filters

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. |

```json
{
  "catalog": {
    "query": "shirts",
    "filters": {
      "available": false
    }
  }
}
```

***

## Example response

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

```json
{
  "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},
          "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},
          "inputs": [{"id": "gid://shopify/Product/102", "match": "featured"}]
        }
      ]
    }
  ]
}
```

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

***