Custom columns

Custom columns let you extend a grid with your own data fields. You can add them manually, edit cell values inline, and choose how each column stores and displays its data.

This page covers the API-level details of custom columns. For the in-app Add Column flow with screenshots and step-by-step walkthroughs, see Add columns.

Add a custom column

Click Add Column in the grid toolbar to open the column stepper. The stepper walks you through two steps:

Select a column type - choose from Text, Number, Currency, or Formula.
Configure the column - set a name and any type-specific options, then click Add Column.

The new column appears immediately in the grid.

Column types

Type	`column_type` value	Description
Text	`custom_text`	Plain text field. Values are stored as strings.
Number	`custom_number`	Numeric field. Values are stored as numbers.
Currency	`custom_currency`	Numeric field displayed in the account’s display currency (see Currency).
Formula	`custom_formula`	Dynamically computed from other columns.

Formula columns

Formula columns reference other column values using expressions and display the result according to a Display Format you pick during setup:

Formatter	`formatter` value	Behavior
Text	`text`	Result is rendered as plain text.
Number	`number`	Result is rendered as a number.
Currency	`currency`	Result is rendered in the account’s display currency.

Grouping and aggregation are not available for formula columns.

Edit cell values

Custom columns are editable directly in the grid. Click a cell and type to update its value. Press Enter to confirm and move to the next row. Retailgrid validates the value against the column’s storage type before saving:

Storage type	Accepted values	Rejected values
`string`	Text, `null`	-
`numeric`	Numbers, numeric strings, `null`	Booleans
`integer`	Integers, integer strings, `null`	Booleans, floats with a fractional part
`boolean`	`true`/`false`, `"true"`/`"1"`/`"yes"`, `null`	-

If the value cannot be coerced to the expected type, the API returns a 422 error and the cell reverts to its previous value. Clearing a cell (leaving it empty) stores null for all column types.

API reference

The internal API path segment is currently /workbooks/ for historical reasons. The customer-facing concept is Grid everywhere in the product and the docs; the path segment will be renamed in a future API version. Both segments resolve to the same endpoint.

Add a custom column

POST /workbooks/{grid_id}/columns/add-custom

Request body

{
  "name": "Margin",
  "column_type": "custom_formula",
  "formatter": "currency"
}

Field	Type	Required	Description
`name`	string	No	Column label. Defaults to `"Custom"`.
`column_type`	string	No	One of `custom_text`, `custom_number`, `custom_currency`, `custom_formula`. Defaults to `custom_text`.
`formatter`	string	No	Display format for `custom_formula` columns: `text`, `number`, or `currency`. Defaults to `text`.

Response

{
  "column_id": 42,
  "column_key": "dyn:a1b2c3d4e5f6",
  "column_name": "Margin",
  "unique_id": "dyn:42",
  "type": "custom_formula",
  "formatter": "currency"
}

Set a cell value

PUT /workbooks/{grid_id}/data/cells

Request body

{
  "row_id": 101,
  "column_id": 42,
  "value": 19.99
}

Field	Type	Required	Description
`row_id`	integer	Yes	Must be greater than `0`.
`column_id`	integer	Yes	Must be greater than `0`.
`value`	string \| number \| boolean \| null	Yes	The new cell value. Pass `null` to clear the cell.

Errors

Status	Cause
`404`	Column not found in this grid.
`422`	Value cannot be coerced to the column’s storage type (e.g. passing a boolean to a numeric column).

Get started

Grids

Columns & metrics

SKU & store views

Stores

Agents

Dashboards

Settings

Add a custom column

Column types

Formula columns

Edit cell values

API reference

Add a custom column

Set a cell value

​Add a custom column

​Column types

​Formula columns

​Edit cell values

​API reference

​Add a custom column

​Set a cell value

​Related

Add a custom column

Column types

Formula columns

Edit cell values

API reference

Add a custom column

Set a cell value

Related