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

# Retailers

Retailers represent B2B retail partners for the calling merchant. Retailer records can include fulfillment defaults, retailer-specific custom fields, EDI identifiers, ship-to locations, and routing-guide metadata.

## Methods

* [retailer.list](#retailer-list)
* [retailer.info](#retailer-info)

***

## Entity Properties

* [Retailer](#retailer-properties)
* [Retailer Identifier](#identifier-properties)
* [Retailer Ship-To Location](#ship-to-location-properties)
* [Retailer Routing Guide](#routing-guide-properties)

***

## Additional Resources

* [Retailer Custom Fields](/merchant-api/retailer-custom-field) — definition metadata for Retailer `custom_fields` values.

***

## `retailer.list`

`retailer.list(filters, options, fields)`

Retrieve a paged list of Retailers for the calling merchant. Terminated Retailers are excluded unless a `status` filter is supplied or `options.include_terminated` is `true`.

### Parameters

<ParamField path="filters" type="object">
  Optional search filters. Supported fields: `retailer_id`, `code`, `name`, `status`, `fulfillment_model`, `parent_retailer_id`, `created_at`, and `updated_at`.
</ParamField>

<ParamField path="options" type="object">
  Optional [search options](/merchant-api/search-options). Supported options: `sort_field`, `sort_dir`, `page`, `limit`, and `include_terminated`.
</ParamField>

<ParamField path="fields" type="array">
  Optional list of Retailer fields to return. Use nested fields such as `identifiers`, `ship_to_locations`, and `routing_guides` only when those child records are needed.
</ParamField>

### Return Value

An object with `results`, `totalCount`, and `numPages`. Each item in `results` contains [Retailer](#retailer-properties) properties.

### Example Request

```json title="Request" theme={null}
{
    "jsonrpc" : "2.0",
    "id"      : 1234,
    "method"  : "call",
    "params"  : [
        "34aa989befe360d67fe3f70b3517a1e5",
        "retailer.list",
        [
            { "status" : "active" },
            { "sort_field" : "code", "sort_dir" : "asc", "limit" : 50 },
            ["retailer_id", "code", "name", "status", "fulfillment_model"]
        ]
    ]
}
```

### Example Response

```json title="Response" theme={null}
{
    "jsonrpc": "2.0",
    "id": 1234,
    "result": {
        "results": [
            {
                "retailer_id": 123,
                "code": "walmart",
                "name": "Walmart",
                "status": "active",
                "fulfillment_model": "wholesale"
            }
        ],
        "totalCount": 1,
        "numPages": 1
    }
}
```

## `retailer.info`

`retailer.info(code, fields)`

Retrieve one Retailer by its merchant-facing `code`. The lookup is scoped to the calling merchant.

### Parameters

<ParamField path="code" type="string" required>
  The Retailer code.
</ParamField>

<ParamField path="fields" type="array">
  Optional list of fields to return.
</ParamField>

### Return Value

An object containing [Retailer](#retailer-properties) properties.

### Example Request

```json title="Request" theme={null}
{
    "jsonrpc" : "2.0",
    "id"      : 1234,
    "method"  : "call",
    "params"  : [
        "34aa989befe360d67fe3f70b3517a1e5",
        "retailer.info",
        [
            "walmart",
            ["retailer_id", "code", "name", "identifiers", "ship_to_locations", "routing_guides"]
        ]
    ]
}
```

### Example Response

```json title="Response" theme={null}
{
    "jsonrpc": "2.0",
    "id": 1234,
    "result": {
        "retailer_id": 123,
        "code": "walmart",
        "name": "Walmart",
        "identifiers": [
            {
                "identifier_id": 456,
                "qualifier": "duns",
                "qualifier_x12": "01",
                "value": "123456789",
                "label": "Walmart DUNS",
                "is_primary": true,
                "notes": null,
                "created_at": "2026-05-28T12:00:00+00:00",
                "updated_at": "2026-05-28T12:00:00+00:00"
            }
        ],
        "ship_to_locations": [
            {
                "ship_to_location_id": 789,
                "code": "DC01",
                "location_type": "dc",
                "city": "Bentonville",
                "region": "AR",
                "country_id": "US",
                "is_default": true,
                "status": "active"
            }
        ],
        "routing_guides": [
            {
                "guide_id": 987,
                "title": "Walmart Routing Guide",
                "file_name": "walmart-routing-guide.pdf",
                "file_type": "pdf",
                "file_size": 128000,
                "uploaded_by": "Organization User: Jane Manager",
                "uploaded_at": "2026-05-28T12:00:00+00:00"
            }
        ]
    }
}
```

## Entity Properties

### Retailer Properties

<Expandable title="Retailer Properties">
  <ParamField path="retailer_id" type="integer">
    An automatically generated Retailer identifier.
  </ParamField>

  <ParamField path="code" type="string">
    The merchant-facing Retailer code. Codes are unique within a merchant.
  </ParamField>

  <ParamField path="name" type="string">
    The Retailer display name.
  </ParamField>

  <ParamField path="status" type="string">
    Retailer lifecycle status. Allowed values: `active`, `on_hold`, `terminated`.
  </ParamField>

  <ParamField path="fulfillment_model" type="string">
    Default fulfillment model. Allowed values: `wholesale`, `drop_ship`, `mixed`.
  </ParamField>

  <ParamField path="parent_retailer_id" type="integer">
    Optional parent Retailer ID.
  </ParamField>

  <ParamField path="parent_retailer_code" type="string">
    Optional parent Retailer code. Returned only when requested.
  </ParamField>

  <ParamField path="legal_name" type="string">
    Optional legal Retailer name.
  </ParamField>

  <ParamField path="dba" type="string">
    Optional doing-business-as name.
  </ParamField>

  <ParamField path="default_duties_payor" type="string">
    Optional default duties payor for future order-integration defaults. Allowed values: `shipper`, `recipient`, `third_party`.
  </ParamField>

  <ParamField path="default_shipping_method" type="string">
    Optional default shipping method identifier for future order-integration defaults.
  </ParamField>

  <ParamField path="allowed_shipping_methods" type="array">
    Optional list of shipping method identifiers allowed when this Retailer is selected.
  </ParamField>

  <ParamField path="default_tpb_group_id" type="integer">
    Optional default shipping third-party billing group ID for future order-integration defaults.
  </ParamField>

  <ParamField path="routing_guide_notes" type="string">
    Optional routing-guide notes.
  </ParamField>

  <ParamField path="custom_fields" type="object">
    Optional Retailer custom-field values keyed by custom-field code. Hidden custom fields are omitted. Currency custom fields include the merchant/global default currency. Use [Retailer Custom Fields](/merchant-api/retailer-custom-field) to retrieve field definitions.
  </ParamField>

  <ParamField path="identifiers" type="array">
    Optional array of [Retailer Identifier](#identifier-properties) objects.
  </ParamField>

  <ParamField path="ship_to_locations" type="array">
    Optional array of [Retailer Ship-To Location](#ship-to-location-properties) objects.
  </ParamField>

  <ParamField path="routing_guides" type="array">
    Optional array of [Retailer Routing Guide](#routing-guide-properties) objects.
  </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>
</Expandable>

### Retailer Identifier Properties

<Expandable title="Retailer Identifier Properties">
  <ParamField path="identifier_id" type="integer">
    An automatically generated identifier row ID.
  </ParamField>

  <ParamField path="qualifier" type="string">
    Identifier qualifier. Common values include `duns`, `gln`, `mutually_defined`, and `custom`.
  </ParamField>

  <ParamField path="qualifier_x12" type="string">
    Optional X12 qualifier code.
  </ParamField>

  <ParamField path="value" type="string">
    Identifier value.
  </ParamField>

  <ParamField path="label" type="string">
    Optional display label.
  </ParamField>

  <ParamField path="is_primary" type="boolean">
    Flag indicating the primary identifier for its qualifier.
  </ParamField>

  <ParamField path="notes" type="string">
    Optional notes.
  </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>
</Expandable>

### Retailer Ship-To Location Properties

<Expandable title="Retailer Ship-To Location Properties">
  <ParamField path="ship_to_location_id" type="integer">
    An automatically generated ship-to location row ID.
  </ParamField>

  <ParamField path="code" type="string">
    Retailer-assigned ship-to location code.
  </ParamField>

  <ParamField path="qualifier_x12" type="string">
    Optional X12 qualifier code.
  </ParamField>

  <ParamField path="label" type="string">
    Optional display label.
  </ParamField>

  <ParamField path="location_type" type="string">
    Location type. Allowed values: `dc`, `store`, `customer`, `other`.
  </ParamField>

  <ParamField path="company" type="string">
    Optional company name.
  </ParamField>

  <ParamField path="street" type="string">
    Optional street address.
  </ParamField>

  <ParamField path="city" type="string">
    Optional city.
  </ParamField>

  <ParamField path="region_id" type="integer">
    Optional ShipStream region ID.
  </ParamField>

  <ParamField path="region" type="string">
    Optional state or region value.
  </ParamField>

  <ParamField path="postcode" type="string">
    Optional postal code.
  </ParamField>

  <ParamField path="country_id" type="string">
    Optional ISO 3166-1 alpha-2 country code.
  </ParamField>

  <ParamField path="telephone" type="string">
    Optional telephone number.
  </ParamField>

  <ParamField path="email" type="string">
    Optional email address.
  </ParamField>

  <ParamField path="is_default" type="boolean">
    Flag indicating the default ship-to location for the Retailer.
  </ParamField>

  <ParamField path="status" type="string">
    Ship-to location status. Allowed values: `active`, `inactive`.
  </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>
</Expandable>

### Retailer Routing Guide Properties

<Expandable title="Retailer Routing Guide Properties">
  <ParamField path="guide_id" type="integer">
    An automatically generated routing guide row ID.
  </ParamField>

  <ParamField path="title" type="string">
    Routing guide title.
  </ParamField>

  <ParamField path="description" type="string">
    Optional routing guide description.
  </ParamField>

  <ParamField path="file_name" type="string">
    The uploaded file name.
  </ParamField>

  <ParamField path="file_type" type="string">
    The uploaded file extension or type.
  </ParamField>

  <ParamField path="file_size" type="integer">
    File size in bytes.
  </ParamField>

  <ParamField path="uploaded_by" type="string">
    Optional formatted Requester name for the uploader.
  </ParamField>

  <ParamField path="uploaded_at" type="string">
    The upload timestamp in ISO 8601 format.
  </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>
</Expandable>