Admin Product Variations and Attributes API Reference

Variations let shoppers select a specific option (e.g., Color = Red, Size = XL) before adding a product to their cart. The system is built on two lookup tables and one variation table:

Attributes — the type of option (e.g., Color, Size, Material). Each attribute has a type_attribute that governs how its values are rendered and which contexts it can be used in.
Properties — the values belonging to an attribute (e.g., Red, Blue for Color; S, M, L for Size). A code field stores hex color codes for color-type attributes.
Product Variations — link a product to a specific attribute + property combination, with optional stock allocation and price adjustment. Variations can be nested (anidado) to model multi-dimensional options such as Color → Size.

Mutating operations on attributes (store, store_propertie, update, destroy, destroy_propertie) and variations (store, update, destroy) are throttled at 10 requests per minute per token.

Authentication

All /api/admin/ endpoints require:

Authorization: Bearer <admin_token>

See Products — Authentication for obtaining a token.

Attributes

List Attributes

GET /api/admin/attributes

Returns all attributes paginated 25 per page, ordered by id descending. Each attribute includes its full list of properties. Query parameters

string

Filter by attribute name (SQL LIKE %value%).

Response

total

integer

Total matching attributes.

attributes

array

Array of attribute objects (plain array, not wrapped in a data key), each with an embedded properties array.

{
  "total": 5,
  "attributes": [
    {
      "id": 1,
      "name": "Color",
      "type_attribute": 1,
      "state": 1,
      "created_at": "2024-01-10 08:00 AM",
      "properties": [
        { "id": 1, "name": "Red",  "code": "#FF0000" },
        { "id": 2, "name": "Blue", "code": "#0000FF" }
      ]
    }
  ]
}

Create Attribute

POST /api/admin/attributes

Attribute names must be unique. A duplicate name returns {"message": 403}.

Body parameters

name

string

required

Attribute name (e.g., "Color", "Size", "Material"). Must be unique.

state

integer

1 = active, 0 = inactive.

type_attribute

integer

Controls how the attribute is rendered on the storefront and which contexts it can be used in.

Value	Meaning
`1`	Color swatch — property `code` holds a hex color value
`2`	Free-text input — no predefined properties needed
`3`	Select / dropdown from predefined properties

Only attributes with type_attribute 1 (color) or 3 (select) are available for product variations (returned by GET /api/admin/variations/config as attributes_variations). All type_attribute values are available for product specifications.

Response

message

integer

200 on success, 403 on duplicate name.

attribute

object

The created attribute including its (initially empty) properties array.

{
  "message": 200,
  "attribute": {
    "id": 6,
    "name": "Size",
    "type_attribute": 3,
    "state": 1,
    "created_at": "2024-06-01 09:00 AM",
    "properties": []
  }
}

Update Attribute

PUT /api/admin/attributes/{id}

Path parameters

integer

required

Attribute ID to update.

Body parameters — same as Create Attribute. Response

{
  "message": 200,
  "attribute": { "id": 6, "name": "Shoe Size", "type_attribute": 3, "state": 1, "properties": [] }
}

Delete Attribute

DELETE /api/admin/attributes/{id}

An attribute linked to any product specification or variation cannot be deleted. Returns {"message": 403, "message_text": "El atributo no puede ser eliminado porque tiene productos asociados"}.

Path parameters

integer

required

Attribute ID to delete.

Response

{ "message": 200 }

Properties

Properties are the individual values that belong to an attribute (e.g., Red/Blue for Color; S/M/L for Size).

Add Property to Attribute

POST /api/admin/properties

The name must be unique within the same attribute_id. Duplicates return {"message": 403}.

Body parameters

attribute_id

integer

required

The parent attribute ID this property belongs to.

name

string

required

Property display name (e.g., "Red", "XL", "Cotton").

code

string

For color attributes (type_attribute = 1), supply the hex color code (e.g., "#FF5733"). Leave empty for non-color attributes.

Response

message

integer

200 on success, 403 on duplicate name within the same attribute.

propertie

object

The created property record.

{
  "message": 200,
  "propertie": {
    "id": 12,
    "name": "Red",
    "code": "#FF0000",
    "created_at": "2024-06-01 09:05 AM"
  }
}

Delete Property

DELETE /api/admin/properties/{id}

A property linked to an existing specification or variation cannot be deleted. Returns {"message": 403, "message_text": "La propiedad no puede ser eliminada porque tiene productos asociados"}.

Path parameters

integer

required

Property ID to delete.

Response

{ "message": 200 }

Variation Config

Returns the attribute lists for use in variation and specification form dropdowns.

GET /api/admin/variations/config

Response

attributes_specifications

array

All active attributes (any type_attribute value) with their properties. Used to populate specification forms.

attributes_variations

array

Active attributes with type_attribute 1 (color swatch) or 3 (select/dropdown) only. Used to populate variation forms. Free-text (type_attribute = 2) attributes are excluded because variations require selecting from a finite list of predefined properties.

{
  "attributes_specifications": [
    {
      "id": 1, "name": "Color", "type_attribute": 1, "state": 1,
      "created_at": "2024-01-10 08:00:00",
      "properties": [{ "id": 1, "name": "Red", "code": "#FF0000" }]
    },
    {
      "id": 2, "name": "Weight", "type_attribute": 2, "state": 1,
      "created_at": "2024-01-11 08:00:00",
      "properties": []
    }
  ],
  "attributes_variations": [
    {
      "id": 1, "name": "Color", "type_attribute": 1, "state": 1,
      "created_at": "2024-01-10 08:00:00",
      "properties": [{ "id": 1, "name": "Red", "code": "#FF0000" }]
    }
  ]
}

Product Variations (First Level)

List Variations for a Product

GET /api/admin/variations?product_id={id}

Returns all top-level variations (where product_variation_id IS NULL) for the given product, ordered by id descending. Query parameters

product_id

integer

required

The product ID whose variations to retrieve.

Response

variations

array

Array of variation objects. Each includes the resolved attribute and propertie nested objects.

{
  "variations": [
    {
      "id": 5,
      "product_id": 42,
      "attribute_id": 1,
      "attribute": { "name": "Color", "type_attribute": 1 },
      "propertie_id": 1,
      "propertie": { "name": "Red", "code": "#FF0000" },
      "value_add": null,
      "add_price": 0,
      "stock": 50,
      "state": 1
    }
  ]
}

Create Variation

POST /api/admin/variations

All variations on a single product must share the same attribute_id. Adding a variation with a different attribute than existing ones returns {"message": 403, "message_text": "No se puede agregar un atributo diferente en la lista de variaciones"}.

Body parameters

product_id

integer

required

The product this variation belongs to.

attribute_id

integer

required

The attribute type for this variation (e.g., Color attribute ID, Size attribute ID). Must be type_attribute 1 or 3 (color or select) — only those are included in attributes_variations from the config endpoint.

propertie_id

integer

The specific property value (e.g., Red ID, XL ID). Use for type_attribute = 1 (color) and type_attribute = 3 (select). Either propertie_id or value_add should be supplied.

value_add

string

Free-text value for attributes without predefined properties. Either propertie_id or value_add should be supplied.

add_price

number

Price adjustment added on top of the base product price when this variation is selected.

stock

integer

Stock units reserved for this specific variation.

state

integer

1 = active, 0 = inactive.

Response

message

integer

200 on success, 403 on validation error.

variation

object

The newly created variation object with resolved attribute and propertie.

{
  "message": 200,
  "variation": {
    "id": 5,
    "product_id": 42,
    "attribute_id": 1,
    "attribute": { "name": "Color", "type_attribute": 1 },
    "propertie_id": 1,
    "propertie": { "name": "Red", "code": "#FF0000" },
    "value_add": null,
    "add_price": 0,
    "stock": 50,
    "state": 1
  }
}

Update Variation

PUT /api/admin/variations/{id}

Path parameters

integer

required

Variation ID to update.

Body parameters — same as Create Variation. The same attribute-consistency and duplicate-value validations apply. Returns {"message": 403} on conflict. Response

{ "message": 200, "variation": { "id": 5, "..." : "..." } }

Delete Variation

DELETE /api/admin/variations/{id}

Path parameters

integer

required

Variation ID to delete.

Response

{ "message": 200 }

Nested (Anidado) Variations

Nested variations model multi-dimensional option combinations, for example: a parent variation of Color = Red with child variations Size = S, Size = M, Size = L. Endpoints mirror the standard variations resource but operate on rows scoped to a specific product_variation_id (the parent variation).

List Nested Variations

GET /api/admin/anidado_variations?product_id={id}&product_variation_id={parent_id}

Query parameters

product_id

integer

required

The product ID.

product_variation_id

integer

required

The parent (first-level) variation ID whose children to retrieve.

Response

variations

array

Array of nested variation objects, each including a product_variation_id field pointing back to the parent.

{
  "variations": [
    {
      "id": 10,
      "product_id": 42,
      "attribute_id": 6,
      "attribute": { "name": "Size", "type_attribute": 3 },
      "propertie_id": 12,
      "propertie": { "name": "M", "code": null },
      "value_add": null,
      "add_price": 0,
      "stock": 15,
      "state": 1,
      "product_variation_id": 5
    }
  ]
}

Create Nested Variation

POST /api/admin/anidado_variations

The total stock of all nested variations under a parent cannot exceed the parent variation’s stock. Attempts to exceed the limit return

{"message": 403, "message_text": "El stock de las variaciones anidadas no puede ser mayor al stock de la variación central"}

All nested variations under the same parent must share the same attribute_id. Using a different attribute returns {"message": 403, "message_text": "No se puede agregar un atributo diferente en la lista de variaciones"}.

Body parameters

product_id

integer

required

The product ID.

product_variation_id

integer

required

The parent first-level variation ID. This links the nested variation as a child.

attribute_id

integer

required

The attribute for this dimension (e.g., Size attribute ID).

propertie_id

integer

The property value (e.g., Size = M).

value_add

string

Free-text value for attributes without predefined properties.

add_price

number

Additional price adjustment for this specific combination.

stock

integer

Stock units for this combination. The sum of all sibling nested variations’ stock must not exceed the parent’s stock.

state

integer

1 = active, 0 = inactive.

Response

{
  "message": 200,
  "variation": {
    "id": 10,
    "product_id": 42,
    "attribute_id": 6,
    "attribute": { "name": "Size", "type_attribute": 3 },
    "propertie_id": 12,
    "propertie": { "name": "M", "code": null },
    "value_add": null,
    "add_price": 0,
    "stock": 15,
    "state": 1,
    "product_variation_id": 5
  }
}

Update Nested Variation

PUT /api/admin/anidado_variations/{id}

Same body parameters and validation rules as Create Nested Variation. Stock validation excludes the current record when recalculating the sibling sum. Response

{ "message": 200, "variation": { "id": 10, "..." : "..." } }

Delete Nested Variation

DELETE /api/admin/anidado_variations/{id}

Path parameters

integer

required

Nested variation ID to delete.

Response

{ "message": 200 }

Example: Building a Color + Size Variation Tree

The following walkthrough creates a Color → Size variation tree for product ID 42, which has a base stock of 50 units total.

Create the first-level Color variations

Create one first-level variation for each color. The total stock across colors represents the available inventory per color.

# Color = Red, 30 units
curl -X POST https://your-domain.com/api/admin/variations \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 42,
    "attribute_id": 1,
    "propertie_id": 1,
    "add_price": 0,
    "stock": 30,
    "state": 1
  }'

{ "message": 200, "variation": { "id": 5, "propertie": { "name": "Red" }, "stock": 30 } }

# Color = Blue, 20 units
curl -X POST https://your-domain.com/api/admin/variations \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 42,
    "attribute_id": 1,
    "propertie_id": 2,
    "add_price": 0,
    "stock": 20,
    "state": 1
  }'

{ "message": 200, "variation": { "id": 6, "propertie": { "name": "Blue" }, "stock": 20 } }

Create nested Size variations under Red (id=5)

The sum of nested stock must not exceed the parent’s stock (30).

# Red / Size S — 10 units
curl -X POST https://your-domain.com/api/admin/anidado_variations \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 42,
    "product_variation_id": 5,
    "attribute_id": 6,
    "propertie_id": 11,
    "add_price": 0,
    "stock": 10,
    "state": 1
  }'

# Red / Size M — 12 units
curl -X POST https://your-domain.com/api/admin/anidado_variations \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 42,
    "product_variation_id": 5,
    "attribute_id": 6,
    "propertie_id": 12,
    "add_price": 0,
    "stock": 12,
    "state": 1
  }'

# Red / Size L — 8 units  (10 + 12 + 8 = 30 ✓)
curl -X POST https://your-domain.com/api/admin/anidado_variations \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 42,
    "product_variation_id": 5,
    "attribute_id": 6,
    "propertie_id": 13,
    "add_price": 0,
    "stock": 8,
    "state": 1
  }'

Repeat nested variations for Blue (id=6)

Repeat Step 2 using "product_variation_id": 6 and a total stock not exceeding 20. The resulting tree looks like:

Product #42
├── Color: Red  (stock: 30)
│   ├── Size: S  (stock: 10)
│   ├── Size: M  (stock: 12)
│   └── Size: L  (stock:  8)
└── Color: Blue (stock: 20)
    ├── Size: S  (stock:  8)
    ├── Size: M  (stock:  7)
    └── Size: L  (stock:  5)

Authentication

Storefront

Admin

Admin Product Variations and Attributes API Reference

Authentication

Attributes

List Attributes

Create Attribute

Update Attribute

Delete Attribute

Properties

Add Property to Attribute

Delete Property

Variation Config

Product Variations (First Level)

List Variations for a Product

Create Variation

Update Variation

Delete Variation

Nested (Anidado) Variations

List Nested Variations

Create Nested Variation

Update Nested Variation

Delete Nested Variation

Example: Building a Color + Size Variation Tree

Build docs developers (and LLMs) love

Authentication

Storefront

Admin

Documentation Index

​Authentication

​Attributes

​List Attributes

​Create Attribute

​Update Attribute

​Delete Attribute

​Properties

​Add Property to Attribute

​Delete Property

​Variation Config

​Product Variations (First Level)

​List Variations for a Product

​Create Variation

​Update Variation

​Delete Variation

​Nested (Anidado) Variations

​List Nested Variations

​Create Nested Variation

​Update Nested Variation

​Delete Nested Variation

​Example: Building a Color + Size Variation Tree

Build docs developers (and LLMs) love

Authentication

Attributes

List Attributes

Create Attribute

Update Attribute

Delete Attribute

Properties

Add Property to Attribute

Delete Property

Variation Config

Product Variations (First Level)

List Variations for a Product

Create Variation

Update Variation

Delete Variation

Nested (Anidado) Variations

List Nested Variations

Create Nested Variation

Update Nested Variation

Delete Nested Variation

Example: Building a Color + Size Variation Tree