Skip to content

Replace a product's attribute links

PUT
/stores/{storeRef}/products/{productId}/attributes
curl --request PUT \
--url https://apibase.ecomweb.app/api/v1/stores/example/products/1/attributes \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--data '{ "attributes": [ { "attribute_id": 12, "value_ids": [ 3, 4 ], "position": 0, "is_visible": true, "is_variation": true }, { "custom_name": "Material", "custom_values": [ "Cotton" ], "position": 1, "is_visible": true, "is_variation": false } ] }'

Replaces the product’s whole set of attribute links with the list you send, in one step, and returns the new set. Each link carries exactly one of attribute_id or custom_name, and only library attributes can drive variants. Dropping an attribute or a value that existing variants use is refused with a 409 error.

Required scopes: write:products

productId
required
integer

The product ID.

storeRef
required
string

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

Media typeapplication/json
object
attributes
required

Full set of attribute links for the product. Replaces all existing links.

Array<object>
object
attribute_id

Library attribute id. Mutually exclusive with custom_name — exactly one must be set.

number

Example

12
custom_name

Local (non-library) attribute name. Mutually exclusive with attribute_id.

string
<= 255 characters

Example

Material
value_ids

Selected attribute_values ids, for a library attribute_id

Array<number>

Example

[
3,
4
]
custom_values

Local values, for a custom_name link

Array<string>

Example

[
"Cotton"
]
position

Display order

number

Example

0
group

Optional group label for organizing attributes

string
nullable <= 255 characters

Example

Specifications
is_visible

Whether this attribute is shown on the storefront

boolean
default: true
is_variation

Whether this attribute drives variant generation

boolean

Example

[
{
"attribute_id": 12,
"value_ids": [
3,
4
],
"position": 0,
"is_visible": true,
"is_variation": true
},
{
"custom_name": "Material",
"custom_values": [
"Cotton"
],
"position": 1,
"is_visible": true,
"is_variation": false
}
]
Media typeapplication/json
Array<object>
object
values
required

The values the product uses for this attribute.

Array<object>
object
key
required

Stable key of the value within the link.

string
display
required

Value as shown to shoppers.

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
attribute_value_id
required

ID of the library value, or null for a local value.

number
nullable
taxonomy_value_code
required

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

string
nullable
id
required

Link ID. Use it to remove the link.

number
position
required

Display position of the attribute on the product.

number
group
required

Group label the attribute is shown under, or null.

string
nullable
is_visible
required

Whether the attribute is shown on the storefront.

boolean
is_variation
required

Whether the attribute drives the product’s variants.

boolean
attribute_id
required

ID of the library attribute, or null for a local attribute.

number
nullable
custom_name
required

Name of the local attribute, or null for a library attribute.

string
nullable
name
required

The attribute’s name, whether library or local.

string
taxonomy_attribute_code
required

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

string
nullable

Example generated

[
{
"values": [
{
"key": "example",
"display": "example",
"swatch_type": "example",
"swatch_value": "example",
"attribute_value_id": 1,
"taxonomy_value_code": "example"
}
],
"id": 1,
"position": 1,
"group": "example",
"is_visible": true,
"is_variation": true,
"attribute_id": 1,
"custom_name": "example",
"name": "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"
}

The resource does not exist in this store.

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 request conflicts with the resource’s current state.

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