> ## 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](https://docs.shipstream.io/merchant-api/retailer.md#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

**Retailer Custom Field Properties**

**custom\_field\_id** `integer`

An automatically generated unique identifier for a Retailer Custom Field.

**name** `string`

The display name of the Retailer Custom Field.

**code** `string`

The custom-field code. This is the key used in Retailer `custom_fields` values.

**is\_active** `integer`

Flag whether the Retailer Custom Field is active.

**input\_type** `string`

The input type. Allowed values: "text", "multiline-text", "number", "currency", "select", "multiselect", "boolean", "date", "client-user", "admin-user", "email", "url".

**is\_required** `integer`

Flag whether the Retailer Custom Field is required.

**client\_note** `string`

Optional note shown to API clients.

**client\_permissions** `string`

Client-side permission mode. Allowed values: "unrestricted", "restricted", "read-only", "hidden".

**is\_display\_client\_grid** `integer`

Flag whether the Retailer Custom Field is displayed in the client grid.

**is\_display\_client\_form** `integer`

Flag whether the Retailer Custom Field is displayed in the client form.

**sort\_order** `integer`

Display sort order.

**created\_at** `string`

The creation timestamp in ISO 8601 format.

**updated\_at** `string`

The last update timestamp in ISO 8601 format.

**options** `array`

Array of options for `select` and `multiselect` fields. See [Option Properties](#option-properties).

### Retailer Custom Field Option Properties

**Retailer Custom Field Option Properties**

**option\_id** `integer`

The internal option ID.

**label** `string`

The option label.

**is\_default** `boolean`

Flag whether the option is default.

**sort\_order** `integer`

The option sort order.


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