Skip to content

Variants

Variants are the actual SKU that are sold in the store. Product of kind basic has a single default variant and with kind with-variants has more than 1 variant. Pricing, taxation, the dimensions of the packaged product and various details needed for selling and shipping an SKU are captured in the variant model.

Variant Object

Below is the json representation of the variant object, followed by a data table

Variant Object
{
  "attribute_values": null,
  "created_at": "2023-04-05T04:00:48.299Z",
  "description": null,
  "gtin_code": null,
  "id": "fcfff0e9-655c-4753-b8cf-6ccf6f37fa64",
  "is_backorderable": false,
  "is_default": true,
  "list_price_units": null,
  "media": [],
  "metadata": null,
  "name": "variant name",
  "position": 0,
  "price_units": null,
  "product_id": "121681a8-5e51-4e3f-9e58-542687bb214a",
  "properties": null,
  "sku": null,
  "status": "inactive",
  "stock_items": [],
  "store_tax_code_id": null,
  "tax_number": null,
  "updated_at": "2023-04-05T04:00:48.323Z"
}

Fields

All Fields

Field Data Type Description
attribute_values object array Provides values for different variant kinds described in product object's variant attributes field.
created_at string UTC timestamp at which the variant was created.
description string description of the variant.
gtin_code string GTIN number, Refer wiki
id string UUID of the variant.
is_backorderable boolean Whether this variant can accept order even when stock is not available. See Stock Management pages for more information.
is_default boolean Whether this is the default variant within the product.
list_price_units integer Maximum price at which this sku can be sold. Value is expressed in least denomination of the currency. For Indian store, this value will be in paisa.
media object array images and other files attached to this variant. See Media page for more details.
metadata object seo and marketing related content, see metada section for more details.
name string Name of the variant.
position integer Position of this variant within multiple variants of the product.
price_units integer Price at which this sku can be sold. Value is expressed in least denomination of the currency. For Indian store, this value will be in paisa.
product_id string UUID of the product. See product object page for more details.
properties object length, width and height of the variant. See properties section for more details.
sku string Unique sku for this variant across the store.
status string status of the variant. See status section for more details.
stock_items object array Array of stock_item objects. See stock_item page for more details. Relation: Variant has many stock_items
store_tax_code_id string Tax details associated with this variant. See taxation page for more details. Relation: Variant has one or none tax code associated with it.
tax_number string Tax number associated with the variant. This is the govt. code assigned to various categories of the product. In Indian context this will be HSN or SAC code.
updated_at string UTC timestamp at which the variant was last modified.

Objects

Attribute Value Object
Field Data Type Description
kind string Attribute kind defined in one of variant_attributes object in product.
value string Value of the attribute kind.
Metadata Object

Metadata object captures various feilds related to seo and marketing across webpages, google and facebook.

Field Data Type Description
google_title string Title of this variant that should be shown in google ads or google catalog.
google_descritpion string Description of this variant that should be shown in google ads or google catalog.
facebook_title string Title of this variant that should be shown in facebook ads or facebook catalog.
facebook_descritpion string Description of this variant that should be shown in facebook ads or facebook catalog.
Properties Object

Properties object captures length, width, height and weight of the packaged sku. This is vital for shipping charges.

Field Data Type Description
length integer length of the package in mm.
width integer width of the package in mm.
height integer height of the package in mm.
weight integer weight of the package in grams.

Status State Machine

status field represents whether a variant is sellable on storefront. When a variant is in active state it can be sold. Temporarily variant's can be suspended to be sold on storefront by moving them to inactive state. An archived variant can be considered as a decommissioned variant and it cannot be sold on the storefront anymore.

Possible values: active, inactive and archived. Below diagram shows possible transitions on the product status.

graph LR
  A[active] --> |archive| C[archived];
  B[inactive] --> |archive| C[archived];
  A --> |deactivate| B;
  B --> |activate| A;
  C --> |unarchive| B;

API

List Variants

GET /api/platform/v1/products/{product_id}/variants

Lists the variants of a product. The result set is paginated and can be controlled by various query parameters

Query Params
Field Data Type Description
page integer Page number of the result set. Values start from 1.
per_page integer How many items should be present in a given page.
curl command 
curl 'http://localhost:3000/api/platform/v1/products/6f50c995-930e-46a3-8e6e-f8617a239eba/variants' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer r_4p9chTbUBxI7wL14C1ZyHcc9TRHavj_3yPWPeAoFw' \
  -H 'Content-Type: application/json'
Response Body

response json data object is list of variant object 

  {
  "status": "success",
  "data": [
    {
      "id": "693fd757-3426-45e1-80b3-2161a0705b5d",
      "product_id": "6f50c995-930e-46a3-8e6e-f8617a239eba",
      "position": 0,
      "sku": null,
      "name": "color: Red",
      "status": "active",
      "attribute_values": [{ "kind": "color", "value": "Red" }],
      "price_units": null,
      "list_price_units": null,
      "is_default": true,
      "is_backorderable": false,
      "properties": null,
      "metadata": null,
      "extradata": null,
      "created_at": "2023-04-13T10:06:51.091Z",
      "updated_at": "2023-04-13T10:11:23.850Z",
      "account_id": "a9f7ef20-dc03-494a-9db2-cbc43ff2f564",
      "tax_number": null,
      "store_tax_code_id": null,
      "description": null,
      "gtin_code": null,
      "stock_items": [],
      "media": []
    },
    {
      "id": "dcc58fcb-6ecc-4eba-a5ca-562939fdded4",
      "product_id": "6f50c995-930e-46a3-8e6e-f8617a239eba",
      "position": 1,
      "sku": null,
      "name": "color: Blue",
      "status": "active",
      "attribute_values": [{ "kind": "color", "value": "Blue" }],
      "price_units": null,
      "list_price_units": null,
      "is_default": false,
      "is_backorderable": false,
      "properties": null,
      "metadata": null,
      "extradata": null,
      "created_at": "2023-04-13T10:11:29.535Z",
      "updated_at": "2023-04-13T10:11:29.535Z",
      "account_id": "a9f7ef20-dc03-494a-9db2-cbc43ff2f564",
      "tax_number": null,
      "store_tax_code_id": null,
      "description": null,
      "gtin_code": null,
      "stock_items": [],
      "media": []
    }
  ],
  "pagination": {
    "total_count": 2,
    "current_page": 1,
    "total_pages": 1,
    "window": 4,
    "breakdown": [
      {
        "kind": "inner",
        "url": "/api/platform/v1/products/6f50c995-930e-46a3-8e6e-f8617a239eba/variants",
        "page": 1
      }
    ]
  }
}


 {
  "status": "failure",
  "data": [{ "attribute_name": "id", "messages": ["Not Found"] }],
  "message": null,
  "errors": null
 }

Create Variant

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

To create a variant, the api requires values for all the attribute kinds defined in the product object.

Request Body

Request body is an array of attribute_value objects 

  {
    "variant_attributes": [{ "kind": "color", "value": "Yellow" }]
  }

curl command 
curl 'http://localhost:3000/api/platform/v1/products/6f50c995-930e-46a3-8e6e-f8617a239eba/variants' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer r_4p9chTbUBxI7wL14C1ZyHcc9TRHavj_3yPWPeAoFw' \
    -H 'Content-Type: application/json' \
    --data-raw '{"variant_attributes":[{"kind":"color","value":"Green"}]}'
Response Body

response json data is variant object 

{
  "status": "success",
  "data": {
    "id": "ec0e0cdf-97e2-4664-a15f-388434b7a253",
    "product_id": "6f50c995-930e-46a3-8e6e-f8617a239eba",
    "position": 3,
    "sku": null,
    "name": "color: Green",
    "status": "active",
    "attribute_values": [
      {
        "kind": "color",
        "value": "Green"
      }
    ],
    "price_units": null,
    "list_price_units": null,
    "is_default": false,
    "is_backorderable": false,
    "properties": null,
    "metadata": null,
    "extradata": null,
    "created_at": "2023-04-15T06:39:06.016Z",
    "updated_at": "2023-04-15T06:39:06.016Z",
    "account_id": "a9f7ef20-dc03-494a-9db2-cbc43ff2f564",
    "tax_number": null,
    "store_tax_code_id": null,
    "description": null,
    "gtin_code": null,
    "stock_items": [],
    "media": []
  }
}


{
  "status": "failure",
  "data": [
    {
      "attribute_name": "variant_attributes",
      "messages": [
        "Variant attributes failed creation - Attribute values is already present"
      ]
    }
  ],
  "message": null,
  "errors": null
}

Get Variant

GET /api/platform/v1/products/{product_id}/variants/{id} GET /api/platform/v1/variants/{id}

A Variant can be obtained directly by id or via its product.

curl command 
  curl 'http://localhost:3000/api/platform/v1/products/6f50c995-930e-46a3-8e6e-f8617a239eba/variants/dcc58fcb-6ecc-4eba-a5ca-562939fdded4' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer 0QgCt_eGSJQsAgCHmEAIg1BLvpmKkfwNi_C3yOHESLY' \
  -H 'Content-Type: application/json'

  curl 'http://localhost:3000/api/platform/v1/variants/dcc58fcb-6ecc-4eba-a5ca-562939fdded4' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer 0QgCt_eGSJQsAgCHmEAIg1BLvpmKkfwNi_C3yOHESLY' \
  -H 'Content-Type: application/json'
Response Body

response json data is variant object 

{
  "status": "success",
  "data": {
    "id": "ec0e0cdf-97e2-4664-a15f-388434b7a253",
    "product_id": "6f50c995-930e-46a3-8e6e-f8617a239eba",
    "position": 3,
    "sku": null,
    "name": "color: Green",
    "status": "active",
    "attribute_values": [
      {
        "kind": "color",
        "value": "Green"
      }
    ],
    "price_units": null,
    "list_price_units": null,
    "is_default": false,
    "is_backorderable": false,
    "properties": null,
    "metadata": null,
    "extradata": null,
    "created_at": "2023-04-15T06:39:06.016Z",
    "updated_at": "2023-04-15T06:39:06.016Z",
    "account_id": "a9f7ef20-dc03-494a-9db2-cbc43ff2f564",
    "tax_number": null,
    "store_tax_code_id": null,
    "description": null,
    "gtin_code": null,
    "stock_items": [],
    "media": []
  }
}


{
  "status": "failure",
  "data": [{ "attribute_name": "id", "messages": ["Not Found"] }],
  "message": null,
  "errors": null
}

Update Variant

PATCH /api/platform/v1/products/{product_id}/variants/{id}

Request Body

All the fields in the variant object can be updated except for those that are related objects.

{
  "sku": "TSHT-YL",
  "tax_number": "HTSV112",
  "gtin_code": "332456",
  "price_units": 200000,
  "list_price_units": 220000,
  "is_backorderable": false,
  "store_tax_code_id": null,
  "properties": { "length": 200, "height": 340, "width": 420, "weight": 500 }
}
curl command 
  curl 'http://localhost:3000/api/platform/v1/products/6f50c995-930e-46a3-8e6e-f8617a239eba/variants/10afecaf-cc79-4226-9855-0d30df513574' \
    -X 'PATCH' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer 0QgCt_eGSJQsAgCHmEAIg1BLvpmKkfwNi_C3yOHESLY' \
    -H 'Content-Type: application/json' \
    --data-raw '{"sku":"TSHT-YL","tax_number":"HTSV112","gtin_code":"332456","price_units":200000,"list_price_units":220000,"is_backorderable":false,"store_tax_code_id":null,"properties":{"length":200,"height":340,"width":420,"weight":500}}'
Response Body

response json data is variant object 

{
  "status": "success",
  "data": {
    "product_id": "6f50c995-930e-46a3-8e6e-f8617a239eba",
    "id": "10afecaf-cc79-4226-9855-0d30df513574",
    "position": 2,
    "sku": "TSHT-YL",
    "name": "color: Yellow",
    "status": "active",
    "attribute_values": [{ "kind": "color", "value": "Yellow" }],
    "price_units": 200000,
    "list_price_units": 220000,
    "is_default": false,
    "is_backorderable": false,
    "properties": { "length": 200, "width": 420, "height": 340, "weight": 500 },
    "metadata": null,
    "extradata": null,
    "created_at": "2023-04-14T11:39:38.295Z",
    "updated_at": "2023-04-15T07:28:22.454Z",
    "account_id": "a9f7ef20-dc03-494a-9db2-cbc43ff2f564",
    "tax_number": "HTSV112",
    "store_tax_code_id": null,
    "description": null,
    "gtin_code": "332456",
    "stock_items": [],
    "media": []
  }
}


{
  "status": "failure",
  "data": [{ "attribute_name": "id", "messages": ["Not Found"] }],
  "message": null,
  "errors": null
}

Delete Variant

DELETE /api/platform/v1/products/{product_id}/variants/{id}

If a variant has no dependent orders, it can be deleted. If it has existing orders associated with it, it can only be archived.

Request Body

Request body must be empty json. 

{}

curl command 
curl 'http://localhost:3000/api/platform/v1/products/6f50c995-930e-46a3-8e6e-f8617a239eba/variants/10afecaf-cc79-4226-9855-0d30df513574' \
    -X 'DELETE' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer 0QgCt_eGSJQsAgCHmEAIg1BLvpmKkfwNi_C3yOHESLY' \
    -H 'Content-Type: application/json' \
    --data-raw '{}'
Response Body

response json data is variant object 

{
  "status": "success",
  "data": {
    "product_id": "6f50c995-930e-46a3-8e6e-f8617a239eba",
    "id": "10afecaf-cc79-4226-9855-0d30df513574",
    "position": 2,
    "sku": "TSHT-YL",
    "name": "color: Yellow",
    "status": "active",
    "attribute_values": [{ "kind": "color", "value": "Yellow" }],
    "price_units": 200000,
    "list_price_units": 220000,
    "is_default": false,
    "is_backorderable": false,
    "properties": { "length": 200, "width": 420, "height": 340, "weight": 500 },
    "metadata": null,
    "extradata": null,
    "created_at": "2023-04-14T11:39:38.295Z",
    "updated_at": "2023-04-15T07:28:22.454Z",
    "account_id": "a9f7ef20-dc03-494a-9db2-cbc43ff2f564",
    "tax_number": "HTSV112",
    "store_tax_code_id": null,
    "description": null,
    "gtin_code": "332456",
    "stock_items": [],
    "media": []
  }
}


{
  "status": "failure",
  "data": [{ "attribute_name": "id", "messages": ["Not Found"] }],
  "message": null,
  "errors": null
}

Transition Variant Status

POST /api/platform/v1/products/{product_id}/variants/{id}/transition

This api should be used to make state transitions as discussed in status section.

Request Body
Field Data Type Description Required
name string Name of the transition. One of active, inactive, unarchive or archive 
{
  "name": "active"
}
curl command 
curl 'http://localhost:3000/api/platform/v1/products/6f50c995-930e-46a3-8e6e-f8617a239eba/variants/dcc58fcb-6ecc-4eba-a5ca-562939fdded4/transition' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer 0QgCt_eGSJQsAgCHmEAIg1BLvpmKkfwNi_C3yOHESLY' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"active"}'
Response Body

response json data is variant object 

{
  "status": "success",
  "data": {
    "product_id": "6f50c995-930e-46a3-8e6e-f8617a239eba",
    "id": "10afecaf-cc79-4226-9855-0d30df513574",
    "position": 2,
    "sku": "TSHT-YL",
    "name": "color: Yellow",
    "status": "active",
    "attribute_values": [{ "kind": "color", "value": "Yellow" }],
    "price_units": 200000,
    "list_price_units": 220000,
    "is_default": false,
    "is_backorderable": false,
    "properties": { "length": 200, "width": 420, "height": 340, "weight": 500 },
    "metadata": null,
    "extradata": null,
    "created_at": "2023-04-14T11:39:38.295Z",
    "updated_at": "2023-04-15T07:28:22.454Z",
    "account_id": "a9f7ef20-dc03-494a-9db2-cbc43ff2f564",
    "tax_number": "HTSV112",
    "store_tax_code_id": null,
    "description": null,
    "gtin_code": "332456",
    "stock_items": [],
    "media": []
  }
}


{
  "status": "failure",
  "data": [{ "attribute_name": "id", "messages": ["Not Found"] }],
  "message": null,
  "errors": null
}

Reorder Variants

POST /api/platform/v1/products/{product_id}/variants/{id}/reorder

This api should be used to reorders position of variant within a product. Later these positions can be used in storefront to display in an order that is preferred.

Request Body
Field Data Type Description Required
id string UUID of the variant
position integer integer value
curl command 
curl 'http://localhost:3000/api/platform/v1/products/6f50c995-930e-46a3-8e6e-f8617a239eba/variants/reorder' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer 0QgCt_eGSJQsAgCHmEAIg1BLvpmKkfwNi_C3yOHESLY' \
-H 'Content-Type: application/json' \
--data-raw '{"items":[{"id":"693fd757-3426-45e1-80b3-2161a0705b5d","position":0},{"id":"dcc58fcb-6ecc-4eba-a5ca-562939fdded4","position":1},{"id":"ec0e0cdf-97e2-4664-a15f-388434b7a253","position":2}]}'
Response Body

Response is always success with data being null. Position is presentation logic, so the api wont perform validation around it. 

  {"status":"success","data":null}