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

# Lookup

Retrieve details of a single `UniversalProduct`.

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

***

## GETGet details about a Universal Product

This example illustrates how to retrieve detailed information for a single product using the `UniversalProduct` resource and the `/global/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.

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

***

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

Maximum number of results to return.

***

`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`•`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`

***

`variant_id`•`Int`

Preselect this product variant. For example, `46731565826293`

***

GET

## /global/v2/p/{upid}

```bash
curl -X GET \
  'https://discover.shopifyapps.com/global/v2/p/{upid}' \
  -H 'Authorization: Bearer {BEARER_TOKEN}'
```

## {} Response

```json
{
  "id": "gid://shopify/p/abc123XYZ789defGHI456jk",
  "description": "A comfortable everyday sweatshirt with a classic fit and soft cotton-polyester blend.",
  "options": [
    {
      "name": "Color",
      "values": [
        { "value": "Heather Gray", "availableForSale": true, "exists": true }
      ]
    },
    {
      "name": "Size",
      "values": [
        { "value": "Medium", "availableForSale": true, "exists": true }
      ]
    }
  ],
  "selectedOptions": [
    { "name": "Color", "value": "Heather Gray" },
    { "name": "Size", "value": "Medium" }
  ],
  "rating": { "rating": 4.5, "count": 128 },
  "featuredVariantId": "gid://shopify/ProductVariant/2000000000001?shop=10000000001",
  "featuredVariantMedia": [
    {
      "url": "https://cdn.shopify.com/s/files/1/0000/0001/0002/files/classic-crewneck-front.webp?v=1700000001",
      "altText": "Classic Crewneck Sweatshirt"
    }
  ],
  "variants": [
    {
      "id": "gid://shopify/ProductVariant/2000000000001?shop=10000000001",
      "productId": "gid://shopify/Product/1000000000001",
      "displayName": "Classic Crewneck Sweatshirt - Heather Gray / Medium",
      "productDescription": "A comfortable everyday sweatshirt with a classic fit.",
      "availableForSale": true,
      "price": { "amount": 4500, "currency": "USD" },
      "media": [
        {
          "url": "https://cdn.shopify.com/s/files/1/0000/0001/0002/files/classic-crewneck-front.webp?v=1700000001",
          "altText": "Classic Crewneck Sweatshirt"
        }
      ],
      "shop": {
        "id": "gid://shopify/Shop/10000000001",
        "name": "Mock Shop",
        "onlineStoreUrl": "https://mock.shop",
        "privacyPolicy": { "url": "https://checkout.shopify.com/10000000001/policies/20000000001.html" },
        "refundPolicy": { "url": "https://checkout.shopify.com/10000000001/policies/20000000002.html" },
        "termsOfService": { "url": "https://checkout.shopify.com/10000000001/policies/20000000003.html" },
        "shippingPolicy": { "url": "https://checkout.shopify.com/10000000001/policies/20000000004.html" },
        "permanentDomain": "mock-shop.myshopify.com"
      },
      "variantUrl": "https://mock.shop/products/classic-crewneck-sweatshirt?variant=2000000000001",
      "checkoutUrl": "https://mock.shop/cart/2000000000001:1?payment=shop_pay",
      "eligibleForNativeCheckout": false,
      "rating": { "rating": 4.7, "count": 89 },
      "secondhand": false
    }
  ],
  "uniqueSellingPoint": "Features a soft cotton-polyester blend with ribbed details.",
  "topFeatures": [
    "50/50 cotton polyester blend provides softness and durability",
    "Classic crewneck design suitable for layering",
    "Ribbed collar, cuffs, and hem ensure a secure fit"
  ],
  "techSpecs": [
    "Weight: 8.0 oz",
    "Material: 50% cotton, 50% polyester",
    "Available Sizes: S, M, L, XL, 2XL"
  ],
  "attributes": [
    { "name": "Fabric", "values": ["Cotton", "Polyester"] },
    { "name": "Neckline", "values": ["Crew"] },
    { "name": "Pattern", "values": ["Solid"] },
    { "name": "Age group", "values": ["Adults"] },
    { "name": "Target gender", "values": ["Unisex"] }
  ]
}
```

**Note:**

The schema returned by Lookup is the same as Search, except the `url` field 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/v2/p/{uid}

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

## {} Response

```json
{
    "id": "gid://shopify/p/def456GHI789jklMNO123pq",
    "description": "A cozy pullover hoodie with kangaroo pocket and drawstring hood.",
    ...
    "variants": [
        {
            "id": "gid://shopify/ProductVariant/2000000000002?shop=10000000001",
            "productId": "gid://shopify/Product/1000000000002",
            "displayName": "Premium Pullover Hoodie - Navy / Large",
            "productDescription": "A cozy pullover hoodie...",
            ...
            "variantUrl": "https://mock.shop/products/premium-pullover-hoodie?variant=2000000000002&_gsid=xyz789abc123",
            "checkoutUrl": "https://mock.shop/cart/2000000000002:1?_gsid=xyz789abc123&payment=shop_pay",
            "price": {
                ...
            },
            ...
        },
        ...
}
```

***

## Lookup response schema

The Lookup endpoint returns a single `UniversalProduct` object with comprehensive product details for building product detail pages.

### 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`•`Attribute[]``Inferred`

Array of product attributes.

***

`description`•`string``Inferred`

Detailed product description.

***

`featuredVariantId`•`string`

The ID of the featured variant for this product.

***

`featuredVariantMedia`•`Media[]`

Media for the featured variant. Currently returns images only.

***

`id`•`string`

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

***

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

Array of product options/variants.

***

`rating`•`Rating`

Universal product rating information.

***

`selectedOptions`•`VariantOption[]`

Array of selected variant options.

***

`status`•`Status`

Product status information.

***

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

Array of technical specifications.

***

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

Array of top product features.

***

`uniqueSellingPoint`•`string``Inferred`

The unique selling point for the product.

***

`variants`•`Variant[]`

Array of product variants. Default: 5.

***

## {} UniversalProduct

```json
{
  "id": "gid://shopify/p/abc123XYZ789defGHI456jk",
  "description": "A comfortable everyday sweatshirt.",
  "featuredVariantId": "gid://shopify/ProductVariant/2000000000001",
  "featuredVariantMedia": [
    { "url": "https://cdn.shopify.com/.../variant.webp", "altText": "Featured variant" }
  ],
  "options": [
    {
      "name": "Color",
      "values": [
        { "value": "Heather Gray", "availableForSale": true, "exists": true },
        { "value": "Navy", "availableForSale": false, "exists": true }
      ]
    }
  ],
  "selectedOptions": [
    { "name": "Color", "value": "Heather Gray" }
  ],
  "status": null,
  "variants": [
    {
      "id": "gid://shopify/ProductVariant/2000000000001",
      "productId": "gid://shopify/Product/1000000000001",
      "displayName": "Classic Crewneck - Heather Gray",
      "availableForSale": true,
      "price": { "amount": 4500, "currency": "USD" },
      "shop": {
        "id": "gid://shopify/Shop/10000000001",
        "name": "Mock Shop",
        "permanentDomain": "mock-shop.myshopify.com"
      }
    }
  ],
  "rating": { "rating": 4.5, "count": 120 }
}
```

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

***

`media`•`Media[]`

Media for this variant. Currently returns images only.

***

`price`•`Price`

Price information for this variant.

***

`productDescription`•`string`

Description of the parent product.

***

`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",
  "productId": "gid://shopify/Product/1000000000001",
  "displayName": "Classic Crewneck - Heather Gray",
  "productDescription": "A comfortable everyday sweatshirt.",
  "availableForSale": true,
  "price": { "amount": 4500, "currency": "USD" },
  "media": [
    { "url": "https://cdn.shopify.com/.../variant.webp", "altText": "Heather Gray variant" }
  ],
  "shop": {
    "id": "gid://shopify/Shop/10000000001",
    "name": "Mock Shop",
    "permanentDomain": "mock-shop.myshopify.com"
  },
  "variantUrl": "https://mock.shop/products/crewneck?variant=2000000000001",
  "checkoutUrl": "https://mock.shop/cart/2000000000001:1",
  "eligibleForNativeCheckout": true,
  "rating": { "rating": 4.8, "count": 24 },
  "secondhand": false
}
```

### The Shop resource

Represents the shop offering the product. In Lookup responses, Shop includes policy 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`.

***

`privacyPolicy`•`Policy`

Shop's privacy policy.

***

`refundPolicy`•`Policy`

Shop's refund policy.

***

`shippingPolicy`•`Policy`

Shop's shipping policy.

***

`termsOfService`•`Policy`

Shop's terms of service.

***

## {} Shop

```json
{
  "id": "gid://shopify/Shop/10000000001",
  "name": "Mock Shop",
  "onlineStoreUrl": "https://mock.shop",
  "permanentDomain": "mock-shop.myshopify.com",
  "privacyPolicy": { "url": "https://checkout.shopify.com/.../privacy.html" },
  "refundPolicy": { "url": "https://checkout.shopify.com/.../refund.html" },
  "shippingPolicy": { "url": "https://checkout.shopify.com/.../shipping.html" },
  "termsOfService": { "url": "https://checkout.shopify.com/.../terms.html" }
}
```

### 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", "availableForSale": true, "exists": true },
    { "value": "Navy", "availableForSale": false, "exists": true }
  ]
}
```

### The Option​Value resource

Represents a product option value. In Lookup responses, OptionValue includes availability information.

#### Properties

***

`availableForSale`•`boolean`

Whether a variant with this option is available for sale.

***

`exists`•`boolean`

Whether a variant with this option exists.

***

`value`•`string`

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

***

## {} OptionValue

```json
{
  "value": "Heather Gray",
  "availableForSale": true,
  "exists": true
}
```

### The Attribute resource

Represents a product attribute with a name and array of values.

#### Properties

***

`name`•`string`

Attribute name.

***

`values`•`string[]`

Array of attribute values.

***

## {} Attribute

```json
{
  "name": "Fabric",
  "values": ["Cotton", "Polyester"]
}
```

### The Status resource

Indicates the state of the requested UPID or variant, including whether it was redirected, expired, or fell back to a different selection.

#### Properties

***

`requestedFilters`•`string`

Indicates if the requested filters caused a fallback. Value: `fallback`

***

`requestedId`•`string`

Indicates if the requested product ID was redirected or expired. Values: `redirected`, `expired`

***

`requestedVariantId`•`string`

Indicates if the requested variant caused a fallback. Value: `fallback`

***

## {} Status

```json
{
  "requestedId": "redirected",
  "requestedVariantId": null,
  "requestedFilters": null
}
```

### The Policy resource

Represents a shop policy document.

#### Properties

***

`url`•`string`

URL to the policy document.

***

## {} Policy

```json
{
  "url": "https://checkout.shopify.com/.../policies/privacy.html"
}
```

### 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
}
```

### 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"
}
```

***