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.

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:

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:

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.

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.

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.

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.