---
title: Catalog API reference
description: >-
  Get detailed product information using Universal Product IDs with the Catalog
  Lookup API.
source_url:
  html: 'https://shopify.dev/docs/agents/catalog/catalog-api'
  md: 'https://shopify.dev/docs/agents/catalog/catalog-api.md'
---

# Catalog API reference

Early access

Agentic commerce is rolling out to Dev Dashboard. [Sign up to be notified](https://docs.google.com/forms/d/e/1FAIpQLSe4DsRrfytH6CBrolSJdPKLyl-e-K2MEBDOjm-F-ZJpNy6Vtw/viewform).

The Catalog API provides access to product data across all eligible Shopify merchants, enabling agentic commerce applications to search, discover, and retrieve detailed product information to render product details pages.

## Authentication

All Catalog API requests require a valid bearer token.

API keys created in the [Dev Dashboard](https://dev.shopify.com/dashboard/) provide a client id and secret that can be used to exchange to generate a bearer token.

POST

## /auth/access\_token

```bash
curl --request POST \
  --url https://api.shopify.com/auth/access_token \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "{your_client_id}",
    "client_secret": "{your_client_secret}",
    "grant_type": "client_credentials"
  }'
```

Include your token as a `Authorization: Bearer {token}` header on all API queries.

Learn more about [building agentic commerce experiences](https://shopify.dev/docs/agents/get-started/search-catalog).

GET

## /global/v1/search

```bash
curl -X GET \
  'https://discover.shopifyapps.com/global/v1/search?query=glossier%20lip%20balm' \
  -H 'Authorization: Bearer {BEARER_TOKEN}'
```

## Endpoints and requests

Catalog API endpoints are organized by resource type. You’ll need to use different endpoints depending on your agent's requirements.

All Catalog API endpoints follow this pattern: `https://discover.shopifyapps.com/global/{API_VERSION}/{resource}`.

The Catalog API provides two main endpoints:

* **[Search](#search):** Search for products across the global Shopify Catalog
* **[Lookup](#lookup):** Get detailed product information using a Universal Product ID (UPID)

The references and examples below document `https://discover.shopifyapps.com/global/v1/search` as the endpoint, which assumes Search and Lookup against the entire Shopify catalog. If you want your agents to make requests against a [saved catalog you've created in Dev Dashboard](https://shopify.dev/docs/agents/catalog#saved-catalogs), update the endpoint URLs accordingly.

Tip

For usage guidelines, see [About Catalog](https://shopify.dev/docs/agents/catalog#usage-guidelines).

## Search

Retrieve products from the Shopify Catalog using the `/global/v1/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 Shopify 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/v1/search` endpoint. Replace `{query}` with the buyer's search terms and `{BEARER_TOKEN}` with the bearer token you generated in the Authentication section.

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.

Append additional supported parameters from the table below to the path.

#### Parameters

query•StringRequired (critical)

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.

min\_price•Decimal

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

ships\_from•String

ISO country code. For example, `US`

ships\_to•StringDefault: 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/v1/search

```bash
# Search the Catalog
curl -X GET \
  'https://discover.shopifyapps.com/global/v1/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 and soft cotton-polyester blend.",
    "images": [
      {
        "url": "https://cdn.shopify.com/s/files/1/0000/0001/0002/files/classic-crewneck.webp?v=1700000001",
        "altText": "Classic Crewneck Sweatshirt",
        "product": {
          "id": "gid://shopify/Product/1000000000001",
          "title": "Classic Crewneck Sweatshirt",
          "onlineStoreUrl": "https://mock.shop/products/classic-crewneck-sweatshirt?variant=2000000000001&_gsid=abc123def456",
          "shop": {
            "name": "Mock Shop",
            "onlineStoreUrl": "https://mock.shop"
          }
        }
      }
    ],
    "options": [
      {
        "name": "Color",
        "values": [
          {
            "value": "Heather Gray",
            "availableForSale": true,
            "exists": true
          }
        ]
      },
      {
        "name": "Size",
        "values": [
          {
            "value": "Medium",
```

## Lookup

Retrieve details of a single `UniversalProduct`.

This example illustrates how to retrieve detailed information for a single product using the `UniversalProduct` resource and the `/global{API_VERSION}/p/{upid}` endpoint. Replace `{upid}` with the Universal Product ID for the product of interest and `{bearer_token}` with the bearer token you generated in the Authentication section.

Use this endpoint to retrieve comprehensive variant information, including availability and option filtering.

#### GETRetrieve detailed information about a Universal Product

Retrieve details of a single `UniversalProduct`.

This example illustrates how to retrieve detailed information for a single product using the `UniversalProduct` resource and the `/global{API_VERSION}/p/{upid}` endpoint. Replace `{upid}` with the variant ID of a previous Search query or more generally the Universal Product ID for the product of interest and `{bearer_token}` with the bearer token you generated in the Authentication section.

Use this endpoint to retrieve comprehensive variant information, including availability and option filtering.

Variant selection behavior

If no variant matches the passed option filters, a relaxation of filters occurs to select the closest matching variant. If no match is found, the rightmost option filter is dropped until a match is found. The `selectionState` field in the response indicates whether the variant is a `match` (exact match) or `fallback` (relaxed match).

#### Parameters

\_gsid•String

Reference to the Catalog Search which generated the URL. Optional, and pre-populated in Catalog Search Results.\
\
For example, `xuUi3kiX3Fzt`

available\_for\_sale•Int (0,1)Default: 1 (only available items)

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

include\_secondhand•Int (0,1)Default: 1 (include)

Include secondhand products.\
\
When `1` include secondhand products in the result, not that only secondhand products will appear in the results.

limit•Integer (1-100)Default: 10

Maximum number of 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.

option.{name}•String

Option for inclusive and exclusive filtering. Filter products by appending `option.{NAME}={VALUE}` to the URL. Multiple options can be included per request. Different option keys are combined using **AND** logic. This affects the selected variant on `onlineStoreUrl` and `checkoutUrl`.\
\
For example, `option.color=red&option.material=steel`

option\_preferences•String

Comma-delimited list of option names. If no variant matches passed filters, a relaxation of filters occurs to select the closest matching variant. If no match is found, the rightmost option filter is dropped until a match is found.\
\
For example, `color, material`

query•String

Keywords for search. For example, `Running Shoes`

ships\_from•String

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

ships\_to•StringDefault: 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`

variant\_id•Int

Preselect this product variant. For example, `46731565826293`

GET

## /global/v1/p/{upid}

```bash
# Retrieve details about an individual product.
curl -X GET \
  'https://discover.shopifyapps.com/global/v1/p/{d}' \
  -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 and soft cotton-polyester blend.",
  "images": [
    {
      "url": "https://cdn.shopify.com/s/files/1/0000/0001/0002/files/classic-crewneck-front.webp?v=1700000001",
      "altText": "Classic Crewneck Sweatshirt - Front",
      "product": {
        "id": "gid://shopify/Product/1000000000001",
        "title": "Classic Crewneck Sweatshirt",
        "onlineStoreUrl": "https://mock.shop/products/classic-crewneck-sweatshirt?variant=2000000000001&_gsid=abc123def456",
        "shop": {
          "name": "Mock Shop",
          "onlineStoreUrl": "https://mock.shop"
        }
      }
    },
    {
      "url": "https://cdn.shopify.com/s/files/1/0000/0001/0002/files/classic-crewneck-back.webp?v=1700000002",
      "altText": "Classic Crewneck Sweatshirt - Back",
      "product": {
        "id": "gid://shopify/Product/1000000000001",
        "title": "Classic Crewneck Sweatshirt",
        "onlineStoreUrl": "https://mock.shop/products/classic-crewneck-sweatshirt?variant=2000000000001&_gsid=abc123def456",
        "shop": {
          "name": "Mock Shop",
          "onlineStoreUrl": "https://mock.shop"
        }
      }
    },
    {
      "url": "https://cdn.shopify.com/s/files/1/0000/0001/0002/files/classic-crewneck-detail.webp?v=1700000003",
      "altText": "Classic Crewneck Sweatshirt - Detail",
      "product": {
        "id": "gid://shopify/Product/1000000000001",
```

Note

The schema returned by the Universal Product Id query (Catalog Lookup) is the same returned by the Catalog Search, except for the `UniversalProduct`’s `url` param, which is omitted.

#### Examples

**Use options to pre-select variants.**

By specifying options, you can ensure that the relevant variant is selected when users are redirected to `onlineStoreUrl` and `checkoutUrl`.

For example, consider product `gid://shopify/p/def456GHI789jklMNO123pq` which has multiple color and size options.

Using the request's `option` params, a color and size combination of `Navy/Large` can be specified. The returned payload's `onlineStoreUrl` and `checkoutUrl` will pre-select these options for the user.

Variant selection behavior

If no variant exists with the combination of options that were requested, a relaxation of option filters will occur to find the next best variant. The parameter `option_preferences` can be used to decide the order in which options are relaxed.

## {} Response

```json
{
    "id": "gid://shopify/p/def456GHI789jklMNO123pq",
    "title": "Premium Pullover Hoodie",
    ...
    "options": [
        {
            "name": "color",
            "values": [
                "Heather Gray",
                "Navy",
                "Black",
                "Forest Green",
                "Burgundy",
                "Charcoal",
                "Oatmeal",
                "White"
            ]
        },
        {
            "name": "size",
            "values": [
                "Small",
                "Large"
            ]
        }
    ],
    ...
}
```

GET

## /global/v1/p/{uid}

```bash
curl --location 'https://discover.shopifyapps.com/global/v1/p/def456GHI789jklMNO123pq?ships_to=US&ships_from=US&available_for_sale=1&min_price=25.00&max_price=75.00&query=hoodie&_gsid=xyz789abc123&option.color=Navy&option.size=Large' \
  --header 'Authorization: Bearer API_TOKEN'
```

## {} Response

```json
{
    "id": "gid://shopify/p/def456GHI789jklMNO123pq",
    "title": "Premium Pullover Hoodie",
    ...
    "products": [
        {
            "id": "gid://shopify/Product/1000000000002",
            "title": "Premium Pullover Hoodie",
            "checkoutUrl": "https://mock.shop/cart/2000000000002:1?_gsid=xyz789abc123&payment=shop_pay",
            ...
            "onlineStoreUrl": "https://mock.shop/products/premium-pullover-hoodie?variant=2000000000002&_gsid=xyz789abc123",
            "price": {
                ...
            },
            ...
        },
        ...
}
```

## Resources and schema

Both Search and Lookup endpoints return data structured around the `UniversalProduct` resource, a high-level grouping that represents a product concept across multiple Shopify merchants.

Each `UniversalProduct` contains arrays of related resources like `Image`, `Option`, `Product`, and more that provide complete product and shop information for building commerce experiences and displaying products to customers. The schemas below document all available fields and their relationships.

### The Universal​Product resource

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

#### Properties

availableForSale•boolean

Universal product availability status.

description•string

Detailed product description.

id•string

Unique identifier for the universal product.

For example, `gid://shopify/p/1UT1zYWaL8WeTNCllgUbsM`

images•[Image](#the-image-resource)\[]

Array of product images.

inferredFields•String\[]

Array of fields which are inferred.

For example, `["options","products.secondhand", "products.selectedProductVariant.options"]`

options•[Option](#the-option-resource-search)\[]

Array of product options/variants.

priceRange•[PriceRange](#the-pricerange-resource)

Price range for the universal product.

products•[Product](#the-product-resource)\[]

Array of specific product variants/offers.

rating•[Rating](#the-rating-resource)

Universal product rating information.

title•string

Product title/name.

url•string

URL for subsequent calls to Universal Product ID endpoint. `url` is included in responses from Search, but omitted from Lookup.

## {} The UniversalProduct resource

```json
[
  {
    "id": "gid://shopify/p/abc123XYZ789defGHI456jk",
    "title": "Classic Crewneck Sweatshirt",
    "description": "A comfortable everyday sweatshirt with a classic fit and soft cotton-polyester blend.",
    "images": [
      {
        "url": "https://cdn.shopify.com/s/files/1/0000/0001/0002/files/classic-crewneck.webp?v=1700000001",
        "altText": "Classic Crewneck Sweatshirt",
        "product": {
          "id": "gid://shopify/Product/1000000000001",
          "title": "Classic Crewneck Sweatshirt",
          "onlineStoreUrl": "https://mock.shop/products/classic-crewneck-sweatshirt?variant=2000000000001&_gsid=abc123def456",
          "shop": {
            "name": "Mock Shop",
            "onlineStoreUrl": "https://mock.shop"
          }
        }
      }
    ],
    "options": [
      {
        "name": "Color",
        "values": [
          {
            "value": "Heather Gray",
            "availableForSale": true,
            "exists": true
          }
        ]
      },
      {
        "name": "Size",
        "values": [
          {
            "value": "Medium",
```

### The Image resource

Represents an image associated with a product or product variant.

#### Properties

altText•string

Alternative text for the image.

product•[Product](#the-product-resource)

Associated product information (simplified schema containing id, title, onlineStoreUrl, and shop).

url•string

Image URL.

## {} The Image resource

```json
{
  "url": "https://cdn.shopify.com/s/files/1/0000/0001/0002/files/classic-crewneck.webp?v=1700000001",
  "altText": "Classic Crewneck Sweatshirt",
  "product": {
    "id": "gid://shopify/Product/1000000000001",
    "title": "Classic Crewneck Sweatshirt",
    "onlineStoreUrl": "https://mock.shop/products/classic-crewneck-sweatshirt?variant=2000000000001&_gsid=abc123def456",
    "shop": {
      "name": "Mock Shop",
      "onlineStoreUrl": "https://mock.shop"
    }
  }
}
```

### The Option resource (Search)

Represents a product option like size or color.

#### Properties

name•string

Option name, configured by the merchant. For example, `Size`

values•string\[]

List of option values configured by the merchant. For example, `["US5.5", "US6", "US6.5"]`

## {} The Option resource

```json
[
    {
      "name": "Color",
      "values": [
          "Red",
          "Blue"
      ]
    },
    {
      "name": "Size",
      "values": [
          "Small",
          "Medium",
          "Large"
      ]
    }
  ]
```

### The Option resource (Lookup)

Represents a product option like size or color. When using the universal product lookup, options include availability and existence.

#### Properties

name•string

Option name, configured by the merchant. For example, `Size`

values•[OptionValue](#the-optionvalue-resource)\[]

List of option values configured by the merchant.

## {} The Option resource

```json
[
    {
      "name": "Color",
      "values": [
        {
          "value": "Blue",
          "availableForSale": true,
          "exists": true
        }
      ]
    },
    {
      "name": "Size",
      "values": [
        {
          "value": "Medium",
          "availableForSale": true,
          "exists": true
        }
      ]
    }
  ]
```

### The Option​Value resource

Represents a product option value like US 5.5.

#### Properties

available\_for\_sale•boolean

If this option filter is applied, this is the variant available for sale.

exists•boolean

If this option filter is applied, does a variant exist.

value•string

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

## {} The OptionValue resource

```json
{
  "value": "Blue",
  "availableForSale": true,
  "exists": true
}
```

### The Price​Range resource

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

#### Properties

max•[Price](#the-price-resource)

Maximum price information.

min•[Price](#the-price-resource)

Minimum price information.

## {} The PriceRange resource

```json
{
  "min": {
    "amount": "6.24",
    "currencyCode": "USD"
  },
  "max": {
    "amount": "6.24",
    "currencyCode": "USD"
  }
}
```

### The Price resource

Represents a monetary amount and its currency.

#### Properties

amount•string

Monetary amount. For example, `"45.0"`

currencyCode•string

Currency code. For example, `"CAD"`

## {} The Price resource

```json
{
  "amount": "6.24",
  "currencyCode": "USD"
}
```

### The Product resource

Represents a specific product variant or offer available for sale, typically linked to a specific shop. Nested within UniversalProduct.

#### Properties

availableForSale•boolean

Product availability status.

checkoutUrl•string

Direct checkout URL.

description•string

Product description.

id•string

Unique product identifier. For example, `gid://shopify/Product/7987676283074`

onlineStoreUrl•string

Product page URL.

rating•[Rating](#the-rating-resource)

Product rating details.

selectedProductVariant•[SelectedProductVariant](#the-selectedproductvariant-resource)

Selected product variant.

shop•[Shop](#the-shop-resource)

Associated shop information.

title•string

Product title/name.

## {} The Product resource

```json
{
  "id": "gid://shopify/Product/1000000000001",
  "title": "Classic Crewneck Sweatshirt",
  "checkoutUrl": "https://mock.shop/cart/2000000000001:1?_gsid=abc123def456&payment=shop_pay",
  "description": "A comfortable everyday sweatshirt with a classic fit. Made from a soft cotton-polyester blend, this versatile piece features ribbed cuffs and hem for a secure fit. Perfect for layering or wearing on its own.",
  "featuredImage": {
    "url": "https://cdn.shopify.com/s/files/1/0000/0001/0002/files/classic-crewneck.webp?v=1700000001",
    "altText": "Classic Crewneck Sweatshirt"
  },
  "onlineStoreUrl": "https://mock.shop/products/classic-crewneck-sweatshirt?variant=2000000000001&_gsid=abc123def456",
  "price": {
    "amount": "45.00",
    "currencyCode": "USD"
  },
  "rating": null,
  "availableForSale": true,
  "shop": {
    "name": "Mock Shop",
    "paymentSettings": {
      "supportedDigitalWallets": [
        "SHOPIFY_PAY"
      ],
      "acceptedCardBrands": [
        "visa",
        "master",
        "american_express",
        "discover",
        "diners_club",
        "visadebit",
        "masterdebit"
      ]
    },
    "onlineStoreUrl": "https://mock.shop",
    "privacyPolicy": {
      "url": "https://checkout.shopify.com/10000000001/policies/20000000001.html?locale=en"
    },
    "refundPolicy": {
      "url": "https://checkout.shopify.com/10000000001/policies/20000000002.html?locale=en"
    },
    "termsOfService": {
      "url": "https://checkout.shopify.com/10000000001/policies/20000000003.html?locale=en"
    },
    "shippingPolicy": {
      "url": "https://checkout.shopify.com/10000000001/policies/20000000004.html?locale=en"
    },
    "id": "gid://shopify/Shop/10000000001",
    "permanentDomain": "mock-shop.myshopify.com"
  },
  "selectedProductVariant": {
    "id": "gid://shopify/ProductVariant/2000000000001?shop=10000000001",
    "availableForSale": true,
    "options": [
      {
        "name": "Color",
        "value": "Heather Gray"
      },
      {
        "name": "Size",
        "value": "Medium"
      }
    ],
    "price": {
      "amount": "45.00",
      "currencyCode": "USD"
    },
    "image": {
      "url": "https://cdn.shopify.com/s/files/1/0000/0001/0002/files/classic-crewneck.webp?v=1700000001",
      "altText": "Classic Crewneck Sweatshirt"
    }
  },
  "secondhand": false,
  "requiresSellingPlan": false,
  "eligibleForNativeCheckout": false
}
```

### The Shop resource

Represents the shop offering the product.

#### Properties

id•string

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

name•string

Shop name.

onlineStoreUrl•string

Shop page URL.

paymentSettings•[PaymentSettings](#the-paymentsettings-resource)

Shop's payment configuration.

permanentDomain•string

Shop's permanent domain. For example, `mock-shop.myshopify.com`

privacyPolicy•[Policy](#the-policy-resource)

Shop's privacy policy.

refundPolicy•[Policy](#the-policy-resource)

Shop's refund policy.

shippingPolicy•[Policy](#the-policy-resource)

Shop's shipping policy.

termsOfService•[Policy](#the-policy-resource)

Shop's terms of service.

## {} The Shop resource

```json
{
  "name": "Mock Shop",
  "paymentSettings": {
    "supportedDigitalWallets": [
      "SHOPIFY_PAY"
    ],
    "acceptedCardBrands": [
      "visa",
      "master",
      "american_express",
      "discover",
      "diners_club",
      "visadebit",
      "masterdebit"
    ]
  },
  "onlineStoreUrl": "https://mock.shop",
  "privacyPolicy": {
    "url": "https://checkout.shopify.com/10000000001/policies/20000000001.html?locale=en"
  },
  "refundPolicy": {
    "url": "https://checkout.shopify.com/10000000001/policies/20000000002.html?locale=en"
  },
  "termsOfService": {
    "url": "https://checkout.shopify.com/10000000001/policies/20000000003.html?locale=en"
  },
  "shippingPolicy": {
    "url": "https://checkout.shopify.com/10000000001/policies/20000000004.html?locale=en"
  },
  "id": "gid://shopify/Shop/10000000001",
  "permanentDomain": "mock-shop.myshopify.com"
}
```

### The Payment​Settings resource

Configuration details for the shop's payment methods.

#### Properties

acceptedCardBrands•string\[]

Array of supported credit card payment methods. For example, `["visa", "master"]`

supportedDigitalWallets•string\[]

Array of supported digital payment methods. For example, `["SHOPIFY_PAY"]`

## {} The PaymentSettings resource

```json
{
  "supportedDigitalWallets": [
    "SHOPIFY_PAY"
  ],
  "acceptedCardBrands": [
    "visa",
    "master",
    "american_express",
    "discover",
    "diners_club",
    "visadebit",
    "masterdebit"
  ]
}
```

### The Rating resource

Details about product ratings.

#### Properties

count•integer

Number of ratings. For example, `18`

value•float

Average rating value. For example, `4.9`

## {} The Rating resource

```json
{
  "count": 18,
  "value": 4.9
}
```

### The Policy resource

Details about shop policies.

#### Properties

url•string

Policy's URL.

## {} The Policy resource

```json
{
  "url": "https://checkout.shopify.com/10000000001/policies/20000000001.html?locale=en"
}
```

### The Selected​Product​Variant resource

Details about the selected product variant.

#### Properties

availableForSale•boolean

Product variant availability status.

id•string

Unique product variant identifier. For example, `gid://shopify/ProductVariant/7987676283074`

image•[Image](#the-image-resource)

Selected product variant image.

options•[Option](#the-option-resource-search)\[]

Array of options of the selected product variant.

price•[Price](#the-price-resource)

Product variant price information.

selectionState•[SelectionState](#the-selectionstate-resource)

Information about whether variant matches requested parameters.

## {} The SelectedProductVariant resource

```json
{
  "id": "gid://shopify/ProductVariant/2000000000001?shop=10000000001",
  "availableForSale": true,
  "options": [
    {
      "name": "Color",
      "value": "Heather Gray"
    },
    {
      "name": "Size",
      "value": "Medium"
    }
  ],
  "price": {
    "amount": "45.00",
    "currencyCode": "USD"
  },
  "image": {
    "url": "https://cdn.shopify.com/s/files/1/0000/0001/0002/files/classic-crewneck.webp?v=1700000001",
    "altText": "Classic Crewneck Sweatshirt"
  }
}
```

### The Selection​State resource

Details about how the variant was selected. If both options and variant id was requested, variant id takes precedence.

#### Properties

requestedFilters•[RequestedFilter](#the-requestedfilter-resource)\[]

List of options that were requested by client.

requestedVariantId•string

Variant id that was requested by client. For example, `7987676283074`

type•string

Whether variant matches requested parameters. `match` if variant matches requested filters/variant id, `fallback` if variant does not match.

## {} The SelectionState resource

```json
{
  "type": "match",
  "requestedFilters": [
    {
      "name": "Size",
      "value": "Large"
    }
  ],
  "requestedVariantId": "7987676283074"
}
```

### The Requested​Filter resource

Represents a product option like size or color that was passed as a URL parameter.

#### Properties

name•string

Option name. For example, `Size`

value•string

Option value. For example, `US5.5`

## {} The RequestedFilter resource

```json
{
  "name": "Size",
  "value": "Large"
}
```

## Status and error codes

All API queries return HTTP status codes that can tell you more about the response.

200 OK

The request was successful.

400 Bad Request

The request contains invalid parameters. Check the `errors` object in the response for details.

401 Unauthorized

The bearer token is missing or invalid.

404 Not Found

The requested product (UPID) was not found.

429 Too Many Requests

Rate limit exceeded. Wait before retrying.

## {} Sample error responses

##### 400

```json
{
  "errors": {
    "limit": ["must be greater than or equal to 1"],
    "max_price": ["must be greater than 0"],
    "categories": {
      "0": ["must be a Shopify Taxonomy category identifier"]
    }
  }
}
```

##### 401

```json
{
  "error": "Unauthorized"
}
```

##### 404

```json
{
  "errors": {
    "product": [
      "Not found"
    ]
  }
}
```