Documentation Index
Fetch the complete documentation index at: https://docs.retailgrid.io/llms.txt
Use this file to discover all available pages before exploring further.
Custom columns let you extend a workbook 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.
Adding a custom column
Click Add Column in the workbook 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 with $ formatting. |
| Formula | custom_formula | Dynamically computed from other columns. |
| 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 with $ formatting. |
Grouping and aggregation are not available for formula columns.
Editing 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 | — |
422 error and the cell reverts to its previous value.
Clearing a cell (leaving it empty) stores null for all column types.
API reference
Add a custom column
POST /workbooks/{workbook_id}/columns/add-custom
{
"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. |
{
"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/{workbook_id}/data/cells
{
"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. |
| Status | Cause |
|---|
404 | Column not found in this workbook. |
422 | Value cannot be coerced to the column’s storage type (e.g. passing a boolean to a numeric column). |
