> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipstream.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Retailer Custom Fields

Retailer custom-field definitions describe the `custom_fields` object returned by Retailer API methods. Use this endpoint to discover field codes, input types, permissions, display flags, and options for the calling merchant.

## Methods

* [retailer\_custom\_field.list](#retailer-custom-field-list)

***

## Entity Properties

* [Retailer Custom Field](#field-properties)
* [Retailer Custom Field Option](#option-properties)

***

## Additional Resources

* [Retailers](/merchant-api/retailer#retailer-properties) — when submitting or receiving Retailer custom-field values.

***

## `retailer_custom_field.list`

`retailer_custom_field.list()`

Retrieve list of retailer custom fields available for the calling merchant. Global definitions are included, and merchant-specific definitions are returned for the calling merchant.

### Return Value

An array of objects. Each object will contain [Retailer Custom Field](#field-properties) properties.

### Example Request

```json title="Request" theme={null}
{
    "jsonrpc" : "2.0",
    "id"      : 1234,
    "method"  : "call",
    "params"  : [
        "34aa989befe360d67fe3f70b3517a1e5",
        "retailer_custom_field.list"
    ]
}
```

### Example Response

```json title="Response" theme={null}
{
    "result": [
        {
            "custom_field_id": "12",
            "name": "Retailer Department",
            "code": "retailer_department",
            "is_active": "1",
            "input_type": "select",
            "is_required": "0",
            "client_note": "Department used for retailer reporting.",
            "client_permissions": "unrestricted",
            "is_display_client_grid": "1",
            "is_display_client_form": "1",
            "sort_order": "10",
            "created_at": "2026-05-28T12:00:00+00:00",
            "updated_at": "2026-05-28T12:00:00+00:00",
            "options": [
                {
                    "option_id": 31,
                    "label": "Grocery",
                    "is_default": true,
                    "sort_order": 10
                },
                {
                    "option_id": 32,
                    "label": "Apparel",
                    "is_default": false,
                    "sort_order": 20
                }
            ]
        },
        {
            "custom_field_id": "13",
            "name": "Routing Region",
            "code": "routing_region",
            "is_active": "1",
            "input_type": "text",
            "is_required": "0",
            "client_note": null,
            "client_permissions": "restricted",
            "is_display_client_grid": "0",
            "is_display_client_form": "1",
            "sort_order": "20",
            "created_at": "2026-05-28T12:00:00+00:00",
            "updated_at": "2026-05-28T12:00:00+00:00"
        }
    ],
    "id": "1234",
    "jsonrpc": "2.0"
}
```

## Entity Properties

### Retailer Custom Field Properties

<Expandable title="Retailer Custom Field Properties">
  <ParamField path="custom_field_id" type="integer">
    An automatically generated unique identifier for a Retailer Custom Field.
  </ParamField>

  <ParamField path="name" type="string">
    The display name of the Retailer Custom Field.
  </ParamField>

  <ParamField path="code" type="string">
    The custom-field code. This is the key used in Retailer `custom_fields` values.
  </ParamField>

  <ParamField path="is_active" type="integer">
    Flag whether the Retailer Custom Field is active.
  </ParamField>

  <ParamField path="input_type" type="string">
    The input type. Allowed values: "text", "multiline-text", "number", "currency", "select", "multiselect", "boolean", "date", "client-user", "admin-user", "email", "url".
  </ParamField>

  <ParamField path="is_required" type="integer">
    Flag whether the Retailer Custom Field is required.
  </ParamField>

  <ParamField path="client_note" type="string">
    Optional note shown to API clients.
  </ParamField>

  <ParamField path="client_permissions" type="string">
    Client-side permission mode. Allowed values: "unrestricted", "restricted", "read-only", "hidden".
  </ParamField>

  <ParamField path="is_display_client_grid" type="integer">
    Flag whether the Retailer Custom Field is displayed in the client grid.
  </ParamField>

  <ParamField path="is_display_client_form" type="integer">
    Flag whether the Retailer Custom Field is displayed in the client form.
  </ParamField>

  <ParamField path="sort_order" type="integer">
    Display sort order.
  </ParamField>

  <ParamField path="created_at" type="string">
    The creation timestamp in ISO 8601 format.
  </ParamField>

  <ParamField path="updated_at" type="string">
    The last update timestamp in ISO 8601 format.
  </ParamField>

  <ParamField path="options" type="array">
    Array of options for `select` and `multiselect` fields. See [Option Properties](#option-properties).
  </ParamField>
</Expandable>

### Retailer Custom Field Option Properties

<Expandable title="Retailer Custom Field Option Properties">
  <ParamField path="option_id" type="integer">
    The internal option ID.
  </ParamField>

  <ParamField path="label" type="string">
    The option label.
  </ParamField>

  <ParamField path="is_default" type="boolean">
    Flag whether the option is default.
  </ParamField>

  <ParamField path="sort_order" type="integer">
    The option sort order.
  </ParamField>
</Expandable>