Skip to content

List products for pickers

GET
/stores/{storeRef}/products/list
curl --request GET \
--url 'https://apibase.ecomweb.app/api/v1/stores/example/products/list?store_id=1&ids=1&ids=2&ids=3&limit=20&offset=0&search=cotton%20shirt&keyword=cotton%20shirt&status=draft&inventory_status=in_stock&collection_id=12&sort_by=id&sort_order=asc&include_counts=true&include_variants=false&include_combinations=false&include_promotion=false&min_price=10&max_price=100&external_id_pattern=tiktok_%25&filters=%5B%7B%22field%22%3A%22status%22%2C%22operator%22%3A%22is_not%22%2C%22values%22%3A%5B%22draft%22%5D%7D%5D' \
--header 'x-api-key: <x-api-key>'

Returns a compact array of products (ID, name, price and first image URL) for selection controls. The price field is currently always 0; read prices from the full product list or a single product instead. It takes the same filters as the full list and returns the first 100 products when no limit is given. The filters parameter is a JSON array of clauses, each {"field", "operator", "values"}, with at most 10 clauses and 50 values per clause. Fields: status (is, is_not; draft, active or unlisted), category and product_type (is, is_not), tag and collection (is, is_not; numeric IDs), sales_channel (is; numeric IDs), inventory_status (is; in_stock, low_stock or out_of_stock) and price (gte, lte; an amount). sort_by accepts id, name, status, created_at, updated_at, min_price and max_price.

Required scopes: read:products

storeRef
required
string

The store’s ref, as returned by GET /stores.

store_id
number
>= 1

Example

1

Filter by store ID (required for store-specific queries)

ids
Array<number>

Example

[
1,
2,
3
]

Filter by multiple product IDs

limit
number
default: 20 >= 1 <= 10000

Example

20

Number of items per page

offset
number
0

Example

0

Number of items to skip

search
string

Example

cotton shirt

Free-text search over product name or description

keyword
deprecated
string

Example

cotton shirt

Deprecated alias for search, kept so existing callers keep working. search wins when both are sent. New callers should send search.

status
string
Allowed values: draft active unlisted

Example

active

Filter by product status

inventory_status
string
Allowed values: in_stock low_stock out_of_stock

Example

low_stock

Filter by inventory status (in_stock, low_stock, out_of_stock)

collection_id
number
>= 1

Example

12

Only products in this manual collection. A smart collection is refused (400): its products are chosen by its rules.

sort_by
string
default: created_at
Allowed values: id name status created_at updated_at min_price max_price

Example

created_at

Sort field. Any other value is rejected with a 400 error.

sort_order
string
default: desc
Allowed values: asc desc

Example

desc

Sort order

include_counts
boolean
default: true

Example

true

Include related counts (variants, inventory)

include_variants
boolean

Example

false

Include product variants in the response

include_combinations
boolean

Example

false

Include variant combinations (options and values) in the response

include_promotion
boolean

Example

false

Include promotion information in the response

min_price
number

Example

10

Filter by minimum price

max_price
number

Example

100

Filter by maximum price

external_id_pattern
string

Example

tiktok_%

Filter by external ID pattern (for bulk imports)

filters
string

Example

[{"field":"status","operator":"is_not","values":["draft"]}]

A JSON array of filter clauses, each {field, operator, values}. At most 10 clauses, at most 50 values each. Fields: status (is, is_not; draft, active, unlisted), category and product_type (is, is_not), tag and collection (is, is_not; numeric IDs), sales_channel (is; numeric IDs), inventory_status (is; in_stock, low_stock, out_of_stock) and price (gte, lte; an amount).

Media typeapplication/json
Array<object>
object
id
required

Product ID.

number
name
required

Product name.

string
price
required

Currently always 0; use the product’s variant prices or min_price instead.

number
image_url
required

URL of the first product image, or null when there is none.

string
nullable

Example generated

[
{
"id": 1,
"name": "example",
"price": 1,
"image_url": "example"
}
]

The request is malformed or failed validation.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key is missing, invalid, revoked or expired.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key may not do this: a missing scope, a readonly key, a publishable key on a Store API route, or a disallowed origin.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}