Listing (v3)

Get Products In Listing, Via External Id

Returns products in a listing, optionally filtered. Used for product listing pages. Example response: <pre> { "displays": [ { "variant_index": 1, "variant_displays": [ { "in_stock": true, "original_price": 1999, "sale_price": 1999, "title": "Short Sleeve Polo Shirt", "size": "210", "product_id": "1500-10-210", "image_urls": [ "https://example.cdn.com/1.jpg", "https://example.cdn.com/2.jpg", ] }, { "in_stock": true, "original_price": 1999, "sale_price": 1999, "title": "Short Sleeve Polo Shirt", "size": "200", "product_id": "1500-10-200", "image_urls": [ "https://example.cdn.com/1.jpg", "https://example.cdn.com/2.jpg", ] }, ], "product_listing_result_id": "50877e3b-26a4-4ea7-a6e1-1a7696f76f66" }, { "variant_index": 0, "variant_displays": [ { "in_stock": false, "original_price": 1400, "sale_price": 1200, "title": "Collar Polo Shirt", "size": "210", "product_id": "1600-10-210", "image_urls": [ "https://example.cdn.com/10.jpg", "https://example.cdn.com/11.jpg", ] } ], "product_listing_result_id": "671740b5-6828-41fc-8a3f-2869993d000c" } ], "n_hits": 2, "sorts": [ { "field": "_relevance", "order": "desc", "meta": { "title": "Recommended", "values": [ "desc" ], "names": [ "Recommended" ] } }, { "field": "title", "order": "asc", "meta": { "title": "Alphabetical, A-Z", "values": [ "asc" ], "names": [ "Alphabetical, A-Z" ] } }, { "field": "title", "order": "desc", "meta": { "title": "Alphabetical, Z-A", "values": [ "desc" ], "names": [ "Alphabetical, Z-A" ] } }, { "field": "sale_price", "order": "asc", "meta": { "title": "Price, low to high", "values": [ "asc" ], "names": [ "Price, low to high" ] } }, { "field": "sale_price", "order": "desc", "meta": { "title": "Price, high to low", "values": [ "desc" ], "names": [ "Price, high to low" ] } } ], "filters": [ { "field": "sale_price", "op": "inrange", "data": [ 1200, 1999 ], "meta": { "group_title": "Price", "type": "range", "min": 1200, "max": 1999, "currency": "SEK" }, "id": "price0" }, { "field": "size_name", "op": "in", "meta": { "group_title": "Size", "type": "checkbox-grid", "values": [ "200", "210", ], "counts": [ 1, 2 ] }, "id": "size1" } ], "product_listing_request_id": "4bf1eeb0-0b0a-4b0e-9b0a-0a0b0a0b0a0b", "cursor": "eyJjIjogMjAsICJyIjogMjB9" } </pre>

POST

listings

external_id

{external_id}

products

{
  "displays": [
    {}
  ],
  "n_hits": 123,
  "sorts": [
    {
      "field": "<string>",
      "order": "asc",
      "meta": {
        "title": "<string>",
        "values": [
          "asc"
        ],
        "names": [
          "<string>"
        ]
      }
    }
  ],
  "filters": [
    {
      "field": "<string>",
      "op": "eq",
      "data": "true",
      "meta": {
        "group_title": "<string>",
        "group_expanded": true,
        "type": "<any>",
        "min": 123,
        "max": 123,
        "unit": "<string>",
        "currency": "<string>"
      },
      "id": "<string>"
    }
  ],
  "product_listing_request_id": "<string>",
  "cursor": "<string>"
}

Authorizations

api_key

string

query

required

Headers

x-use-db-display-store

boolean

default:false

Path Parameters

external_id

string | null

required

Query Parameters

listing_id

string | null

Body

application/json

market

string

required

merchant

string

required

locale

string

required

cursor

string | null

Used for cursor-based pagination. Set it to the cursor from the last response. If not set, will return the first results.

Maximum length: 500

limit

integer | null

Maximum number of results per response.

Required range: 1 <= x <= 250

filters

object[] | null

List of filters to apply to the results.

sort

object | null

Specifies the sorting method. By default, the results are ordered by relevance. To find the possible values for this field, query the endpoint and look at the sorts field.

session_id

string | null

Session identifier

Minimum length: 1

metadata

object | null

Metadata that can be used to modify the behaviour of the search.

listing_id

string

Response

200

application/json

Successful Response

displays

object[]

required

The products to be shown on the product listing page.

n_hits

integer

required

Total number of results for this query. Not necessarily exact.

product_listing_request_id

string

required

sorts

object[] | null

Available methods for sorting the response. Any element from this list can be sent as sort in subsequent requests.

filters

object[] | null

Available filters that can be used for filtering in the subsequent request.

cursor

string | null

Cursor that can be used in the next request to get subsequent results. If this is not set, there are no more results.

Maximum length: 500

Was this page helpful?

Get Listing Get Products In Listing

{
  "displays": [
    {}
  ],
  "n_hits": 123,
  "sorts": [
    {
      "field": "<string>",
      "order": "asc",
      "meta": {
        "title": "<string>",
        "values": [
          "asc"
        ],
        "names": [
          "<string>"
        ]
      }
    }
  ],
  "filters": [
    {
      "field": "<string>",
      "op": "eq",
      "data": "true",
      "meta": {
        "group_title": "<string>",
        "group_expanded": true,
        "type": "<any>",
        "min": 123,
        "max": 123,
        "unit": "<string>",
        "currency": "<string>"
      },
      "id": "<string>"
    }
  ],
  "product_listing_request_id": "<string>",
  "cursor": "<string>"
}

Glossary

Shopify app

Data ingestion

Search

Product Listing Pages

Product Listing Pages and Search

Looks

Recommendations SDK

Tracking Product Interactions

HTTP API

Get Products In Listing, Via External Id

Authorizations

Headers

Path Parameters

Query Parameters

Body

Response