Warehouse API

The Warehouse API provides endpoints for managing warehouses and their hierarchical structure, addresses, and contact information within stores.

All Warehouse API endpoints require authentication and a valid x-store-id header to identify the store context, unless stated otherwise.

Overview

Warehouses can be:

Created with required address information and optional contact details
Organized in hierarchical structures using parent-child relationships
Filtered and sorted by various criteria
Retrieved in paginated lists or individually by ID
Updated with partial updates for flexible editing
Deleted when no longer needed

Endpoint Details

Base URL: https://jethings-backend.fly.dev
Content-Type: application/json

Required Headers

Authorization: Bearer <token>
x-store-id: <store_id>

All routes require a valid x-store-id header. Users must have an active relation with the store to access its warehouses.

Get All Warehouses

GET /warehouses Retrieve a paginated list of warehouses for the store that the authenticated user has access to. Requires Authentication: Bearer token in Authorization header

Required Headers

Key	Value	Required	Description
`x-store-id`	`string`	Yes	Store identifier (used by `@StoreId()` decorator)

Query Parameters

Parameter	Type	Required	Description	Default
`search`	`string`	No	Filter by warehouse name (partial match)	—
`name`	`string`	No	Filter by specific warehouse name (partial match)	—
`parentId`	`string`	No	Filter by parent warehouse ID (for hierarchical filtering)	—
`isActive`	`boolean`	No	Filter by active/inactive status	—
`page`	`number`	No	Page number (1-based)	`1`
`limit`	`number`	No	Number of items per page (1–100)	`10`
`sortBy`	`string`	No	Sort field (`id`, `name`, `isActive`, `updatedAt`, `createdAt`)	`createdAt`
`sortOrder`	`string`	No	Sort direction (`asc` or `desc`)	`desc`

Success Response

Status Code: 200 OK

{
  "data": [
    {
      "id": "warehouse_123",
      "storeId": "store_456",
      "parentId": null,
      "name": "Main Warehouse",
      "email": "warehouse@company.com",
      "isActive": true,
      "isGrouped": false,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": "warehouse_124",
      "storeId": "store_456",
      "parentId": "warehouse_123",
      "name": "North Branch",
      "email": "north@company.com",
      "isActive": true,
      "isGrouped": true,
      "createdAt": "2024-01-16T09:20:00.000Z",
      "updatedAt": "2024-01-16T09:20:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 25,
    "totalPages": 3,
    "hasNext": true,
    "hasPrev": false
  }
}

Response Fields

Warehouse Object

Field	Type	Description
`id`	`string`	Unique warehouse ID
`storeId`	`string`	ID of the store that owns this warehouse
`parentId`	`string?`	ID of the parent warehouse (for hierarchical structure)
`name`	`string`	Warehouse display name
`email`	`string?`	Email address of the warehouse
`isActive`	`boolean`	Active status
`isGrouped`	`boolean`	Whether the warehouse is grouped (has a parent)
`createdAt`	`string`	Creation timestamp (ISO 8601)
`updatedAt`	`string`	Last update timestamp (ISO 8601)

Pagination Object

Field	Type	Description
`page`	`number`	Current page number
`limit`	`number`	Number of items per page
`total`	`number`	Total number of records
`totalPages`	`number`	Total pages available
`hasNext`	`boolean`	Whether a next page exists
`hasPrev`	`boolean`	Whether a previous page exists

Possible Errors

Code	Message
403	Forbidden - User does not have access to store
500	Internal Server Error

Example Requests

curl -X GET "https://jethings-backend.fly.dev/warehouses?page=1&limit=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-store-id: store_id_here"

const params = new URLSearchParams({
  page: "1",
  limit: "10",
  sortBy: "name",
  sortOrder: "asc"
})

const response = await fetch(`https://jethings-backend.fly.dev/warehouses?${params}`, {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "x-store-id": "store_id_here"
  }
})

const result = await response.json()

import requests

url = "https://jethings-backend.fly.dev/warehouses"

params = {
    "page": 1,
    "limit": 10,
    "sortBy": "name",
    "sortOrder": "asc"
}

response = requests.get(
    url,
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "x-store-id": "store_id_here"
    },
    params=params
)

print(response.json())

Search warehouses by name:

curl -X GET "https://jethings-backend.fly.dev/warehouses?search=main&page=1&limit=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-store-id: store_id_here"

Filter by parent warehouse:

curl -X GET "https://jethings-backend.fly.dev/warehouses?parentId=warehouse_123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-store-id: store_id_here"

Get Single Warehouse

GET /warehouses/:id Retrieve a single warehouse by its ID. Requires Authentication: Bearer token in Authorization header

Path Parameters

Parameter	Type	Required	Description
`id`	`string`	✅ Yes	Warehouse ID

Success Response

Status Code: 200 OK

{
  "id": "warehouse_123",
  "storeId": "store_456",
  "parentId": null,
  "name": "Main Warehouse",
  "email": "warehouse@company.com",
  "isActive": true,
  "isGrouped": false,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

Response Fields

Same as the warehouse object in the “Get All Warehouses” endpoint.

Possible Errors

Code	Message
404	Not Found - Warehouse not found
500	Internal Server Error

Example Requests

curl -X GET "https://jethings-backend.fly.dev/warehouses/warehouse_123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

const response = await fetch("https://jethings-backend.fly.dev/warehouses/warehouse_123", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
  }
})

const result = await response.json()

import requests

url = "https://jethings-backend.fly.dev/warehouses/warehouse_123"

response = requests.get(
    url,
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)

print(response.json())

Create Warehouse

POST /warehouses Create a new warehouse with address information and optional contact details. Requires Authentication: Bearer token in Authorization header

Required Headers

Key	Value	Required	Description
`x-store-id`	`string`	Yes	Store identifier (used by `@StoreId()` decorator)

Request Body

Field	Type	Required	Description
`name`	`string`	✅ Yes	Warehouse name (max 255 characters)
`parentId`	`string`	No	ID of parent warehouse (for hierarchical structure)
`street`	`string`	✅ Yes	Street address (max 500 characters)
`city`	`string`	✅ Yes	City (max 100 characters)
`state`	`string`	✅ Yes	State or province (max 100 characters)
`country`	`string`	✅ Yes	Country (max 100 characters)
`postalCode`	`string`	✅ Yes	Postal or ZIP code (max 20 characters)
`contactPerson`	`string`	No	Contact person name (max 255 characters)
`phone`	`string`	No	Phone number (max 50 characters)
`email`	`string`	No	Email address (max 255 characters, must be valid email)

Request Body Example

{
  "name": "Main Warehouse",
  "parentId": null,
  "street": "123 Industrial Boulevard",
  "city": "New York",
  "state": "NY",
  "country": "United States",
  "postalCode": "10001",
  "contactPerson": "John Smith",
  "phone": "+1-555-123-4567",
  "email": "warehouse@company.com"
}

Success Response

Status Code: 201 Created

{
  "id": "warehouse_123",
  "storeId": "store_456",
  "parentId": null,
  "name": "Main Warehouse",
  "email": "warehouse@company.com",
  "isActive": true,
  "isGrouped": false,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

Possible Errors

Code	Message
400	Bad Request - Validation errors
403	Forbidden - User does not have access to store
404	Not Found - Store not found
500	Internal Server Error

Example Requests

curl -X POST "https://jethings-backend.fly.dev/warehouses" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-store-id: store_id_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main Warehouse",
    "street": "123 Industrial Boulevard",
    "city": "New York",
    "state": "NY",
    "country": "United States",
    "postalCode": "10001",
    "phone": "+1-555-123-4567",
    "email": "warehouse@company.com"
  }'

const warehouseData = {
  name: "Main Warehouse",
  street: "123 Industrial Boulevard",
  city: "New York",
  state: "NY",
  country: "United States",
  postalCode: "10001",
  phone: "+1-555-123-4567",
  email: "warehouse@company.com"
}

const response = await fetch("https://jethings-backend.fly.dev/warehouses", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "x-store-id": "store_id_here",
    "Content-Type": "application/json"
  },
  body: JSON.stringify(warehouseData)
})

const result = await response.json()

import requests

url = "https://jethings-backend.fly.dev/warehouses"

warehouse_data = {
    "name": "Main Warehouse",
    "street": "123 Industrial Boulevard",
    "city": "New York",
    "state": "NY",
    "country": "United States",
    "postalCode": "10001",
    "phone": "+1-555-123-4567",
    "email": "warehouse@company.com"
}

response = requests.post(
    url,
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "x-store-id": "store_id_here",
        "Content-Type": "application/json"
    },
    json=warehouse_data
)

print(response.json())

When creating a warehouse, the system automatically:

Creates an address record with the provided address information
Creates a contact record if phone, email, or contactPerson is provided
Links the warehouse to the authenticated user’s store
Sets isGrouped to true if parentId is provided, otherwise false

Update Warehouse

PUT /warehouses/:id Update an existing warehouse. Supports partial updates - only provided fields will be updated. Requires Authentication: Bearer token in Authorization header

Path Parameters

Parameter	Type	Required	Description
`id`	`string`	✅ Yes	Warehouse ID

Request Body

All fields are optional (partial updates supported):

Field	Type	Required	Description
`name`	`string`	No	Warehouse name (max 255 characters)
`parentId`	`string`	No	ID of parent warehouse (set to `null` to remove parent)
`street`	`string`	No	Street address (max 500 characters)
`city`	`string`	No	City (max 100 characters)
`state`	`string`	No	State or province (max 100 characters)
`country`	`string`	No	Country (max 100 characters)
`postalCode`	`string`	No	Postal or ZIP code (max 20 characters)
`phone`	`string`	No	Phone number (max 50 characters)
`email`	`string`	No	Email address (max 255 characters, must be valid email)

Request Body Example

{
  "name": "Updated Warehouse Name",
  "city": "Los Angeles",
  "state": "CA",
  "email": "newemail@company.com"
}

Success Response

Status Code: 200 OK

{
  "id": "warehouse_123",
  "storeId": "store_456",
  "parentId": null,
  "name": "Updated Warehouse Name",
  "email": "newemail@company.com",
  "isActive": true,
  "isGrouped": false,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T11:45:00.000Z"
}

Possible Errors

Code	Message
400	Bad Request - Validation errors
403	Forbidden - User does not have access to warehouse
404	Not Found - Warehouse not found
500	Internal Server Error

Example Requests

curl -X PUT "https://jethings-backend.fly.dev/warehouses/warehouse_123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Warehouse Name",
    "city": "Los Angeles",
    "state": "CA"
  }'

const updateData = {
  name: "Updated Warehouse Name",
  city: "Los Angeles",
  state: "CA"
}

const response = await fetch("https://jethings-backend.fly.dev/warehouses/warehouse_123", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify(updateData)
})

const result = await response.json()

import requests

url = "https://jethings-backend.fly.dev/warehouses/warehouse_123"

update_data = {
    "name": "Updated Warehouse Name",
    "city": "Los Angeles",
    "state": "CA"
}

response = requests.put(
    url,
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Content-Type": "application/json"
    },
    json=update_data
)

print(response.json())

When updating a warehouse:

Only provided fields are updated (partial updates supported)
Address fields are updated in the linked address record
Contact fields are updated in the linked contact record, or a new contact record is created if one doesn’t exist
Setting parentId to null removes the parent relationship
The updatedAt timestamp is automatically updated

Delete Warehouse

DELETE /warehouses/:id Delete a warehouse by its ID. This is a permanent deletion. Requires Authentication: Bearer token in Authorization header

Path Parameters

Parameter	Type	Required	Description
`id`	`string`	✅ Yes	Warehouse ID

Success Response

Status Code: 200 OK

{
  "id": "warehouse_123",
  "storeId": "store_456",
  "parentId": null,
  "name": "Main Warehouse",
  "email": "warehouse@company.com",
  "isActive": true,
  "isGrouped": false,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

Possible Errors

Code	Message
403	Forbidden - User does not have access to warehouse
404	Not Found - Warehouse not found
500	Internal Server Error

Example Requests

curl -X DELETE "https://jethings-backend.fly.dev/warehouses/warehouse_123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

const response = await fetch("https://jethings-backend.fly.dev/warehouses/warehouse_123", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
  }
})

const result = await response.json()

import requests

url = "https://jethings-backend.fly.dev/warehouses/warehouse_123"

response = requests.delete(
    url,
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)

print(response.json())

This operation permanently deletes the warehouse. Make sure to verify the warehouse ID before deletion. Consider checking for dependent records (like inventory items) before deleting.

Business Logic

Warehouse Creation Flow

Address Management

Address ManagementWhen creating a warehouse:

A new address record is always created with the provided address information
All address fields (street, city, state, country, postalCode) are required
The address is automatically linked to the warehouse via addressId
Address can be updated independently when updating the warehouse

Contact Management

Contact ManagementContact information is optional:

A contact record is only created if at least one contact field (phone, email, contactPerson) is provided
If contact is provided, it’s automatically linked to the warehouse via contactId
When updating, if contact doesn’t exist and contact fields are provided, a new contact record is created
Contact fields can be updated independently of other warehouse fields

Hierarchical Structure

Hierarchical StructureWarehouses can be organized hierarchically:

Set parentId to create a child warehouse under a parent
isGrouped is automatically set to true if parentId exists, false otherwise
Useful for organizing warehouses by location, type, or business unit
Filter by parentId to get all child warehouses of a specific parent
Set parentId to null to remove the parent relationship

Store Access Validation

Store Access ValidationAccess control is enforced:

User must have an active relation with the store to access its warehouses
Store access is validated on every request
Users can only create/update/delete warehouses for stores they have access to
Warehouse operations are scoped to the authenticated user’s accessible stores

Partial Updates

Partial UpdatesThe update endpoint supports flexible partial updates:

Only provided fields are updated
Address fields can be updated independently
Contact fields can be updated independently
Warehouse fields (name, parentId) can be updated independently
This allows fine-grained control over what gets updated

Warehouse States

Active Warehouse

Active (isActive: true)
Warehouse is currently in use and available for operations

Grouped Warehouse

Grouped (isGrouped: true)
Warehouse has a parent warehouse (part of hierarchical structure)

Standalone Warehouse

Standalone (isGrouped: false)
Warehouse has no parent (top-level warehouse)

With Contact

Contact Information
Warehouse has associated contact details (phone, email)

Error Responses

All endpoints may return standard HTTP error codes:

400 Bad Request - Invalid request parameters or body
403 Forbidden - User does not have access to the store or warehouse
404 Not Found - Resource not found (warehouse, store, etc.)
500 Internal Server Error - Server error

Error Response Format

{
  "statusCode": 403,
  "message": "You do not have access to this store",
  "error": "Forbidden"
}

Common Error Scenarios

403 Forbidden - Store Access

{
  "statusCode": 403,
  "message": "You do not have access to this store"
}

Occurs when the user doesn’t have an active relation with the specified store. 404 Not Found - Warehouse

{
  "statusCode": 404,
  "message": "Warehouse not found"
}

Occurs when the warehouse ID doesn’t exist or doesn’t belong to an accessible store. 400 Bad Request - Validation Error

{
  "statusCode": 400,
  "message": ["name must be a string", "street must be a string"],
  "error": "Bad Request"
}

Occurs when required fields are missing or data types are incorrect.

Usage Examples

Example 1: Create a top-level warehouse

curl -X POST "https://jethings-backend.fly.dev/warehouses" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-store-id: store_id_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main Warehouse",
    "street": "123 Industrial Boulevard",
    "city": "New York",
    "state": "NY",
    "country": "United States",
    "postalCode": "10001",
    "email": "warehouse@company.com"
  }'

Example 2: Create a child warehouse

curl -X POST "https://jethings-backend.fly.dev/warehouses" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-store-id: store_id_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "North Branch",
    "parentId": "warehouse_123",
    "street": "456 North Avenue",
    "city": "Boston",
    "state": "MA",
    "country": "United States",
    "postalCode": "02101",
    "phone": "+1-555-987-6543"
  }'

Example 3: Get warehouses with filtering

curl -X GET "https://jethings-backend.fly.dev/warehouses?parentId=warehouse_123&isActive=true&page=1&limit=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-store-id: store_id_here"

Example 4: Update warehouse address only

curl -X PUT "https://jethings-backend.fly.dev/warehouses/warehouse_123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "street": "789 New Street",
    "city": "Philadelphia",
    "state": "PA",
    "postalCode": "19101"
  }'

Example 5: Remove parent relationship

curl -X PUT "https://jethings-backend.fly.dev/warehouses/warehouse_124" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parentId": null
  }'

Best Practices

Warehouse Organization

Use hierarchical structure to organize warehouses by location or business unit
Create top-level warehouses for major locations
Use child warehouses for branches or sub-locations
Keep warehouse names descriptive and consistent

Address Management

Always provide complete address information for accurate location tracking
Use consistent address formats across warehouses
Update addresses when warehouses relocate
Validate postal codes match the country format

Contact Information

Provide contact information for easy communication
Keep email addresses up to date for notifications
Include phone numbers for urgent matters
Update contact information when personnel changes

Pagination

Use pagination when fetching large lists of warehouses
Default limit of 10 is suitable for most use cases
Maximum limit of 100 should be used sparingly
Always check hasNext and hasPrev for navigation

Filtering and Search

Use search for general name searches
Use name for specific name filtering
Use parentId to get all child warehouses
Combine filters for precise results

Partial Updates

Only send fields that need to be updated
Update address and contact information independently when possible
Use partial updates to avoid overwriting unchanged data
Verify warehouse ID before updating

Deletion

Verify warehouse ID before deletion
Check for dependent records (inventory, stock reconciliations) before deleting
Consider the impact on child warehouses before deleting a parent
Deletion is permanent and cannot be undone

Warehouses work in conjunction with other inventory management endpoints:

Stock Reconciliation API (/stock-reconciliation) - Reconcile inventory for specific warehouses
Purchase Invoice API (/purchase-invoices) - Create purchase invoices linked to warehouses
Purchase Order API (/purchase-orders) - Create purchase orders for warehouses

Warehouses are essential for inventory management. They represent physical locations where inventory is stored and managed. Use warehouses to organize your inventory by location and track stock movements.

Summary

Endpoint	Method	Description
`/warehouses`	`GET`	Retrieve paginated list of warehouses
`/warehouses/:id`	`GET`	Retrieve a single warehouse by ID
`/warehouses`	`POST`	Create a new warehouse
`/warehouses/:id`	`PUT`	Update an existing warehouse (partial updates)
`/warehouses/:id`	`DELETE`	Delete a warehouse

Stock Reconciliation API

Reconcile inventory for warehouses

Purchase Invoice API

Create purchase invoices for warehouses

​Warehouse API

​Overview

​Endpoint Details

​Required Headers

​Get All Warehouses

​Required Headers

​Query Parameters

​Success Response

​Response Fields

​Warehouse Object

​Pagination Object

​Possible Errors

​Example Requests

​Get Single Warehouse

​Path Parameters

​Success Response

​Response Fields

​Possible Errors

​Example Requests

​Create Warehouse

​Required Headers

​Request Body

​Request Body Example

​Success Response

​Possible Errors

​Example Requests

​Update Warehouse

​Path Parameters

​Request Body

​Request Body Example

​Success Response

​Possible Errors

​Example Requests

​Delete Warehouse

​Path Parameters

​Success Response

​Possible Errors

​Example Requests

​Business Logic

​Warehouse Creation Flow

​Warehouse States

Active Warehouse

Grouped Warehouse

Standalone Warehouse

With Contact

​Error Responses

​Error Response Format

​Common Error Scenarios

​Usage Examples

​Example 1: Create a top-level warehouse

​Example 2: Create a child warehouse

​Example 3: Get warehouses with filtering

​Example 4: Update warehouse address only

​Example 5: Remove parent relationship

​Best Practices

​Related Endpoints

​Summary

Stock Reconciliation API

Purchase Invoice API

Warehouse API

Overview

Endpoint Details

Required Headers

Get All Warehouses

Required Headers

Query Parameters

Success Response

Response Fields

Warehouse Object

Pagination Object

Possible Errors

Example Requests

Get Single Warehouse

Path Parameters

Success Response

Response Fields

Possible Errors

Example Requests

Create Warehouse

Required Headers

Request Body

Request Body Example

Success Response

Possible Errors

Example Requests

Update Warehouse

Path Parameters

Request Body

Request Body Example

Success Response

Possible Errors

Example Requests

Delete Warehouse

Path Parameters

Success Response

Possible Errors

Example Requests

Business Logic

Warehouse Creation Flow

Warehouse States

Error Responses

Error Response Format

Common Error Scenarios

Usage Examples

Example 1: Create a top-level warehouse

Example 2: Create a child warehouse

Example 3: Get warehouses with filtering

Example 4: Update warehouse address only

Example 5: Remove parent relationship

Best Practices

Related Endpoints

Summary