> ## 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

> Add editable custom columns to any grid - text, number, currency, or formula.

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.

> [!NOTE]
>
> 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](https://docs.retailgrid.io/grids/manage-columns.md).

## Add a custom column

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

1. **Select a column type** - choose from Text, Number, Currency, or Formula.
2. **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](https://docs.retailgrid.io/settings/currency.md)). |
| 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. |

> [!NOTE]
>
> 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

> [!NOTE]
>
> 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

```http theme={null}
POST /workbooks/{grid_id}/columns/add-custom
```

**Request body**

```json theme={null}
{
  "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**

```json theme={null}
{
  "column_id": 42,
  "column_key": "dyn:a1b2c3d4e5f6",
  "column_name": "Margin",
  "unique_id": "dyn:42",
  "type": "custom_formula",
  "formatter": "currency"
}
```

### Set a cell value

```http theme={null}
PUT /workbooks/{grid_id}/data/cells
```

**Request body**

```json theme={null}
{
  "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). |

## Related

* [Add columns](https://docs.retailgrid.io/grids/manage-columns.md)
* [Formula columns](https://docs.retailgrid.io/grids/formula-columns.md)
* [Currency](https://docs.retailgrid.io/settings/currency.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.