> ## 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](/grids/manage-columns).
</Note>

## 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](/settings/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. |

<Note>
  Grouping and aggregation are not available for formula columns.
</Note>

## 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.
</Note>

### 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](/grids/manage-columns)
* [Formula columns](/grids/formula-columns)
* [Currency](/settings/currency)