Product List

get https://{shopdomain}.myshoplaza.com/openapi/2022-01/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

Body Parameters

Parameter	Type	Required	Example	Description
`ids`	`string`	No	9e79ca1f-9ff2-409b-976f-98be343d38a3	Product IDs, separated by commas. Use this to filter by specific product IDs.
`title`	`string`	No	"Stylish Shirt"	Filter products by their title. Allows partial matching.
`collection_id`	`string`	No	9e79ca1f-9ff2-409b-976f-98be343d38a3	The Collection ID uniquely identifies a group of products within a collection.
`created_at_min`	`string`	No	2018-10-01T16:15:47-04:00	Filter products created at or after the specified date (ISO 8601 format).
`created_at_max`	`string`	No	2018-10-01T16:15:47-04:00	Filter products created at or before the specified date (ISO 8601 format).
`updated_at_min`	`string`	No	2018-10-01T16:15:47-04:00	Filter products updated at or after the specified date (ISO 8601 format).
`updated_at_max`	`string`	No	2018-10-01T16:15:47-04:00	Filter products updated at or before the specified date (ISO 8601 format).
`published_at_min`	`string`	No	2018-10-01T16:15:47-04:00	Filter products published at or after the specified date (ISO 8601 format).
`published_at_max`	`string`	No	2018-10-01T16:15:47-04:00	Filter products published at or before the specified date (ISO 8601 format).
`published_status`	`string`	No	"published" or "unpublished"	Filter products by their publication status. Options: `published`, `unpublished`, or `any`.
`spus`	`string`	No	"spu1,spu2"	Product SPUs, separated by commas. Use this to filter by specific SPUs.
`cursor`	`string`	No	"c1d5b2a3-fab1-4e26-8582-75d3b2677042"	Cursor for pagination. Use this parameter to fetch the next set of results.
`pre_cursor`	`string`	No	"c1d5b2a3-fab1-4e26-8582-75d3b2677042"	Cursor for pagination. Use this parameter to fetch the previous set of results.
`per_page`	`int32`	No	50	Number of results per page. Maximum value: `250`.
`fields`	`string`	No	"title,id"	Comma-separated list of fields to include in the response. Reduces response size by excluding unnecessary fields.
`vendors`	`string`	No	"vendor1,vendor2"	Filter products by exact vendor names. Multiple vendor names should be separated by commas.
`vendors_match`	`string`	No	"ab"	Filter products by vendors using prefix matching. For example, if vendor is `"abcd"`, `"a"`, `"ab"`, `"abc"` will match, but `"bc"` will not.

Response Explanation

Public Response Parameters

📘
Public Response Parameters

Successful Response

Field	Type	Example	Description
`cursor`	`string`	MjAyNC0wNC0xN1QwMjoxNToxOFojYTFhOD hiZTAtYTFkNC0 0N2U0LWEyZjItYmE2 ZTEzMWNmNDQ3	Cursor for the next page of results.
`pre_cursor`	`string`	MjAyNC0wNC0xN1QwMjoxNToxOFojYTFhOD hiZTAtYTFkNC0 0N2U0LWEyZjItYmE2 ZTEzMWNmNDQ3	Cursor for the previous page of results.
`products`	`array`	Array of product object	List of products matching the query.
`product.id`	`string`	`"9fb9f3c6-2300-42c1-8593-d9008d7cfc09"`	Unique identifier for the product.
`product.title`	`string`	`"Stylish Shirt"`	Title of the product.
`product.brief`	`string`	`"A stylish shirt."`	Brief description or summary of the product.
`product. description`	`string`	`""`	Full description of the product.
`product. published`	`boolean`	`true`	Indicates whether the product is published.
`product. requires_shipping`	`boolean`	`true`	Indicates if the product requires shipping.
`product. taxable`	`boolean`	`true`	Indicates if the product is subject to tax.
`product.tags`	`string`	`"shirt,stylish,cotton"`	Tags associated with the product, separated by commas.
`product.vendor`	`string`	`"Awesome Vendor"`	Name of the product vendor.
`product.vendor_url`	`string`	`"https://awesomevendor.com"`	URL of the vendor's website.
`product. inventory_quantity`	`integer`	`300`	Total inventory available for the product.
`product. published_at`	`string (ISO8601)`	`"2024-12-03T19:02:30Z"`	Timestamp when the product was published.
`product. created_at`	`string (ISO8601)`	`"2024-12-03T19:02:30Z"`	Timestamp when the product was created.
`product. updated_at`	`string (ISO8601)`	`"2024-12-03T19:02:30Z"`	Timestamp when the product was last updated.
`product.note`	`string`	`"Special promotion item."`	Notes or special remarks about the product.
`product. seo_title`	`string`	`"Buy Stylish Shirt Online"`	SEO-friendly title for the product.
`product. seo_description`	`string`	`"Premium cotton"`	SEO-friendly description for the product.
`product. seo_keywords`	`string`	`"shirt, cotton, stylish"`	SEO keywords for the product, separated by commas.
`product.handle`	`string`	`"stylish-shirt-zbxf"`	URL-friendly handle for the product.
`product. has_only_default_variant`	`boolean`	`false`	Indicates if the product has only the default variant.
`product. image.src`	`string`	`"//img.fantaskycdn.com/loading.png"`	Source URL of the product's main image.
`product. image.width`	`integer`	`100`	Width of the product's main image in pixels.
`product. image.height`	`integer`	`100`	Height of the product's main image in pixels.
`product. image.path`	`string`	`"loading.png"`	File path of the product's main image.
`product. image.alt`	`string`	`""`	Alternative text for the product's main image.
`product.images`	array of image object	See `images` fields below	Array of additional images for the product.
`product.images[].id`	`string`	`"15333433-a0d5-44c9-941b-2c59ea07683e"`	Unique identifier for the image.
`product.images[]. product_id`	`string`	`"9fb9f3c6-2300-42c1-8593-d9008d7cfc09"`	ID of the product associated with the image.
`product.images[]. position`	`integer`	`1`	Position of the image in the gallery.
`product.images[]. src`	`string`	`"//img.fantaskycdn.com/loading.png"`	Source URL of the image.
`product. variants[].id`	`string`	`"d7c7f9ba-f824-46b6-94af-1c2d1befaf27"`	Unique identifier for the variant.
`product. variants[].title`	`string`	`"Small-Red"`	Title of the variant.
`product. variants[].option1`	`string`	`"Small"`	Value of the first option for the variant.
`product. variants[].option2`	`string`	`"Red"`	Value of the second option for the variant.
`product. variants[].price`	`string`	`"19.99"`	Price of the variant.
`product. variants[].sku`	`string`	`"SS1234-RD-S"`	Stock Keeping Unit (SKU) for the variant.
`product. variants[].inventory_quantity`	`integer`	`100`	Inventory quantity for the variant.
`product. variants[].wholesale_price`	array of wholesale price	See `wholesale_price` fields below	Wholesale price information for the variant.
`product. variants[]. wholesale_price[].price`	`string`	`"19.99"`	Wholesale price for the variant.
`product.variants[]. wholesale_price[]. min_quantity`	`integer`	`1`	Minimum quantity for the wholesale price.
`product.category`	`Object`	Category object	Category information for the product.
`product.category.id`	`integer`	368313940138040900	The ID of the category.
`product. category.name`	`string`	"3"	Category name.
`product. category.google_id`	`integer`	0	Google category ID.
`product. category.level`	`integer`	"3"	Level of category.
`product. category.path`	`string`	"368313940138008142, 368313940138024526, 368313940138040910"	The full path of a category, consisting of category IDs.

Error Response

Error responses in the API can be represented using two different fields: errors and error. Both fields provide details about issues encountered during request processing. Below is an explanation of the fields with their respective examples and descriptions.

Field	Type	Example	Description
`errors`	Array	`["Context"]`	A list of errors encountered during the request processing.

Field	Type	Example	Description
`error`	String	`"store is not active"`	Indicates an error encountered during the process.

Error Details

Status Code	Message	Possible Reason	Example Response
422	`failed verification: the published status is invalid`	The `published_status` provided is not one of the allowed values.	`{"errors": ["failed verification: the published status is invalid"]}`
	`created_at_min time format error`	The `created_at_min` field is not in a valid time format.(e.g., not ISO8601).	`{"errors": [" created_at_min time format error""]}`
	`created_at_max time format error`	The `updated_at_max` field is not in a valid time format.(e.g., not ISO8601).	`{"errors": ["created_at_max time format error"]}`
	`published_at_max time format error`	The `published_at_max` field is not in a valid time format.(e.g., not ISO8601).	`{"errors": ["published_at_max time format error"]}`
	`published_at_min time format error`	The `published_at_min` field is not in a valid time format.(e.g., not ISO8601).	`{"errors": ["published_at_min time format error"]}`
	`update_at_min time format error`	The `update_at_min` field is not in a valid time format.(e.g., not ISO8601).	`{"errors": ["update_at_min time format error"]}`
	`update_at_max time format error`	The `update_at_max` field is not in a valid time format.(e.g., not ISO8601).	`{"errors": ["update_at_min time format error"]}`
		Invalid `cursor` or `pre_cursor` type
500	`no_context`	Missing Context	`{"errors": ["No context"]}`

Product List

🔒
Requires `read_product` access scope. For more access scope

Request Parameters

Public Request Parameters

📘
Public Request Parameters

Body Parameters

Response Explanation

Public Response Parameters

📘
Public Response Parameters

Successful Response

Error Response

Error Details

🔒Requires read_product access scope. For more access scope

Request Parameters

Public Request Parameters

📘Public Request Parameters

Body Parameters

Response Explanation

Public Response Parameters

📘Public Response Parameters

Successful Response

Error Response

Error Details

🔒
Requires `read_product` access scope. For more access scope

📘
Public Request Parameters

📘
Public Response Parameters