Locations

Manage physical store locations, warehouses, and pickup points. Each location has its own inventory, queue, and staff assignments.

Overview

The locations API lets you manage every physical point of presence for your business. Create retail stores, warehouses, popup shops, and pickup points — each with its own address, operating hours, and contact information. Locations integrate with inventory (stock is tracked per location), customer queues (walk-in wait management), and team assignments (scheduling and permissions).

Multi-type

Retail stores, warehouses, popups, and pickup points — all managed in one place.

Per-location inventory

Each location maintains independent stock levels, transfers, and audits.

Customer queue

Walk-in queue management with estimated wait times and position tracking.

Staff assignments

Assign team members to locations for scheduling, permissions, and reporting.

Create a Location

Create a new location with an address, type, contact details, and operating hours. The location is immediately available for inventory tracking, queue management, and staff assignments.

const whale = new WhaleClient("wk_live_...");

const location = await whale.locations.create({
  name: "Downtown Flagship",
  address: {
    line1: "123 Main Street",
    city: "Austin",
    state: "TX",
    postal_code: "78701",
    country: "US"
  },
  type: "retail",
  phone: "+1-512-555-0199",
  hours: {
    monday: { open: "09:00", close: "21:00" },
    tuesday: { open: "09:00", close: "21:00" },
    wednesday: { open: "09:00", close: "21:00" },
    thursday: { open: "09:00", close: "21:00" },
    friday: { open: "09:00", close: "22:00" },
    saturday: { open: "10:00", close: "22:00" },
    sunday: { open: "10:00", close: "18:00" }
  }
});

// Response
{
  "object": "location",
  "id": "loc_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Downtown Flagship",
  "type": "retail",
  "status": "active",
  "address": {
    "line1": "123 Main Street",
    "city": "Austin",
    "state": "TX",
    "postal_code": "78701",
    "country": "US"
  },
  "phone": "+1-512-555-0199",
  "created_at": "2026-03-10T08:00:00.000Z"
}

Location Types

Each location has a type that determines its role in your business. Use the type to filter locations and configure type-specific behavior.

Type	Description	Use case
retail	Physical store open to customers	Storefronts, boutiques, showrooms
warehouse	Storage and fulfillment facility	Bulk storage, shipping hubs, distribution centers
popup	Temporary or seasonal location	Markets, festivals, seasonal shops
pickup	Collection point for online orders	BOPIS, curbside pickup, locker stations

Customer Queue

Manage walk-in customers with a real-time queue. Add customers when they arrive, track their position, and get estimated wait times based on average service duration. Queue entries move through statuses: waiting, serving, completed, or no_show.

// Add a customer to the queue
const entry = await whale.locations.queue.add(
  "loc_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  {
    customer_name: "Jordan Mitchell",
    party_size: 2,
    notes: "Interested in the new collection"
  }
);

// Response
{
  "object": "queue_entry",
  "id": "que_b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "location_id": "loc_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customer_name": "Jordan Mitchell",
  "party_size": 2,
  "status": "waiting",
  "position": 3,
  "estimated_wait": "12 min",
  "joined_at": "2026-03-10T14:22:00.000Z"
}

// Mark as now being served
await whale.locations.queue.update(entry.id, {
  status: "serving"
});

Staff Assignment

Assign team members to locations for scheduling and permissions. Staff assignments determine which locations a team member can access in POS, inventory management, and reporting. A team member can be assigned to multiple locations.

// Assign a team member to a location
await whale.locations.staff.assign({
  location_id: "loc_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  user_id: "usr_c3d4e5f6-a7b8-9012-cdef-234567890abc",
  role: "manager"
});

// List staff at a location
const staff = await whale.locations.staff.list({
  location_id: "loc_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
});

// Response
{
  "object": "list",
  "data": [
    {
      "id": "ls_d4e5f6a7-b8c9-0123-defg-345678901bcd",
      "location_id": "loc_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "user_id": "usr_c3d4e5f6-a7b8-9012-cdef-234567890abc",
      "name": "Alex Rivera",
      "role": "manager",
      "assigned_at": "2026-03-10T09:00:00.000Z"
    },
    {
      "id": "ls_e5f6a7b8-c9d0-1234-efgh-456789012cde",
      "location_id": "loc_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "user_id": "usr_d4e5f6a7-b8c9-0123-defg-345678901bcd",
      "name": "Sam Chen",
      "role": "associate",
      "assigned_at": "2026-03-10T09:05:00.000Z"
    }
  ]
}

API Reference

Method	Path	Description
GET	/v1/stores/{store_id}/locations	List all locations. Filter by type or status.
GET	/v1/stores/{store_id}/locations/{id}	Get a single location with address and hours.
POST	/v1/stores/{store_id}/locations	Create a new location.
PATCH	/v1/stores/{store_id}/locations/{id}	Update location details, hours, or status.
DELETE	/v1/stores/{store_id}/locations/{id}	Archive a location. Inventory must be transferred first.
GET	/v1/stores/{store_id}/location-queue	List queue entries for a location. Filter by status.
POST	/v1/stores/{store_id}/location-queue	Add a customer to the queue at a location.
PATCH	/v1/stores/{store_id}/location-queue/{id}	Update queue entry status (serving, completed, no-show).
DELETE	/v1/stores/{store_id}/location-queue/{id}	Remove a customer from the queue.
GET	/v1/stores/{store_id}/location-staff	List staff assignments. Filter by location_id or user_id.
POST	/v1/stores/{store_id}/location-staff	Assign a team member to a location.
DELETE	/v1/stores/{store_id}/location-staff/{id}	Remove a staff assignment from a location.