---
title: Global Catalog extension
description: >-
  The dev.shopify.catalog.global extension adds cross-shop discovery fields to
  UCP catalog tools, including shipping filters, similarity search, checkout
  URLs, inventory signals, and ML-inferred product metadata.
source_url:
  html: 'https://shopify.dev/docs/agents/catalog/global-catalog-extension'
  md: 'https://shopify.dev/docs/agents/catalog/global-catalog-extension.md'
---

# Global Catalog extension

The Global Catalog extension adds Shopify-specific fields to the base [UCP catalog tools](https://shopify.dev/docs/agents/catalog/global-catalog#available-tools). Every Global Catalog response includes the additional filters, variant fields, and ML-inferred metadata documented on this page.

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

This extension is scoped to the global catalog — products from across all Shopify merchants. For the single-store extension, see [Storefront Catalog extension](https://shopify.dev/docs/agents/catalog/storefront-catalog-extension).

***

## Filters

All three tools (`search_catalog`, `lookup_catalog`, and `get_product`) accept a `catalog.filters` object with the following Shopify-specific fields:

| Field | Type | Default | Description |
| - | - | - | - |
| `available` | boolean | `true` | When `true` (default), only sale-ready items are returned. Set to `false` to include unavailable items. |
| `condition` | array | — | Product condition filter. Known values: `"new"`, `"secondhand"`. Multiple values use OR logic. Absent means no condition filter. |
| `ships_to` | object | — | Filter to products that ship to a given location. When country matches `context.address_country`, the implementation may enrich with context region and postal code. Accepts `country` (required, [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)), `region`, and `postal_code`. |
| `ships_from` | object | — | Filter by merchant origin country. Accepts `country` (required, [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). |

`search_catalog` also accepts these additional filters:

| Filter | Type | Default | Description |
| - | - | - | - |
| `shop_ids` | array | — | Restrict results to specific shops by GID. |
| `categories` | array | — | Filter by product category. Each item is a taxonomy category GID (for example, `"gid://shopify/TaxonomyCategory/123"`). Multiple values use OR logic. |

```json
{
  "catalog": {
    "query": "running shoes",
    "filters": {
      "available": true,
      "condition": ["new"],
      "ships_to": {"country": "US"},
      "ships_from": {"country": "US"}
    }
  }
}
```

***

## Similarity search

Use `catalog.like` in a `search_catalog` request to find products similar to a reference product or image. Pass 1–2 items, each as one of:

* Item Reference: A product or variant GID: `{"id": "gid://shopify/p/..."}`.
* Image Content: A base64-encoded image with its MIME type: `{"image": {"content_type": "image/jpeg", "data": "<base64>"}}`.

You can combine `like` with `query` in a single request to narrow similarity results by keyword:

```json
{
  "catalog": {
    "query": "trail running shoes",
    "like": [
      {"id": "gid://shopify/p/7f3a2b8c1d9e"}
    ],
    "filters": {
      "ships_to": {"country": "US"}
    }
  }
}
```

***

## Product fields

All three tool responses include these additional fields on each product:

| Field | Type | Description |
| - | - | - |
| `metadata.attributes` | Array\[Attribute] | ML-inferred product attributes such as material, style, and occasion. |
| `metadata.tech_specs` | Array\[string] | ML-inferred technical specifications. |
| `metadata.top_features` | Array\[string] | ML-inferred top product features. |
| `metadata.unique_selling_points` | Array\[string] | ML-inferred unique selling propositions. |

### Attributes

Each attribute object contains:

| Field | Type | Description |
| - | - | - |
| `name` | string | Attribute name (for example, `"Material"`, `"Style"`). |
| `value` | string | Attribute value (for example, `"Cotton"`, `"Casual"`). |

***

## Variant fields

Variants include checkout URLs, purchase requirements, inventory signals, and seller identity:

| Field | Type | Description |
| - | - | - |
| `checkout_url` | string | Direct checkout URL for this variant. |
| `requires.shipping` | boolean | Whether a shipping address is needed. When `false`, checkout can skip address collection. |
| `requires.components` | boolean | Whether the variant requires bundle components. When `true`, the variant can only be purchased as a parent bundle. |
| `condition` | Array\[string] | Product condition labels for this variant. Known values: `"new"`, `"secondhand"`. |
| `eligible.native_checkout` | boolean | Whether this variant supports native (non-redirect) checkout. Default `false`. |
| `availability.running_low` | boolean | Whether inventory is limited. Only meaningful when `available` is `true`. |
| `seller.id` | string | The shop GID. |
| `seller.url` | string | The storefront URL. |
| `seller.domain` | string | The primary domain of the shop. |

**Info:**

`seller.name` and `seller.links` are part of the base UCP spec and always present in Global Catalog responses.

***

## Example response

The following example shows a `search_catalog` response with Global Catalog extension fields:

```json
{
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-04-08",
        "capabilities": {
          "dev.ucp.shopping.catalog.search": [{"version": "2026-04-08"}],
          "dev.shopify.catalog.global": [{"version": "2026-04-08"}]
        }
      },
      "products": [
        {
          "id": "gid://shopify/p/7f3a2b8c1d9e",
          "title": "Trail Runner Pro",
          "description": {"html": "<p>Lightweight trail running shoe for road and light trail.</p>"},
          "price_range": {
            "min": {"amount": 8999, "currency": "USD"},
            "max": {"amount": 12999, "currency": "USD"}
          },
          "metadata": {
            "attributes": [
              {"name": "Material", "value": "Mesh"},
              {"name": "Style", "value": "Athletic"}
            ],
            "top_features": ["Lightweight", "Breathable mesh upper", "Cushioned sole"],
            "unique_selling_points": ["Designed for road and light trail", "Responsive foam midsole"]
          },
          "variants": [
            {
              "id": "gid://shopify/ProductVariant/12345678",
              "title": "Black / Size 10",
              "price": {"amount": 8999, "currency": "USD"},
              "checkout_url": "https://example-running.myshopify.com/cart/12345678:1",
              "condition": ["new"],
              "eligible": {"native_checkout": true},
              "availability": {
                "available": true,
                "status": "in_stock",
                "running_low": false
              },
              "requires": {"shipping": true, "selling_plan": false, "components": false},
              "seller": {
                "name": "Example Running",
                "id": "gid://shopify/Shop/987654321",
                "domain": "example-running.myshopify.com",
                "url": "https://example-running.myshopify.com",
                "links": [
                  {"type": "refund_policy", "url": "https://example-running.myshopify.com/policies/refunds"}
                ]
              }
            }
          ]
        }
      ]
    }
  }
}
```

***