---
title: 'Catalog API: Search'
description: Search for products across the Shopify Catalog using the Search endpoint.
api_name: catalog
source_url:
  html: 'https://shopify.dev/docs/api/catalog-api/search'
  md: 'https://shopify.dev/docs/api/catalog-api/search.md'
---

# Search

Retrieve products from the Shopify Catalog using the `/global/v2/search` endpoint.

The resource returns an array of Universal Products, each representing a high-level product grouping that might contain multiple variants or offers from different shops.

***

## GETRetrieve products from Catalog

Pass a search query to retrieve products from the Shopify Catalog.

This example illustrates how to retrieve information from many products using the Search resource and the `/global/v2/search` endpoint. Replace `{query}` with the buyer's search terms and `{BEARER_TOKEN}` with the bearer token you generated in the Authentication section.

#### Parameters

***

`query`•`String``Required`

Keywords for search. For example, `Running Shoes`

***

`available_for_sale`•`Int (0,1)``Default: 1 (only available items)`

Filter by availability.\
\
When `1`, only products available for sale are included. When `0`, unavailable items are only included if they are a good match for the query.

***

`categories`•`String`

Comma-delimited list of global IDs for taxonomy categories. Refer to the [Shopify Standard Product Taxonomy](https://shopify.github.io/product-taxonomy/releases/latest/) and [raw category list](https://github.com/Shopify/product-taxonomy/tree/main/dist/en).\
\
For example, for shoes, use: `gid://shopify/TaxonomyCategory/aa-8`.

***

`include_secondhand`•`Int (0,1)``Default: 1 (include)`

Include secondhand products.\
\
When `1`, include secondhand products in the results.

***

`limit`•`Integer (1-10)``Default: 10`

Max results to return.

***

`max_price`•`Decimal`

Maximum price (currency determined by `ships_to`). API accepts decimals.

***

`min_price`•`Decimal`

Minimum price (currency determined by `ships_to`). API accepts decimals.

***

`products_limit`•`Integer (1-10)``Default: 10`

The maximum number of variants to return per Universal Product.

***

`ships_from`•`String`

An [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) country code. For example, `US`

***

`ships_to`•`String``Default: US`

An [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) country code.

***

`shop_ids`•`String`

Filter by specific shops. For example, `gid://shopify/Shop/1234` or `1234`

***

GET

## /global/v2/search

```bash
curl -X GET \
  'https://discover.shopifyapps.com/global/v2/search?query={query}' \
  -H 'Authorization: Bearer {BEARER_TOKEN}'
```

## {} Response

```json
[
  {
    "id": "gid://shopify/p/abc123XYZ789defGHI456jk",
    "title": "Classic Crewneck Sweatshirt",
    "description": "A comfortable everyday sweatshirt with a classic fit.",
    "lookupUrl": "https://discover.shopifyapps.com/global/v2/p/abc123XYZ789defGHI456jk",
    "media": [
      { "url": "https://cdn.shopify.com/.../classic-crewneck.webp", "altText": "Classic Crewneck" }
    ],
    "options": [
      { "name": "Color", "values": [{ "value": "Heather Gray" }] },
      { "name": "Size", "values": [{ "value": "Medium" }] }
    ],
    "priceRange": {
      "min": { "amount": 4500, "currency": "USD" },
      "max": { "amount": 5500, "currency": "USD" }
    },
    "variants": [
      {
        "id": "gid://shopify/ProductVariant/2000000000001?shop=10000000001",
        "productId": "gid://shopify/Product/1000000000001",
        "displayName": "Classic Crewneck - Heather Gray / Medium",
        "availableForSale": true,
        "price": { "amount": 4500, "currency": "USD" },
        "media": [{ "url": "https://cdn.shopify.com/.../crewneck.webp", "altText": "Crewneck" }],
        "options": [
          { "name": "Color", "value": "Heather Gray" },
          { "name": "Size", "value": "Medium" }
        ],
        "shop": {
          "id": "gid://shopify/Shop/10000000001",
          "name": "Mock Shop",
          "onlineStoreUrl": "https://mock.shop",
          "permanentDomain": "mock-shop.myshopify.com"
        },
        "variantUrl": "https://mock.shop/products/crewneck?variant=2000000000001",
        "checkoutUrl": "https://mock.shop/cart/2000000000001:1?payment=shop_pay",
        "eligibleForNativeCheckout": false,
        "rating": { "rating": 4.7, "count": 89 },
        "secondhand": false,
        "lookupUrl": "https://discover.shopifyapps.com/global/v2/p/abc123XYZ789defGHI456jk"
      }
    ],
    "rating": { "rating": 4.5, "count": 128 },
    "uniqueSellingPoint": "Features a soft cotton-polyester blend with ribbed details.",
    "topFeatures": ["50/50 cotton polyester blend", "Classic crewneck design"],
    "techSpecs": ["Weight: 8.0 oz", "Material: 50% cotton, 50% polyester"],
    "attributes": [
      { "name": "Fabric", "values": ["Cotton", "Polyester"] },
      { "name": "Neckline", "values": ["Crew"] }
    ],
    "url": "https://discover.shopifyapps.com/global/v2/p/abc123?query=sweatshirts&ships_to=US"
  }
]
```

***

## Search response schema

The Search endpoint returns an array of `UniversalProduct` objects. Each object contains product information optimized for discovery and browsing.

### Inferred fields

Some fields are generated using machine learning and are marked with `Inferred` in the documentation. These fields may not always be present or may have varying accuracy depending on the available product data.

**Response type:**

[`UniversalProduct`\[\]](#the-universalproduct-resource)

### The Universal​Product resource

Represents a high-level product grouping that may contain multiple variants or offers from different shops.

#### Properties

***

`attributes`•`Hash[]``Inferred`

Array of product attributes as name-value pairs.

***

`description`•`string``Inferred`

Detailed product description.

***

`id`•`string`

Unique identifier for the universal product.\
\
For example, `gid://shopify/p/1UT1zYWaL8WeTNCllgUbsM`

***

`lookupUrl`•`string`

URL for subsequent calls to the Lookup endpoint.

***

`media`•`Media[]`

Product media from the top-ranked variant. Currently returns images only.

***

`options`•`ProductOption[]``Inferred`

Array of product options/variants.

***

`priceRange`•`PriceRange`

Price range from the top-ranked variant.

***

`rating`•`Rating`

Universal product rating information.

***

`techSpecs`•`string[]``Inferred`

Array of technical specifications.

***

`title`•`string`

Product title from the top-ranked variant.

***

`topFeatures`•`string[]``Inferred`

Array of top product features.

***

`uniqueSellingPoint`•`string``Inferred`

The unique selling point for the product.

***

`url`•`string`

URL for the product with search context parameters preserved.

***

`variants`•`Variant[]`

Array of product variants.

***

## {} UniversalProduct

```json
{
  "id": "gid://shopify/p/abc123XYZ789defGHI456jk",
  "title": "Classic Crewneck Sweatshirt",
  "description": "A comfortable everyday sweatshirt.",
  "lookupUrl": "https://discover.shopifyapps.com/global/v2/p/abc123",
  "media": [
    { "url": "https://cdn.shopify.com/.../crewneck.webp", "altText": "Crewneck" }
  ],
  "options": [
    { "name": "Color", "values": [{ "value": "Heather Gray" }] },
    { "name": "Size", "values": [{ "value": "Medium" }] }
  ],
  "priceRange": {
    "min": { "amount": 4500, "currency": "USD" },
    "max": { "amount": 5500, "currency": "USD" }
  },
  "variants": [
    {
      "id": "gid://shopify/ProductVariant/2000000000001",
      "displayName": "Classic Crewneck - Heather Gray",
      "availableForSale": true,
      "price": { "amount": 4500, "currency": "USD" },
      "shop": { "id": "gid://shopify/Shop/10000000001", "name": "Mock Shop" }
    }
  ],
  "rating": { "rating": 4.5, "count": 120 },
  "url": "https://discover.shopifyapps.com/global/v2/p/abc123?query=sweatshirts"
}
```

### The Variant resource

Represents a specific product variant with pricing, availability, and checkout information.

#### Properties

***

`availableForSale`•`boolean`

Whether the variant is available for purchase.

***

`checkoutUrl`•`string`

Direct checkout URL for this variant.

***

`displayName`•`string`

Display name for the variant.

***

`eligibleForNativeCheckout`•`boolean`

Whether the variant supports native checkout. This field is not returned by default and requires opt-in from Shopify.

***

`id`•`string`

Unique variant identifier.

***

`lookupUrl`•`string`

URL for looking up this variant.

***

`media`•`Media[]`

Media for this variant. Currently returns images only.

***

`options`•`VariantOption[]`

Array of options for this variant.

***

`price`•`Price`

Price information for this variant.

***

`productId`•`string`

ID of the parent product.

***

`rating`•`Rating`

Rating information for this variant.

***

`secondhand`•`boolean``Inferred`

Whether the variant is secondhand.

***

`shop`•`Shop`

Shop offering this variant.

***

`variantUrl`•`string`

URL for the variant's product page.

***

## {} Variant

```json
{
  "id": "gid://shopify/ProductVariant/2000000000001?shop=10000000001",
  "productId": "gid://shopify/Product/1000000000001",
  "displayName": "Classic Crewneck - Heather Gray / Medium",
  "availableForSale": true,
  "price": { "amount": 4500, "currency": "USD" },
  "media": [
    { "url": "https://cdn.shopify.com/.../variant.webp", "altText": "Heather Gray variant" }
  ],
  "options": [
    { "name": "Color", "value": "Heather Gray" },
    { "name": "Size", "value": "Medium" }
  ],
  "shop": {
    "id": "gid://shopify/Shop/10000000001",
    "name": "Mock Shop",
    "onlineStoreUrl": "https://mock.shop",
    "permanentDomain": "mock-shop.myshopify.com"
  },
  "variantUrl": "https://mock.shop/products/crewneck?variant=2000000000001",
  "checkoutUrl": "https://mock.shop/cart/2000000000001:1",
  "eligibleForNativeCheckout": false,
  "rating": { "rating": 4.8, "count": 24 },
  "secondhand": false,
  "lookupUrl": "https://discover.shopifyapps.com/global/v2/p/abc123"
}
```

### The Shop resource

Represents the shop offering the product. In Search responses, Shop contains only basic information.

#### Properties

***

`id`•`string`

Unique shop identifier.\
\
For example, `gid://shopify/Shop/54623456`

***

`name`•`string`

Shop name.

***

`onlineStoreUrl`•`string`

Shop page URL.

***

`permanentDomain`•`string`

Shop's permanent domain. For example, `mock-shop.myshopify.com`. This field is `null` if the client is not opted in to receive `eligibleForNativeCheckout`.

***

## {} Shop

```json
{
  "id": "gid://shopify/Shop/10000000001",
  "name": "Mock Shop",
  "onlineStoreUrl": "https://mock.shop",
  "permanentDomain": "mock-shop.myshopify.com"
}
```

### The Product​Option resource

Represents a product option like Size or Color.

#### Properties

***

`name`•`string`

Option name. For example, `Color` or `Size`

***

`values`•`OptionValue[]`

Array of possible values for this option.

***

## {} ProductOption

```json
{
  "name": "Color",
  "values": [
    { "value": "Heather Gray" },
    { "value": "Navy" }
  ]
}
```

### The Option​Value resource

Represents a product option value. In Search responses, OptionValue contains only the value.

#### Properties

***

`value`•`string`

Option value, configured by the merchant. For example, `US5.5`

***

## {} OptionValue

```json
{
  "value": "Heather Gray"
}
```

### The Price​Range resource

Represents the minimum and maximum prices for a product or collection of variants.

#### Properties

***

`max`•`Price`

Maximum price in the range.

***

`min`•`Price`

Minimum price in the range.

***

## {} PriceRange

```json
{
  "min": { "amount": 2999, "currency": "USD" },
  "max": { "amount": 4999, "currency": "USD" }
}
```

### The Variant​Option resource

Represents a selected option for a specific variant.

#### Properties

***

`name`•`string`

The name of the option (e.g., `Color`, `Size`).

***

`value`•`string`

The selected value for this option (e.g., `Blue`, `Medium`).

***

## {} VariantOption

```json
{
  "name": "Color",
  "value": "Heather Gray"
}
```

### The Media resource

Represents product media. Currently returns images only.

#### Properties

***

`altText`•`string`

Alt text for the media.

***

`url`•`string`

URL of the media asset.

***

## {} Media

```json
{
  "url": "https://cdn.shopify.com/.../sneaker.jpg",
  "altText": "White running sneaker side view"
}
```

### The Price resource

Represents a monetary value with currency.

#### Properties

***

`amount`•`integer`

The price amount in the smallest currency unit (e.g., cents for USD).

***

`currency`•`string`

The three-letter ISO 4217 currency code (e.g., `USD`, `EUR`).

***

## {} Price

```json
{
  "amount": 12999,
  "currency": "USD"
}
```

### The Rating resource

Represents product or variant rating information.

#### Properties

***

`count`•`integer`

The total number of ratings.

***

`rating`•`number`

The average rating value.

***

## {} Rating

```json
{
  "rating": 4.5,
  "count": 128
}
```

***