# Warehouses

Find, create, maintain, archive, and restore physical warehouses.

Canonical HTML: https://developer.shelfcycle.com/guides/warehouses

Find, create, maintain, archive, and restore the physical warehouses used by connected inventory workflows.

Use the warehouse directory to keep names, source identifiers, addresses, and contacts aligned between ShelfCycle and connected systems. Warehouse responses include `updatedAt` for precise updates and lifecycle changes.

## Access

Reads require `warehouses:read`. Creates, updates, archive, and restore actions require `warehouses:write` plus the acting person's current organization access. `GET /me` reports the available actions through `effectiveCapabilities.warehouses` and `effectiveCapabilities.writeReadiness.warehouses`.

## Find warehouses

`GET /warehouses` returns active physical warehouses by default.

```bash
curl "$SHELFCYCLE_API_BASE_URL/warehouses?q=main&limit=25" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"
```

Use `q` for a name search or `externalId` for one exact source identifier. Set `includeArchived=true` when reconciling retired locations, or `includeDirectShip=true` when a workflow also needs Direct Ship locations for reference.

When `meta.hasMore` is true, continue with the returned cursor by itself:

```bash
curl "$SHELFCYCLE_API_BASE_URL/warehouses?cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"
```

Read one known warehouse with `GET /warehouses/{id}`.

## Create a warehouse

Create accepts a required `name` plus address, contact, and source-identity fields. A stable `externalId` makes repeated source-driven requests safe; otherwise, provide an `Idempotency-Key`.

Preview:

```bash
curl "$SHELFCYCLE_API_BASE_URL/warehouses?dryRun=true" \
  -X POST \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Northeast Distribution Center",
    "street1": "410 Harbor Way",
    "city": "Newark",
    "state": "NJ",
    "zip": "07114",
    "country": "US",
    "phone": "973-555-0100",
    "email": "receiving@example.com",
    "contactName": "Receiving Team",
    "externalId": "WMS-NE-01"
  }'
```

Apply the same request without `dryRun=true`. Repeating the same `externalId` and fields returns the existing warehouse unchanged. A different request using an existing `externalId` returns the existing warehouse ID so the source record can be reconciled.

## Update warehouse details

Read the warehouse first, then send the latest `updatedAt` value in `If-Match`.

```bash
curl "$SHELFCYCLE_API_BASE_URL/warehouses/warehouse-id" \
  -X PATCH \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "2026-09-12T14:30:00.000Z"' \
  -d '{
    "contactName": "Alex Rivera",
    "email": "alex.rivera@example.com"
  }'
```

The same fields can be previewed with `dryRun=true` before they are saved.

## Archive and restore

Archive a warehouse that is no longer used for new setup while preserving its identity and existing history. Both actions use an empty body and the latest `updatedAt` value.

```bash
curl "$SHELFCYCLE_API_BASE_URL/warehouses/warehouse-id/archive?dryRun=true" \
  -X POST \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H 'If-Match: "2026-09-12T14:30:00.000Z"' \
  -H "Content-Type: application/json" \
  -d '{}'
```

Remove `dryRun=true` to apply the archive. To restore the location, call `/warehouses/{id}/unarchive` with its latest `updatedAt` value.

## Resolve a warehouse name

Entity Resolution accepts `class: "warehouse"` and returns stable warehouse IDs for familiar names. It uses `search:read` together with the acting person's current Lot viewing access.

```bash
curl "$SHELFCYCLE_API_BASE_URL/entity-resolution?q=Northeast%20DC&class=warehouse" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"
```

Use the selected warehouse ID with inventory balances, reorder status, reorder-point maintenance, pricing, and other warehouse-aware workflows.