Variant Attributes

variant_attributes are field within the product object model. They define many variants of a product. Its an array field with the following object as defined in the table below.

Field	Data Type	Description
`kind`	string	Defines the property of the variant like color, size etc.
`properties`	string array	Array of strings. All possible values for a given property.

Consider the following variant_attributes value in the product object.

[
  {
    kind: "color",
    properties: ["blue", "red"]
  },
  {
    kind: "size",
    properties: ["small", "medium", "large"]
  }
]

This represents a possibility of a total 6 variants for this product blue-small, blue-medium, blue-large, red-small, red-medium, and red-large. Not all these variants need to be available, variants api can be used to fine tune and control which variants a product can support.

Instead of directly manipulating the product object's variants_attributes field, its recommended to use the variants attribute api to maintain consistency and offload validations and checks to the api. The api are simplified and designed in a way to start with basic product and use these api to incrementally add new attributes and values to them

API¶

Create¶

POST /api/platform/v1/products/{product_id}/variant_attributes

Use this api to add a variant attribute to a product. At least one property value is needed to add an attribute. Existing variants will be added with this new attributed kind and value. If this operation is performed on a basic product it will be converted to product kind with-variants.

Request Body

Field	Data Type	Description	Required
`kind`	string	Kind of the attribute, like color, size etc
`value`	string	Property value, for example if kind is "Color", value could be "Red"

{
  "kind": "Color",
  "value": "Red"
}

curl command

curl 'http://localhost:3000/api/platform/v1/products/64ea2096-a004-4967-b856-cca6f5ad9dc2/variant_attributes' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer KJW4Vzb27Yett76Btq3ockduQ9Hw1yI_-kSzyp_jjig' \
  -H 'Content-Type: application/json' \
  --data-raw '{"variant_attributes":[{"kind":"Color","value":"Red"}]}'

Response Body

200422

response json data object is product object

ght>

{ "status": "success", "data": { "id": "64ea2096-a004-4967-b856-cca6f5ad9dc2", "name": "Cool T Shirt", "slug": "cool-t-shirt", "status": "draft", "kind": "with-variants", "variant_attributes": [ { "kind": "Color", "properties": ["Red"] } ], "content": { "summary": "", "description": "" }, "variants": [ { "id": "89d8433a-9ccb-4cd6-b1e0-b1bd844ceafa", "position": 0, "sku": null, "name": "Color: Red", "status": "inactive", "attribute_values": [ { "kind": "Color", "value": "Red" } ], "price_units": null, "list_price_units": null, "is_default": true, "is_backorderable": false, "properties": null, "metadata": null, "tax_number": null, "store_tax_code_id": null, "stock_items": [], "media": [] } ] } class=p>}

   {
  "status": "failure",
  "data": [
    {
      "attribute_name": "attributes",
      "messages": ["Attributes already present in the products"]
    }
  ],
  "message": null,
  "errors": null
}

 Update Properties¶
  POST /api/platform/v1/products/{product_id}/variant_attributes/update_properties 
 Use this api to update the properties of a given variant of a product. Lets say a property is mistakenly added as Redd instead of Red, this api can be used to correct such mistakes.
  Request Body
 Item Object
    Field  Data Type  Description  Required  
 
   kind  string  attribute kind   
  value  string  attribute value   
 
 
    Field  Data Type  Description  Required  
 
   variant_id  string  id of the variant object whose   
  items  array of item objects  All of the attribute kinds whose value needs to be changed   
 
 
   {
    "variant_id": "89d8433a-9ccb-4cd6-b1e0-b1bd844ceafa",
    "items": [
      {
        "kind": "color",
        "value": "Red"
      }
    ]
  }
 
  curl command
 curl 'http://localhost:3000/api/platform/v1/products/64ea2096-a004-4967-b856-cca6f5ad9dc2/variant_attributes/update_properties' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer 8q_XqP08vme6ZGbGMWsvegCviU6Qa95OMFVmRy3gpc8' \
  -H 'Content-Type: application/json' \
  --data-raw '{"variant_id":"89d8433a-9ccb-4cd6-b1e0-b1bd844ceafa","items":[{"kind":"color","value":"Red"}]}'
 
  Response Body
 200422
   response json data object is product object 
{
  "status": "success",
  "data": {
    "id": "64ea2096-a004-4967-b856-cca6f5ad9dc2",
    "name": "Cool T Shirt",
    "slug": "cool-t-shirt",
    "status": "draft",
    "kind": "with-variants",
    "variant_attributes": [
      {
        "kind": "Color",
        "properties": ["Red"]
      }
    ],
    "content": {
      "summary": "",
      "description": ""
    },
    "variants": [
      {
        "id": "89d8433a-9ccb-4cd6-b1e0-b1bd844ceafa",
        "position": 0,
        "sku": null,
        "name": "Color: Red",
        "status": "inactive",
        "attribute_values": [
          {
            "kind": "Color",
            "value": "Red"
          }
        ],
        "price_units": null,
        "list_price_units": null,
        "is_default": true,
        "is_backorderable": false,
        "properties": null,
        "metadata": null,
        "tax_number": null,
        "store_tax_code_id": null,
        "stock_items": [],
        "media": []
      }
    ]
  }
}
 
   {
  "status": "failure",
  "data": [
    { "attribute_name": "items", "messages": ["Items Variant already exists"] }
  ],
  "message": null,
  "errors": null
}
 
 
 
 
 Update Attribute Kind¶
  PATCH /api/platform/v1/products/{product_id}/variant_attributes/{variant_attribute_kind}
 Use this api to update the attribute kind of a product. Lets say an attribute kind is mistakenly added as Color instead of color, this api can be used to correct such mistakes.
  Request Body
    Field  Data Type  Description  Required  
 
   to_kind  string  new value to change to.   
 
 
   {
    "to_kind": "color"
  }
 
  curl command
 curl 'http://localhost:3000/api/platform/v1/products/64ea2096-a004-4967-b856-cca6f5ad9dc2/variant_attributes/Color' \
  -X 'PATCH' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer 8q_XqP08vme6ZGbGMWsvegCviU6Qa95OMFVmRy3gpc8' \
  -H 'Content-Type: application/json' \
  --data-raw '{"to_kind":"color"}'
 
  Response Body
 200422
   {
  "status": "success",
  "data": {
    "id": "64ea2096-a004-4967-b856-cca6f5ad9dc2",
    "name": "Cool T Shirt",
    "slug": "cool-t-shirt",
    "status": "draft",
    "kind": "with-variants",
    "variant_attributes": [{ "kind": "color", "properties": ["Red"] }],
    "content": { "summary": "", "description": "" },
    "variants": [
      {
        "id": "89d8433a-9ccb-4cd6-b1e0-b1bd844ceafa",
        "position": 0,
        "sku": null,
        "name": "color: Red",
        "status": "inactive",
        "attribute_values": [{ "kind": "color", "value": "Red" }],
        "price_units": null,
        "list_price_units": null,
        "is_default": true,
        "is_backorderable": false,
        "properties": null,
        "metadata": null,
        "tax_number": null,
        "store_tax_code_id": null,
        "stock_items": [],
        "media": []
      }
    ]
  }
}
 
      {
      "status": "failure",
      "data": [
        {
          "attribute_name": "to_kind",
          "messages": ["To kind Should not be equal to kind"]
        }
      ],
      "message": null,
      "errors": null
    }
 
 
 
 
 Delete¶
  DELETE /api/platform/v1/products/{product_id}/variant_attributes/{variant_attribute_kind}
 Use this api to delete an attribute kind. If there are more than 1 variant with this attribute kind, api will give a failure message.
  Request Body
 Request body must be empty json. 
{}
 
  curl command
 curl 'http://localhost:3000/api/platform/v1/products/6f50c995-930e-46a3-8e6e-f8617a239eba/variant_attributes/color' \
  -X 'DELETE' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer 8q_XqP08vme6ZGbGMWsvegCviU6Qa95OMFVmRy3gpc8' \
  -H 'Content-Type: application/json' \
  --data-raw '{}'
 
  Response Body
 200422
   {
  "status": "success",
  "data": {
    "id": "6f50c995-930e-46a3-8e6e-f8617a239eba",
    "name": "Cool T Shirt",
    "slug": "cool-t-shirt",
    "status": "draft",
    "kind": "basic",
    "variant_attributes": null,
    "content": {
      "summary": "",
      "description": ""
    },
    "variants": [
      {
        "id": "693fd757-3426-45e1-80b3-2161a0705b5d",
        "position": 0,
        "sku": null,
        "name": "Default Variant",
        "status": "active",
        "attribute_values": null,
        "price_units": null,
        "list_price_units": null,
        "is_default": true,
        "is_backorderable": false,
        "properties": null,
        "metadata": null,
        "tax_number": null,
        "store_tax_code_id": null,
        "stock_items": [],
        "media": []
      }
    ]
  }
}
 
  Example 1 
    {
      "status": "failure",
      "data": [
        {
          "attribute_name": "product",
          "messages": ["Product attribute kind color not present"]
        }
      ],
      "message": null,
      "errors": null
    }
 Example 2   {
    "status": "failure",
    "data": [
      {
        "attribute_name": "product",
        "messages": ["Product attribute kind color has more than 1 value"]
      }
    ],
    "message": null,
    "errors": null
  }

Field	Data Type	Description	Required
`variant_id`	string	id of the variant object whose
`items`	array of item objects	All of the attribute kinds whose value needs to be changed