Skip to content

List attributes

GET
/stores/{storeRef}/attributes
curl --request GET \
--url 'https://apibase.ecomweb.app/api/v1/stores/example/attributes?type=select&filters=%5B%7B%22field%22%3A%22value_count%22%2C%22operator%22%3A%22lte%22%2C%22values%22%3A%5B%220%22%5D%7D%5D&sort_order=asc&limit=20&offset=0' \
--header 'x-api-key: <x-api-key>'

Returns a page of the store’s attributes in their saved order, each with its number of values. Use limit and offset to page, search to match names, type to filter by type and include_values to add each attribute’s values. 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; select, text or visual) and value_count (gte, lte; a number). sort_by accepts name, type, created_at, updated_at and value_count.

Required scopes: read:products

storeRef
required
string

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

include_values
boolean

Include each attribute’s values

search
string

Case-insensitive search on name

type
string
Allowed values: select text visual

Filter by attribute type

filters
string

Example

[{"field":"value_count","operator":"lte","values":["0"]}]

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

sort_by
string

Sort field

sort_order
string
Allowed values: asc desc
limit
number
default: 20 >= 1 <= 10000
offset
number
0
Media typeapplication/json
object
data
required
Array<object>
object
attribute_values

The attribute’s values, in display order. Present when fetching one attribute or when include_values is true.

Array<object>
object
id
required

Attribute value ID.

number
attribute_id
required

ID of the attribute this value belongs to.

number
value
required

Stored value, such as “red”.

string
display_value
required

Value as shown to shoppers, such as “Red”.

string
swatch_type
required

Swatch kind: none, color or image.

string
swatch_value
required

Swatch content: a color code or an image URL. Empty when there is no swatch.

string
sort_order
required

Position of the value within its attribute.

number
nullable
created_at
required

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

string
updated_at
required

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

string
taxonomy_value_code
required

Code of the global taxonomy value this one maps to, or null.

string
nullable
value_count
required

Number of values the attribute has.

number
id
required

Attribute ID.

number
name
required

Attribute name, such as “Color”.

string
slug
required

URL-safe identifier of the attribute, unique within the store.

string
type
required

How values are chosen, such as select.

string
order_by
required

How the values are ordered, such as manual.

string
sort_order
required

Position of the attribute among the store’s attributes.

number
nullable
created_at
required

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

string
updated_at
required

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

string
taxonomy_attribute_code
required

Code of the global taxonomy attribute this one maps to, or null for a local attribute.

string
nullable
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 generated

{
"data": [
{
"attribute_values": [
{
"id": 1,
"attribute_id": 1,
"value": "example",
"display_value": "example",
"swatch_type": "example",
"swatch_value": "example",
"sort_order": 1,
"created_at": "example",
"updated_at": "example",
"taxonomy_value_code": "example"
}
],
"value_count": 1,
"id": 1,
"name": "example",
"slug": "example",
"type": "example",
"order_by": "example",
"sort_order": 1,
"created_at": "example",
"updated_at": "example",
"taxonomy_attribute_code": "example"
}
],
"meta": {
"total": 1,
"limit": 1,
"offset": 1,
"page": 1,
"totalPages": 1,
"hasNext": true,
"hasPrev": true
}
}

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