List Products

🔒
Requires read_product access scope. For more access scope

The Product List API allows developers to retrieve detailed product data with advanced filtering, pagination, and field selection capabilities. This endpoint supports querying by product attributes such as title, ids, and vendors, as well as by specific date ranges for creation, updates, or publication.This API is especially useful for:

Managing large product catalogs efficiently through advanced filtering and pagination.
Optimizing data retrieval by selecting only the required fields, reducing response payload size.

Request Parameters

Public Request Parameters

📘
Public Request Parameters

Query Parameters

Parameter	Type	Required	Description	Example
`ids`	array of strings	No	Filter by specific product IDs	`["prod_123", "prod_456"]`
`title`	string	No	Filter by product title	`"Wireless Headphones"`
`collection_id`	string	No	Filter by collection ID	`"9e79ca1f-9ff2-409b-976f-98be343d38a3"`
`created_at_min`	string	No	Filter products created after date	`"2025-01-01T00:00:00Z"`
`created_at_max`	string	No	Filter products created before date	`"2025-06-01T00:00:00Z"`
`updated_at_min`	string	No	Filter products updated after date	`"2025-05-01T00:00:00Z"`
`updated_at_max`	string	No	Filter products updated before date	`"2025-06-01T00:00:00Z"`
`published_at_min`	string	No	Filter products published after date	`"2025-05-15T00:00:00Z"`
`published_at_max`	string	No	Filter products published before date	`"2025-06-15T00:00:00Z"`
`published_status`	string	No	Filter by publish status	`"published"`
`spus`	array of strings	No	Filter by SPU codes	`["SPU123", "SPU456"]`
`pre_cursor`	string	No	Pagination cursor for previous page	`"eyJpZCI6IjEyMzQ1Njc4OSI="`
`cursor`	string	No	Pagination cursor for next page	`"eyJpZCI6IjEyMzQ1Njc4OSI="`
`per_page`	int32	No	Items per page (max 250)	`50`
`fields`	array of strings	No	Fields to include in response	`["id", "title", "price"]`
`sort_direction`	string	No	Sort direction	`"desc"`
`exclude_ids`	array of strings	No	Product IDs to exclude	`["prod_789"]`
`product_type`	string	No	Filter by product type	`"gift_card"`
`product_behaviour`	string	No	Filter by product behavior	`"hidden"`
`location_id`	string	No	Filter by inventory location	`"loc_123"`
`vendors`	array of strings	No	Filter by exact vendor matches	`["Sony", "Bose"]`
`vendors_match`	array of strings	No	Filter by partial vendor matches	`["son", "bo"]`
`handles`	array of strings	No	Filter products by handle	`["handle1", "handle2"]`

Response Explanation

Public Response Parameters

📘
Public Response Parameters

Successful Response

Parameter	Type	Example	Description
`code`	string	`"200"`	HTTP status code
`message`	string	`"Success"`	Operation result message
`data.cursor`	string	`"eyJpZCI6IjEyMzQ1Njc4OSI="`	Next page cursor
`data.pre_cursor`	string	`"eyJpZCI6IjEyMzQ1Njc4OSI="`	Previous page cursor
`data.products`	array of objects	-	List of products

Product Object

Parameter	Type	Example	Description
`id`	string	`"prod_123"`	Product ID
`title`	string	`"Wireless Headphones"`	Product title
`description`	string	`"Noise-cancelling wireless headphones"`	Product description
`published`	boolean	`true`	Published status
`requires_shipping`	boolean	`true`	Shipping requirement
`taxable`	boolean	`true`	Taxable status
`tags`	array of strings	`["audio", "wireless"]`	Product tags
`vendor`	string	`"Sony"`	Vendor name
`vendor_url`	string	`"https://sony.com"`	Vendor URL
`note`	string	`"Limited edition"`	Internal note
`seo_title`	string	`"Premium Headphones"`	SEO title
`seo_description`	string	`"Buy best wireless headphones"`	SEO description
`seo_keywords`	array of strings	`["headphones", "audio"]`	SEO keywords
`handle`	string	`"wireless-headphones"`	Product handle
`has_only_default_variant`	boolean	`false`	Single variant flag
`inventory_tracking`	boolean	`true`	Inventory tracking
`inventory_policy`	string	`"deny"`	Inventory policy
`need_variant_image`	boolean	`true`	Variant image requirement
`spu`	string	`"SPU123"`	Standard product unit
`fake_sales`	string	`"100"`	Display sales count
`display_fake_sales`	boolean	`true`	Show fake sales
`options`	array of objects	-	Product options
`options.id`	string	`"opt_123"`	Option ID
`options.name`	string	`"Color"`	Option name
`options.values`	array of strings	`["Black", "White"]`	Option values
`options.position`	string	`"1"`	Option position
`images`	array of objects	-	Product images
`images.id`	string	`"img_123"`	Image ID
`images.src`	string	`"https://example. com/image.jpg"`	Image URL
`images.width`	int32	`800`	Image width
`images.height`	int32	`600`	Image height
`images.alt`	string	`"Black headphones"`	Image alt text
`images.position`	string	`"1"`	Image position
`images.path`	string	`"/images/headphones"`	Image path
`variants`	array of objects	-	Product variants
`variants.id`	string	`"var_123"`	Variant ID
`variants.product_id`	string	`"prod_123"`	Parent product ID
`variants.image_id`	string	`"img_123"`	Variant image ID
`variants.created_at`	string	`"2025-01-01T00:00:00Z"`	Creation time
`variants.updated_at`	string	`"2025-06-01T00:00:00Z"`	Update time
`variants.title`	string	`"Black"`	Variant title
`variants.option1`	string	`"Black"`	Option 1 value
`variants.option2`	string	`"Large"`	Option 2 value
`variants.option3`	string	`""`	Option 3 value
`variants.image`	object	-	Variant image
`variants.image.position`	string	`"1"`	Image position
`variants.compare_at_price`	float	`199.99`	Compare at price
`variants.price`	float	`149.99`	Current price
`variants.sku`	string	`"SKU123BLK"`	Stock keeping unit
`variants.barcode`	string	`"123456789"`	Barcode
`variants.note`	string	`"New stock"`	Variant note
`variants. inventory_quantity`	string	`"50"`	Inventory count
`variants.weight`	float	`0.5`	Product weight
`variants.weight_unit`	string	`"kg"`	Weight unit
`variants.cost_price`	float	`89.99`	Cost price
`variants.whole_prices`	array of objects	-	Wholesale prices
`variants. whole_prices.price`	float	`129.99`	Wholesale price
`variants.whole_prices. min_quantity`	string	`"10"`	Minimum quantity
`variants. retail_price`	float	`149.99`	Retail price
`variants. is_discount`	boolean	`false`	Discount status
`variants. origin_price`	float	`149.99`	Original price
`variants. extend`	object	-	Extended properties
`variants. extend.length`	float	`20.5`	Product length
`variants. extend.width`	float	`15.0`	Product width
`variants. extend.height`	float	`5.0`	Product height
`variants.extend. dimension_unit`	string	`"cm"`	Dimension unit
`variants.extend. origin_country_code`	string	`"CN"`	Country of origin
`variants.extend. hs_code`	string	`"8518.29"`	HS code
`variants.extend. mixed_wholesale`	boolean	`false`	Mixed wholesale
`product_type`	string	`"electronics"`	Product type
`brand`	string	`"Sony"`	Product brand
`brief`	string	`"Premium audio"`	Brief description
`inventory_quantity`	string	`"150"`	Total inventory
`price_min`	float	`149.99`	Minimum price
`price_max`	float	`199.99`	Maximum price
`compare_at_price_min`	float	`199.99`	Minimum compare price
`compare_at_price_max`	float	`249.99`	Maximum compare price
`published_at`	string	`"2025-05-15T00:00:00Z"`	Publish date
`created_at`	string	`"2025-01-01T00:00:00Z"`	Creation date
`updated_at`	string	`"2025-06-01T00:00:00Z"`	Update date
`sales`	string	`"75"`	Actual sales count
`independent_seo`	boolean	`true`	Custom SEO flag
`url`	string	`"/products/wireless-headphones"`	Product URL
`available`	boolean	`true`	Availability status
`retail_price_min`	float	`149.99`	Minimum retail price
`retail_price_max`	float	`199.99`	Maximum retail price
`origin_price_min`	float	`149.99`	Minimum original price
`origin_price_max`	float	`199.99`	Maximum original price
`primary_image`	object	-	Primary image
`primary_image.src`	string	`"https://example. com/primary.jpg"`	Image URL
`primary_image.width`	int32	`800`	Image width
`primary_image.height`	int32	`600`	Image height
`primary_image.alt`	string	`"Primary product image"`	Alt text
`primary_image.path`	string	`"/images/primary"`	Image path
`tax_code`	string	`"TAX123"`	Tax code
`category_id`	string	`"cat_123"`	Category ID
`category`	object	-	Category details
`category.id`	string	`"cat_123"`	Category ID
`category.name`	string	`"Electronics"`	Category name
`category.google_id`	string	`"12345"`	Google category ID
`category.level`	int32	`2`	Category level
`category.path`	string	`"Electronics/Audio"`	Category path

Error Response

Field	Type	Example	Description
`code`	string	`InvalidParameter`	Error http message
`message`	string	``	Error message

Requires read_product access scope. For more access scope

Request Parameters

Public Request Parameters

Public Request Parameters

Query Parameters

Response Explanation

Public Response Parameters

Public Response Parameters

Successful Response

Product Object

Error Response

Requires `read_product` access scope. For more access scope