attribute sets v2.md

Attribute Sets v2

Get Attribute Sets

GET /v2/AttributeSets: Returns all attribute sets defined for the tenant, each including its name, identifier, and form layout configuration for Products and Variants (ProductLayout, VariantLayout).

See also: A legacy OData-style version of this endpoint is available at GET /AttributeSets.

Authentication

Requires a valid API key in the X-API-KEY header.

Response

200 OK — GetAttributeSetsResponse containing the list of attribute sets.

Error Responses

401 Unauthorized — Missing or invalid tenant identifier.
500 Internal Server Error — Unexpected technical error.

Example

Request: http GET /v2/AttributeSets HTTP/1.1 X-API-KEY: your-api-key-here

Response: http HTTP/1.1 200 OK Content-Type: application/json

Create Attribute Set

POST /v2/AttributeSets: Creates a new attribute set for the tenant from the supplied name and optional Product and Variant form layouts, returning the created attribute set and a Location header pointing to it.

The Product and Variant layouts behave differently when omitted: an omitted productLayout falls back to a standard default layout, whereas an omitted variantLayout is not created at all (no Variant layout is stored). A Variant layout can be added later with PATCH /v2/AttributeSets({id}).

Authentication

Requires a valid API key in the X-API-KEY header.

Request Body

Field	Required	Description
name	✅ Yes	Unique name for the attribute set within the tenant.
productLayout	❌ No	Form layout for Products. Defaults to the standard layout when omitted.
variantLayout	❌ No	Form layout for Variants. When omitted, no Variant layout is created (it can be added later via PATCH).

Layout Structure

Each layout is a JSON document with a sections array. Each section has a title and a rows array. Each row has a fields array and an optional divider (dividerType, dividerTitle). Each field carries an attributeId and a size.

{
  "sections": [
    {
      "title": "General",
      "rows": [
        {
          "fields": [
            { "attributeId": "prod_title", "size": "half" },
            { "attributeId": "prod_ref",   "size": "half" }
          ]
        },
        {
          "dividerType": "normal",
          "dividerTitle": "Details",
          "fields": [
            { "attributeId": "prod_description", "size": "row" }
          ]
        }
      ]
    }
  ]
}

size — width of the field in the form grid. One of: quarter, half, threeQuarters, row. dividerType — optional visual separator above the row. One of: normal, wide, lineBreak. dividerTitle is optional and only meaningful when dividerType is set. Both properties are omitted from rows that have no divider.

Layout Validation

A layout may contain any subset of the tenant's valid attributes — you do not need to include all of them. Attributes omitted from the layout simply do not appear in the form for this attribute set; they are not removed from the tenant.

If a layout is supplied it must satisfy all of the following rules; otherwise the request returns 400 Bad Request describing each failure:

The layout must be well-formed: the sections, rows and fields arrays must all be present (non-null). Omitting a sections, rows or fields array (or sending it as null) is rejected.
Every attributeId included must exist for the entity type (Products or Variants) in the tenant's storage definition.
No attributeId may appear more than once across the entire layout.
Each field size must be one of: quarter, half, threeQuarters, row.
The sum of field sizes within any single row must not exceed a full row.
Every row must contain at least one field.
Section title values must be unique (case-insensitive).
When a row sets dividerType it must be one of: normal, wide, lineBreak.

Required attributes

These attributes must always be present in their respective layout:

Layout	Required attribute IDs
productLayout	typ_id, prod_ref, prod_title, cat_ref, prod_stat, prod_description, prod_image, prod_tags
variantLayout	frmt_stat, prod_ref, frmt_ref, frmt_tags

Response

201 Created — The Location header points to the new resource: /v2/AttributeSets({id}). The response body contains the created attribute set (CreateAttributeSet2Response).

Error Responses

400 Bad Request — Missing body, missing name, duplicate name, or layout validation failure.
401 Unauthorized — Missing or invalid tenant identifier.
500 Internal Server Error — Unexpected technical error.

Example

Request: http POST /v2/AttributeSets HTTP/1.1 X-API-KEY: your-api-key-here Content-Type: application/json

{ "name": "Electronics" }

Response: http HTTP/1.1 201 Created Location: /v2/AttributeSets(7)

Get Attribute Set

GET /v2/AttributeSets({id}): Returns a single attribute set identified by id. Accepted values:
default (case-insensitive) — retrieves the tenant's default attribute set.
Positive integer — retrieves the attribute set with that numeric ID.

Any other value is rejected with 400 Bad Request.

The response includes the attribute set name and its form layout configuration for Products and Variants (ProductLayout, VariantLayout). When the set has no Variant layout configured, VariantLayout and VariantAttributeIds are omitted from the response.

See also: A legacy OData-style version of this endpoint is available at GET /AttributeSets({attributeSetIdentifier}).

Authentication

Requires a valid API key in the X-API-KEY header.

Response

200 OK — The requested attribute set with its layout configuration.

Error Responses

400 Bad Request — id is not default or a valid positive integer.
401 Unauthorized — Missing or invalid tenant identifier.
404 Not Found — No attribute set with the given identifier exists for this tenant.
500 Internal Server Error — Unexpected technical error.

Example

Request: http GET /v2/AttributeSets(1) HTTP/1.1 X-API-KEY: your-api-key-here

Response: http HTTP/1.1 200 OK Content-Type: application/json

Update Attribute Set

PATCH /v2/AttributeSets({id}): Partially updates an existing attribute set identified by id. Accepted values:
default (case-insensitive) — updates the tenant's default attribute set.
Positive integer — updates the attribute set with that numeric ID.

Any other value is rejected with 400 Bad Request.

Authentication

Requires a valid API key in the X-API-KEY header.

Request Body

All fields are optional. Omitted (null) fields are left unchanged (PATCH semantics). When a layout is supplied it fully replaces the currently stored layout — it is not merged.

Field	Description
name	New unique name for the attribute set.
productLayout	Replacement form layout for Products.
variantLayout	Form layout for Variants. Sets the Variant layout when the set does not yet have one (e.g. created without it), or replaces it when it does.

Layout Structure

Layout Validation

If a layout is supplied it must satisfy all of the following rules; otherwise the request returns 400 Bad Request describing each failure:

Required attributes

These attributes must always be present in their respective layout:

Response

200 OK — The updated attribute set (UpdateAttributeSet2Response).

Error Responses

400 Bad Request — Invalid id, missing body, or layout validation failure.
401 Unauthorized — Missing or invalid tenant identifier.
404 Not Found — No attribute set with the given identifier exists for this tenant.
500 Internal Server Error — Unexpected technical error.

Example

Request: http PATCH /v2/AttributeSets(1) HTTP/1.1 X-API-KEY: your-api-key-here Content-Type: application/json

{ "name": "Electronics v2" }

Response: http HTTP/1.1 200 OK Content-Type: application/json

Delete Attribute Set

DELETE /v2/AttributeSets({id}): Deletes the attribute set identified by id (a positive integer). The tenant's default attribute set cannot be deleted.

Authentication

Requires a valid API key in the X-API-KEY header.

Query Parameters

Parameter	Required	Description
deleteAssociatedProductsAndVariants	❌ No	When true, products and variants associated to the attribute set are deleted along with it. When false or omitted, those products and variants are reassigned to the tenant's default attribute set.

Response

200 OK — Attribute set deleted; the response body (DeleteAttributeSet2Response) summarises the operation.
204 No Content — Nothing to delete (idempotent success).

Error Responses

400 Bad Request — id is not a positive integer or the request is otherwise invalid (ValidationFailureRepresentation).
401 Unauthorized — Missing or invalid tenant identifier.
404 Not Found — No attribute set with the given identifier exists for this tenant.
500 Internal Server Error — Unexpected technical error.

Example

Request: http DELETE /v2/AttributeSets(7)?deleteAssociatedProductsAndVariants=false HTTP/1.1 X-API-KEY: your-api-key-here

Response: http HTTP/1.1 200 OK Content-Type: application/json