> ## 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](#retailer-identifier-properties)
* [Retailer Ship-To Location](#retailer-ship-to-location-properties)
* [Retailer Routing Guide](#retailer-routing-guide-properties)

***

## Additional Resources

* [Retailer Custom Fields](https://docs.shipstream.io/merchant-api/retailer-custom-field.md) — 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

**filters** `object`

Optional search filters. Supported fields: `retailer_id`, `code`, `name`, `status`, `fulfillment_model`, `parent_retailer_id`, `created_at`, and `updated_at`.

**options** `object`

Optional [search options](https://docs.shipstream.io/merchant-api/search-options.md). Supported options: `sort_field`, `sort_dir`, `page`, `limit`, and `include_terminated`.

**fields** `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.

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

**code** `string` *required*

The Retailer code.

**fields** `array`

Optional list of fields to return.

### 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",
                "value": "123456789",
                "label": "Walmart DUNS",
                "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",
                "qualifier": "gln",
                "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

**Retailer Properties**

**retailer\_id** `integer`

An automatically generated Retailer identifier.

**code** `string`

The merchant-facing Retailer code. Codes are unique within a merchant.

**name** `string`

The Retailer display name.

**status** `string`

Retailer lifecycle status. Allowed values: `active`, `on_hold`, `terminated`.

**fulfillment\_model** `string`

Default fulfillment model. Allowed values: `wholesale`, `drop_ship`, `mixed`.

**parent\_retailer\_id** `integer`

Optional parent Retailer ID.

**parent\_retailer\_code** `string`

Optional parent Retailer code. Returned only when requested.

**legal\_name** `string`

Optional legal Retailer name.

**dba** `string`

Optional doing-business-as name.

**default\_duties\_payor** `string`

Optional default duties payor for future order-integration defaults. Allowed values: `shipper`, `recipient`, `third_party`.

**default\_shipping\_method** `string`

Optional default shipping method identifier for future order-integration defaults.

**allowed\_shipping\_methods** `array`

Optional list of shipping method identifiers allowed when this Retailer is selected.

**default\_tpb\_group\_id** `integer`

Optional default shipping third-party billing group ID for future order-integration defaults.

**routing\_guide\_notes** `string`

Optional routing-guide notes.

**custom\_fields** `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](https://docs.shipstream.io/merchant-api/retailer-custom-field.md) to retrieve field definitions.

**identifiers** `array`

Optional array of [Retailer Identifier](#retailer-identifier-properties) objects.

**ship\_to\_locations** `array`

Optional array of [Retailer Ship-To Location](#retailer-ship-to-location-properties) objects.

**routing\_guides** `array`

Optional array of [Retailer Routing Guide](#retailer-routing-guide-properties) objects.

**created\_at** `string`

The creation timestamp in ISO 8601 format.

**updated\_at** `string`

The last update timestamp in ISO 8601 format.

### Retailer Identifier Properties

**Retailer Identifier Properties**

**identifier\_id** `integer`

An automatically generated identifier row ID.

**qualifier** `string`

Identifier qualifier. Common values include `duns`, `gln`, `mutually_defined`, and `custom`.

**value** `string`

Identifier value.

**label** `string`

Optional display label.

**notes** `string`

Optional notes.

**created\_at** `string`

The creation timestamp in ISO 8601 format.

**updated\_at** `string`

The last update timestamp in ISO 8601 format.

### Retailer Ship-To Location Properties

**Retailer Ship-To Location Properties**

**ship\_to\_location\_id** `integer`

An automatically generated ship-to location row ID.

**code** `string` *required*

Retailer-assigned ship-to location code.

**qualifier** `string` *required*

The canonical scheme that identifies the location code. EDI qualifiers are normalized to this set. Allowed values: `duns`, `duns_plus_4`, `gln`, `buyer_location`, `seller_location`, `third_party_location`, `plant_code`, `dodaac`, `cage`, `dea`, `hin`, `san`, `approver_id`, `clli`, `census_schedule_d`, `census_schedule_k`.

**label** `string`

Optional display label.

**location\_type** `string`

Location type. Allowed values: `dc`, `store`, `drop_ship`, `other`.

**company** `string`

Optional company name.

**street** `string`

Optional street address.

**city** `string`

Optional city.

**region\_id** `integer`

Optional ShipStream region ID.

**region** `string`

Optional state or region value.

**postcode** `string`

Optional postal code.

**country\_id** `string`

Optional ISO 3166-1 alpha-2 country code.

**telephone** `string`

Optional telephone number.

**email** `string`

Optional email address.

**is\_default** `boolean`

Flag indicating the default ship-to location for the Retailer.

**status** `string`

Ship-to location status. Allowed values: `active`, `inactive`.

**created\_at** `string`

The creation timestamp in ISO 8601 format.

**updated\_at** `string`

The last update timestamp in ISO 8601 format.

### Retailer Routing Guide Properties

**Retailer Routing Guide Properties**

**guide\_id** `integer`

An automatically generated routing guide row ID.

**title** `string`

Routing guide title.

**description** `string`

Optional routing guide description.

**file\_name** `string`

The uploaded file name.

**file\_type** `string`

The uploaded file extension or type.

**file\_size** `integer`

File size in bytes.

**uploaded\_by** `string`

Optional formatted Requester name for the uploader.

**uploaded\_at** `string`

The upload timestamp in ISO 8601 format.

**created\_at** `string`

The creation timestamp in ISO 8601 format.

**updated\_at** `string`

The last update timestamp in ISO 8601 format.


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