> ## Documentation Index
> Fetch the complete documentation index at: https://docs.depict.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Products In Listing, Via External Id
This page does not apply to installs made in 2025 or later of the Depict Shopify apps
## OpenAPI
````yaml post /v3/listings/external_id/{external_id}/products
openapi: 3.1.0
info:
title: Depict API
version: '1.0'
servers: []
security: []
paths:
/v3/listings/external_id/{external_id}/products:
post:
tags:
- Listing (v3)
summary: Get Products In Listing, Via External Id
description: >-
Returns products in a listing, optionally filtered. Used for product
listing pages.
Example response:
{
"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"
}
operationId: >-
Get_Products_in_Listing__via_external_ID_v3_listings_external_id__external_id__products_post
parameters:
- name: external_id
in: path
required: true
schema:
anyOf:
- type: string
- type: 'null'
title: External Id
- name: listing_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Listing Id
- name: x-use-db-display-store
in: header
required: false
schema:
type: boolean
default: false
title: X-Use-Db-Display-Store
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProductListingRequestV3'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ProductListingResponseV3'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyQuery: []
- APIKeyHeader: []
- APIKeyCookie: []
components:
schemas:
ProductListingRequestV3:
properties:
cursor:
anyOf:
- type: string
maxLength: 500
- type: 'null'
title: Cursor
description: >-
Used for cursor-based pagination. Set it to the cursor from the last
response. If not set, will return the first results.
limit:
anyOf:
- type: integer
maximum: 250
minimum: 1
- type: 'null'
title: Limit
description: Maximum number of results per response.
market:
type: string
title: Market
filters:
anyOf:
- items:
$ref: '#/components/schemas/SearchFilter'
type: array
- type: 'null'
title: Filters
description: List of filters to apply to the results.
sort:
anyOf:
- $ref: '#/components/schemas/SortModel-Input'
- type: 'null'
description: >-
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:
anyOf:
- type: string
minLength: 1
- type: 'null'
title: Session Id
description: Session identifier
metadata:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Metadata
description: Metadata that can be used to modify the behaviour of the search.
merchant:
type: string
title: Merchant
locale:
type: string
title: Locale
listing_id:
type: string
format: uuid
title: Listing Id
additionalProperties: false
type: object
required:
- market
- merchant
- locale
title: ProductListingRequestV3
ProductListingResponseV3:
properties:
displays:
items:
type: object
type: array
title: Displays
description: The products to be shown on the product listing page.
n_hits:
type: integer
title: N Hits
description: Total number of results for this query. Not necessarily exact.
sorts:
anyOf:
- items:
$ref: '#/components/schemas/SortModel-Output'
type: array
- type: 'null'
title: Sorts
description: >-
Available methods for sorting the response. Any element from this
list can be sent as `sort` in subsequent requests.
filters:
anyOf:
- items:
$ref: '#/components/schemas/SearchFilter'
type: array
- type: 'null'
title: Filters
description: >-
Available filters that can be used for filtering in the subsequent
request.
product_listing_request_id:
type: string
title: Product Listing Request Id
cursor:
anyOf:
- type: string
maxLength: 500
- type: 'null'
title: Cursor
description: >-
Cursor that can be used in the next request to get subsequent
results. If this is not set, there are no more results.
additionalProperties: false
type: object
required:
- displays
- n_hits
- product_listing_request_id
title: ProductListingResponseV3
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
SearchFilter:
properties:
field:
type: string
title: Field
description: The field to filter by.
op:
type: string
enum:
- eq
- neq
- in
- nin
- leq
- geq
- inrange
title: Op
description: >-
The operation used for filtering. The filtering should be read as
`field op data`, for example `brand in ["Nike", "Adidas"]`.
data:
anyOf:
- type: string
enum:
- 'true'
- 'false'
- type: number
- type: integer
- type: string
- prefixItems:
- type: number
- type: number
type: array
maxItems: 2
minItems: 2
- prefixItems:
- type: integer
- type: integer
type: array
maxItems: 2
minItems: 2
- prefixItems:
- type: integer
- type: number
type: array
maxItems: 2
minItems: 2
- prefixItems:
- type: number
- type: integer
type: array
maxItems: 2
minItems: 2
- items:
anyOf:
- type: string
enum:
- 'true'
- 'false'
- type: number
- type: integer
- type: string
- prefixItems:
- type: number
- type: number
type: array
maxItems: 2
minItems: 2
- prefixItems:
- type: integer
- type: integer
type: array
maxItems: 2
minItems: 2
- prefixItems:
- type: integer
- type: number
type: array
maxItems: 2
minItems: 2
- prefixItems:
- type: number
- type: integer
type: array
maxItems: 2
minItems: 2
type: array
- items:
items:
type: string
type: array
type: array
- type: 'null'
title: Data
description: Data for the filter.
meta:
anyOf:
- oneOf:
- $ref: '#/components/schemas/RangeFilterMeta'
- $ref: '#/components/schemas/ValuesFilterMeta'
- $ref: '#/components/schemas/HierarchicalValuesFilterMeta'
discriminator:
propertyName: type
mapping:
checkbox:
$ref: '#/components/schemas/ValuesFilterMeta'
checkbox-color:
$ref: '#/components/schemas/ValuesFilterMeta'
checkbox-grid:
$ref: '#/components/schemas/ValuesFilterMeta'
checkbox-hierarchical:
$ref: '#/components/schemas/HierarchicalValuesFilterMeta'
radio:
$ref: '#/components/schemas/ValuesFilterMeta'
range:
$ref: '#/components/schemas/RangeFilterMeta'
- type: 'null'
title: Meta
description: >-
Metadata about the filter that can be used for rendering. For
example, this could contain the possible values to filter by and
their counts in the results.
id:
anyOf:
- type: string
- type: 'null'
title: Id
description: >-
ID of the filter. If multiple filters share the same ID, they should
be grouped together in the UI.
additionalProperties: false
type: object
required:
- field
- op
title: SearchFilter
SortModel-Input:
properties:
field:
type: string
title: Field
description: The field to sort by.
order:
allOf:
- $ref: '#/components/schemas/SortingOrder'
description: The order to sort by.
meta:
anyOf:
- $ref: '#/components/schemas/SortMeta'
- type: 'null'
description: 'Metadata about the sort that can be used for rendering. '
additionalProperties: false
type: object
required:
- field
- order
title: SortModel
SortModel-Output:
properties:
field:
type: string
title: Field
description: The field to sort by.
order:
allOf:
- $ref: '#/components/schemas/SortingOrder'
description: The order to sort by.
meta:
anyOf:
- $ref: '#/components/schemas/SortMeta'
- type: 'null'
description: 'Metadata about the sort that can be used for rendering. '
additionalProperties: false
type: object
required:
- field
- order
title: SortModel
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
RangeFilterMeta:
properties:
group_title:
anyOf:
- type: string
- type: 'null'
title: Group Title
description: >-
Title of the group, where a group consists of all the filters that
share an ID.
group_expanded:
anyOf:
- type: boolean
- type: 'null'
title: Group Expanded
description: Whether the filter group should be expanded by default or not.
type:
const: range
title: Type
min:
type: number
title: Min
description: The minimum value that can be selected in the range.
max:
type: number
title: Max
description: The maximum value that can be selected in the range.
unit:
anyOf:
- type: string
- type: 'null'
title: Unit
description: The unit of the range values.
currency:
anyOf:
- type: string
- type: 'null'
title: Currency
description: The currency of the range values.
additionalProperties: false
type: object
required:
- type
- min
- max
title: RangeFilterMeta
ValuesFilterMeta:
properties:
group_title:
anyOf:
- type: string
- type: 'null'
title: Group Title
description: >-
Title of the group, where a group consists of all the filters that
share an ID.
group_expanded:
anyOf:
- type: boolean
- type: 'null'
title: Group Expanded
description: Whether the filter group should be expanded by default or not.
type:
type: string
enum:
- radio
- checkbox
- checkbox-grid
- checkbox-color
title: Type
description: Type of filter.
values:
items:
anyOf:
- type: string
enum:
- 'true'
- 'false'
- type: number
- type: integer
- type: string
- prefixItems:
- type: number
- type: number
type: array
maxItems: 2
minItems: 2
- prefixItems:
- type: integer
- type: integer
type: array
maxItems: 2
minItems: 2
- prefixItems:
- type: integer
- type: number
type: array
maxItems: 2
minItems: 2
- prefixItems:
- type: number
- type: integer
type: array
maxItems: 2
minItems: 2
type: array
title: Values
description: Selectable values
counts:
anyOf:
- items:
type: integer
type: array
- type: 'null'
title: Counts
description: Counts for values
names:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Names
description: >-
Names for values. This is what should be displayed along with the UI
item for the value.
additionalProperties: false
type: object
required:
- type
- values
title: ValuesFilterMeta
HierarchicalValuesFilterMeta:
properties:
group_title:
anyOf:
- type: string
- type: 'null'
title: Group Title
description: >-
Title of the group, where a group consists of all the filters that
share an ID.
group_expanded:
anyOf:
- type: boolean
- type: 'null'
title: Group Expanded
description: Whether the filter group should be expanded by default or not.
type:
const: checkbox-hierarchical
title: Type
values:
items:
items:
type: string
type: array
type: array
title: Values
description: Selectable hierarchical values
counts:
anyOf:
- items:
type: integer
type: array
- type: 'null'
title: Counts
description: Counts for values
names:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Names
description: >-
Names for hierarchical values, this is what you should display in
the UI (not values)
additionalProperties: false
type: object
required:
- type
- values
title: HierarchicalValuesFilterMeta
SortingOrder:
type: string
enum:
- asc
- desc
title: SortingOrder
SortMeta:
properties:
title:
type: string
title: Title
values:
items:
$ref: '#/components/schemas/SortingOrder'
type: array
title: Values
description: Selectable values
names:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Names
description: >-
Names for orders (this is what you should display in the UI, not
values)
additionalProperties: false
type: object
required:
- title
title: SortMeta
securitySchemes:
APIKeyQuery:
type: apiKey
in: query
name: api_key
APIKeyHeader:
type: apiKey
in: header
name: X-API-KEY
APIKeyCookie:
type: apiKey
in: cookie
name: X-API-KEY
````