Skip to content

Create an attribute

POST
/stores/{storeRef}/attributes
curl --request POST \
--url https://apibase.ecomweb.app/api/v1/stores/example/attributes \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--data '{ "name": "Color", "slug": "color", "type": "select", "order_by": "manual", "sort_order": 1, "taxonomy_attribute_code": "color", "is_local": false }'

Creates an attribute such as Color or Size. The slug is derived from the name unless you send one. A name or slug that is already used in the store is rejected with a 400 error and the code ATTRIBUTE_SLUG_TAKEN. Add values afterwards with the attribute’s values routes.

Required scopes: write:products

storeRef
required
string

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

Media typeapplication/json
object
name
required

Attribute name

string
<= 255 characters

Example

Color
slug

URL-safe slug; derived from name when omitted

string
<= 255 characters

Example

color
type

Attribute type

string
Allowed values: select text visual

Example

select
order_by

How values are ordered by default

string

Example

manual
sort_order

Sort order among store attributes

number
taxonomy_attribute_code

Global taxonomy attribute code. Required unless is_local is true.

string
<= 100 characters

Example

color
is_local

Deliberately create a store-local attribute with no global code. Logged.

boolean

Example

false
Media typeapplication/json
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
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

Example generated

{
"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"
}
],
"id": 1,
"name": "example",
"slug": "example",
"type": "example",
"order_by": "example",
"sort_order": 1,
"created_at": "example",
"updated_at": "example",
"taxonomy_attribute_code": "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"
}