Custom Fields

Custom Fields are customizable fields that you can add to different entities in Lightspeed Retail (X-Series). As an example you could create a Custom Field on line items to store serial numbers of the products that you sell.

To get started you need to first define the fields that you want to use.

This feature is only available on Enterprise plans.

Defining a Custom Field

To define a Custom Field you create a new Custom Field Definition by using our API:

POST /api/2.0/workflows/custom_fields

In the payload you specify the configuration of the field:

{
	"entity": "line_item",
	"name": "serial",
	"title": "Serial Number",
	"type": "string"
}

As a response, you will get a CustomFieldDefinition object:

{
  "data": {
    "id": "1249847800380837888",
    "entity": "line_item",
    "name": "serial",
    "title": "Serial Number",
    "type": "string",
    "created_at": "2020-04-13T23:51:51Z"
  }
}

For more details see the Define Custom Field documentation

Setting Custom Field Values

Now that the custom field is defined, you can start storing serial numbers on line items. To store the serial number SN3847sj-34 on the line item with ID 02dcd191-ae37-11e9-f336-e3ff43e54707, you call the API:

POST /api/2.0/workflows/custom_fields/values

In the payload you specify the values that you want to store:

{
	"entity": "line_item",
	"entity_id": "02dcd191-ae37-11e9-f336-e3ff43e54707",
	"values": [
		{
			"name": "serial",
			"string_value": "SN3847sj-34"
		}
	]
}

Note that the entity_id here is the id of the entity item - in this case, the id of the line_item.

As a response, you will get a list if CustomFieldValue objects that were created:

{
  "data": [
    {
      "definition_id": "1249847800380837888",
      "name": "serial",
      "title": "Serial Number",
      "type": "string",
      "string_value": "SN3847sj-34"
    }
  ]
}

Please note that you will only be able to retrieve and update custom fields created by your app. Additionally, custom fields stored against an entity are not currently able to be searched for from the UI.

For more details see the Set Custom Field Values documentation