Skip to content

Property Sets

PropertySets are a way to add arbitrary data to products and variants. This is a powerful way to add a structured data to product/variant that can be leveraged by storefront.

Object

Below is the json representation of the PropertySet object of kind list

PropertySet List Object
{
    "created_at": "2023-05-30T09:15:49.766Z",
    "description": "A comprehensive set of ingredients used in the store.",
    "id": "cb809dc8-52a5-4eef-b277-d8cb845f3afb",
    "info": [
        {
            "kind": "text",
            "position": 0,
            "value": "Butter"
        },
        {
            "kind": "text",
            "position": 1,
            "value": "Raw Cacao"
        },
        {
            "kind": "text",
            "position": 2,
            "value": "Vanilla Pods"
        },
        {
            "kind": "text",
            "position": 3,
            "value": "Coconut Nectar"
        }
    ],
    "is_template": true,
    "kind": "list",
    "name": "Ingredient",
    "product_id": null,
    "status": "active",
    "updated_at": "2023-05-30T09:17:37.218Z",
    "variant_id": null
}

Note

Info object is different based on the kind of the PropertySet

All Fields

Field Data Type Description
created_at string UTC timestamp at which the PropertySet was created.
description string Detailed description of the PropertySet.
id string UUID of the PropertySet.
info object array Shape of this object depends on the kind of the PropertySet.
is_template boolean Whether the property set is a template. If it is template, both product_id and variant_id will be null.
kind string Kind of the PropertySet, possible values are list, table, strict_table and media.
name string Name of the PropertySet.
product_id string Product to which this PropertySet belongs to. Relation: PropertySet optionally belongs to a Product
status string Status of the PropertySet. Possible values are active and inactive
updated_at string UTC timestamp at which the PropertySet was updated.
variant_id string Variant to which this PropertySet belongs to. Relation: PropertySet optionally belongs to a Variant

Property Fields

Field Data Type Description
kind string data type of the value field. Possible values are text, number, text_array and number_array
position number position of this item in the info list
value string or number value of list item

Kind

There are two kinds of PropertySets, List and Table. List and Table can be added to a product/variant as a propertyset.

List

A PropertySet whose kind value is list. info object is an array of property objects

Info Object
{
  "info": [
    {
        "kind": "text",
        "position": 0,
        "value": "Butter"
    },
    {
        "kind": "text",
        "position": 1,
        "value": "Raw Cacao"
    },
    {
        "kind": "text",
        "position": 2,
        "value": "Vanilla Pods"
    },
    {
        "kind": "text",
        "position": 3,
        "value": "Coconut Nectar"
    }
  ]
}

PropertySet List can be better explained with an example. See below "Ingredient" PropertySet List of a packaged product.

Ingredients
Butter
Raw Cacao
Vanilla Pods
Coconut Nectar

Table

A PropertySet whose kind value is table and info is an object containing columns and rows field. Each of the rows and columns object is an array of property objects

Info Object
{
  "info": {
    "rows": [
      [
        {
          "kind": "text",
          "value": "Energy",
          "position": 0
        },
        {
          "kind": "text",
          "value": "488.74 kcal",
          "position": 1
        }
      ],
      [
        {
          "kind": "text",
          "value": "Carbohydrates",
          "position": 0
        },
        {
          "kind": "text",
          "value": "52.55 g",
          "position": 1
        }
      ],
      [
        {
          "kind": "text",
          "value": "Sugars",
          "position": 0
        },
        {
          "kind": "text",
          "value": "36.19 g",
          "position": 1
        }
      ],
      [
        {
          "kind": "text",
          "value": "Dietary Fiber",
          "position": 0
        },
        {
          "kind": "text",
          "value": "9.37 g",
          "position": 1
        }
      ],
      [
        {
          "kind": "text",
          "value": "Protein",
          "position": 0
        },
        {
          "kind": "text",
          "value": "12.93 g",
          "position": 1
        }
      ]
    ],
    "columns": [
      {
        "kind": "text",
        "value": "Name",
        "position": 0
      },
      {
        "kind": "text",
        "value": "Value",
        "position": 1
      }
    ]
  }
}
PropertySet List can be better explained with an example. See below "Nutrition Info" PropertySet Table of a packaged product.

Name Value
Energy 488.74 kcal
Carbohydrates 52.55 g
Sugars 36.19 g
Dietary Fiber 9.37 g
Protein 12.93 g

Templates

Often for a storefront, across their products, propertyset information get repetitive. To simplify the repetitive process, propertysets can be created as templates at store level and then each product/variant can import that template and make any necessary modification that is relevant.

API

List

GET /api/platform/v1/property_sets

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.
is_template boolean Filter result set based on is_template field.
product_id string Filter result set based on a particular product.
variant_id string Filter result set based on a particular variant.
curl command 
curl 'http://localhost:3000/api/platform/v1/property_sets?is_template=true' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer 7-G8hFiWAh2TTmrLwD5Kwih51mWbesWnd2fNUyg-Wpg' \
    -H 'Content-Type: application/json'
Response Body

This api responds with array of property_set objects

Create

POST /api/platform/v1/property_sets

name, kind and one of is_template or product_id or variant_id is required to create a property set. Later using update api more details can be added to the propertyset.

Request Body 
{
  "name": "Test List 1",
  "kind": "list",
  "is_template": true
}
curl command 
curl 'http://localhost:3000/api/platform/v1/property_sets' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer 7-G8hFiWAh2TTmrLwD5Kwih51mWbesWnd2fNUyg-Wpg' \
    -H 'Content-Type: application/json' \
    --data-raw '{"name":"Test List 1", "kind":"list","is_template":true}'
Response Body

response json data object is propertyset object 

{
  "status": "success",
  "data": {
    "id": "d9750390-a39e-4121-b416-3058dff10a35",
    "is_template": true,
    "status": "active",
    "name": "Test List 1",
    "description": null,
    "kind": "list",
    "info": null,
    "created_at": "2023-05-31T07:10:43.823Z",
    "updated_at": "2023-05-31T07:10:43.823Z",
    "variant_id": null,
    "product_id": null
  }
}


 {
  "status": "failure",
  "data": [
    {
      "attribute_name": "kind",
      "messages": ["Kind lister is not a valid kind"]
    }
  ],
  "message": null,
  "errors": null
}

Get

GET /api/platform/v1/property_sets/{id}

curl command 
curl 'http://localhost:3000/api/platform/v1/property_sets/29bd775d-2c9a-4aa2-96dc-202de4dc49d7' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer 7-G8hFiWAh2TTmrLwD5Kwih51mWbesWnd2fNUyg-Wpg' \
  -H 'Content-Type: application/json'
Response Body

response json data object is propertyset object 

{
  "status": "success",
  "data": {
    "id": "29bd775d-2c9a-4aa2-96dc-202de4dc49d7",
    "is_template": true,
    "status": "active",
    "name": "Nutrition Info",
    "description": "Nutrition information in the packaged food.",
    "kind": "table",
    "info": {
      "rows": [
        [
          { "kind": "text", "value": "Energy", "position": 0 },
          { "kind": "text", "value": "488.74 kcal", "position": 1 }
        ],
        [
          { "kind": "text", "value": "Carbohydrates", "position": 0 },
          { "kind": "text", "value": "52.55 g", "position": 1 }
        ],
        [
          { "kind": "text", "value": "Sugars", "position": 0 },
          { "kind": "text", "value": "36.19 g", "position": 1 }
        ],
        [
          { "kind": "text", "value": "Dietary Fiber", "position": 0 },
          { "kind": "text", "value": "9.37 g", "position": 1 }
        ],
        [
          { "kind": "text", "value": "Protein", "position": 0 },
          { "kind": "text", "value": "12.93 g", "position": 1 }
        ]
      ],
      "columns": [
        { "kind": "text", "value": "Name", "position": 0 },
        { "kind": "text", "value": "Value", "position": 1 }
      ]
    },
    "created_at": "2023-05-31T06:12:28.873Z",
    "updated_at": "2023-05-31T06:14:16.423Z",
    "variant_id": null,
    "product_id": null,
    "account_id": "a9f7ef20-dc03-494a-9db2-cbc43ff2f564"
  }
}


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

Update

PATCH /api/platform/v1/property_sets/{id}

Request Body

All the fields in the propertyset object can be updated except for those that are related kind. Therefore info object can be modified only as list_info for kind list and table_info for kind table. 

{
    "name": "Summer T Shirt"
}

curl command 
curl 'http://localhost:3000/api/platform/v1/property_sets/cb809dc8-52a5-4eef-b277-d8cb845f3afb' \
-X 'PATCH' \
-H 'Accept: application/json, text/plain' \
-H 'Authorization: Bearer 7-G8hFiWAh2TTmrLwD5Kwih51mWbesWnd2fNUyg-Wpg' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"Ingredient","description":"A comprehensive set of ingredients used in the store.","is_template":true,"list_info":[{"kind":"text","value":"Butter"},{"kind":"text","value":"Raw Cacao"},{"kind":"text","value":"Vanilla Pods"},{"kind":"text","value":"Coconut Nectar"},{"kind":"text","value":"Nuts & Seeds"}]}'
Response Body

response json data object is propertyset object 

{
  "status": "success",
  "data": {
    "id": "cb809dc8-52a5-4eef-b277-d8cb845f3afb",
    "is_template": true,
    "status": "active",
    "name": "Ingredient",
    "description": "A comprehensive set of ingredients used in the store.",
    "kind": "list",
    "info": [
      {
        "value": "Butter",
        "kind": "text",
        "position": 0
      },
      {
        "value": "Raw Cacao",
        "kind": "text",
        "position": 1
      },
      {
        "value": "Vanilla Pods",
        "kind": "text",
        "position": 2
      },
      {
        "value": "Coconut Nectar",
        "kind": "text",
        "position": 3
      },
      {
        "value": "Nuts & Seeds",
        "kind": "text",
        "position": 4
      }
    ],
    "created_at": "2023-05-30T09:15:49.766Z",
    "updated_at": "2023-05-31T07:22:53.835Z",
    "variant_id": null,
    "product_id": null
  }
}


 {
    "status": "failure",
    "data": [{
        "attribute_name": "name",
        "messages": ["Name can't be blank"]
    }],
    "message": null,
    "errors": null
}

Delete

DELETE /api/platform/v1/property_sets/{id}

Request Body

Request body must be empty json. 

{}

curl command 
curl 'http://localhost:3000/api/platform/v1/property_sets/d9750390-a39e-4121-b416-3058dff10a35' \
  -X 'DELETE' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer 7-G8hFiWAh2TTmrLwD5Kwih51mWbesWnd2fNUyg-Wpg' \
  -H 'Content-Type: application/json' \
  --data-raw '{}'
Response Body

response json data object is propertyset object 

{
  "status": "success",
  "data": {
    "id": "d9750390-a39e-4121-b416-3058dff10a35",
    "is_template": true,
    "status": "active",
    "name": "Test List 1",
    "description": null,
    "kind": "list",
    "info": null,
    "created_at": "2023-05-31T07:10:43.823Z",
    "updated_at": "2023-05-31T07:10:43.823Z",
    "variant_id": null,
    "product_id": null
  }
}


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