Skip to content

List collections

GET
/stores/{storeRef}/collections
curl --request GET \
--url 'https://apibase.ecomweb.app/api/v1/stores/example/collections?ids=1%2C2%2C3&type=manual&status=draft&search=summer&name=Summer%20Collection&slug=summer-collection&sort_by=name&sort_order=asc&limit=10&offset=0&include_product_count=false&include_seo_metadata=false&filters=%5B%7B%22field%22%3A%22type%22%2C%22operator%22%3A%22is%22%2C%22values%22%3A%5B%22smart%22%5D%7D%5D' \
--header 'x-api-key: <x-api-key>'

Returns a page of the store’s collections, ordered by name by default. Use limit (10 by default) and offset to page, search to match names and descriptions, and type, status, slug or ids to narrow the list. The filters parameter is a JSON array of clauses, each {"field", "operator", "values"}, with at most 10 clauses and 50 values per clause. Fields: type (is, is_not; manual or smart) and status (is, is_not; draft, active, archived or unlisted). sort_by accepts name, status, type, created_at, updated_at and id.

Required scopes: read:categories

storeRef
required
string

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

ids
string

Example

1,2,3

Filter by specific collection IDs (comma-separated)

type
string
Allowed values: manual smart

Filter by collection type

status
string
Allowed values: draft active archived unlisted

Filter by collection status

search
string

Example

summer

Search collections by name or description

name
string

Example

Summer Collection

Filter by collection name

slug
string

Example

summer-collection

Filter by slug

sort_by
string

Example

name

Sort field

sort_order
string
default: asc
Allowed values: asc desc

Sort order

limit
number
default: 10 >= 1

Example

10

Number of items per page

offset
number
0

Example

0

Number of items to skip

include_product_count
boolean

Example

true

Include product count in the response for each collection

include_seo_metadata
boolean

Example

true

Include SEO metadata in the response

filters
string

Example

[{"field":"type","operator":"is","values":["smart"]}]

A JSON array of {field, operator, values} clauses, with at most 10 clauses and 50 values each. Fields: type (is, is_not) and status (is, is_not).

Media typeapplication/json
object
data
required
Array<object>
object
type
required

manual collections list products you choose; smart collections select products with search_criteria.

string
Allowed values: manual smart
status
required

Publication status.

string
Allowed values: draft active archived unlisted
search_criteria
required

The rules a smart collection selects products with, or null for a manual collection.

object
key
additional properties
any
facet_config
required

The facets shoppers can filter the collection by, computed by the store, or null when not yet computed.

object
key
additional properties
any
collection_sort
required

How products are ordered within the collection.

string
Allowed values: manual product_name_asc product_name_desc best_selling highest_price lowest_price newest oldest
product_ids

Product IDs of a manual collection, in display order. Not present on smart collections.

Array<number>
seo_metadata

SEO fields. Present only when include_seo_metadata is true.

object
meta_title
required

Page title for search engines, or null.

string
nullable
meta_description
required

Page description for search engines, or null.

string
nullable
id
required

Collection ID.

number
name
required

Collection name.

string
description
required

Collection description, or null.

string
nullable
image_url
required

URL of the collection image, or null.

string
nullable
slug
required

URL-friendly identifier, unique within the store.

string
generated_from_category_id
required

ID of the category this collection was generated from, or null for a collection created by hand.

number
nullable
created_at
required

When the collection was created, as an ISO 8601 timestamp.

string
updated_at
required

When the collection was last updated, as an ISO 8601 timestamp.

string
deleted_at
required

Always null; deleted collections are not returned.

string
nullable
product_count

Number of products in the collection. Present only when include_product_count is true.

number
meta
required
object
total
required

Total number of items matching the request.

number
limit
required

Maximum number of items in this page.

number
offset
required

Number of items skipped before this page.

number
page
required

Current page number, starting at 1.

number
totalPages
required

Total number of pages.

number
hasNext
required

Whether a next page exists.

boolean
hasPrev
required

Whether a previous page exists.

boolean

Example

{
"data": [
{
"type": "manual",
"status": "draft",
"collection_sort": "manual"
}
]
}

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"
}