Inventory API

Endpoints for managing bookstore inventory. All endpoints require authentication and store access.

Get Inventory

Get all inventory items for a store.

GET /inventory

Authentication

Required (Bearer token - store owner/staff only)

Query Parameters

storeId (required) - Store ID
limit (optional) - Number of results (default: 50)
offset (optional) - Pagination offset (default: 0)
search (optional) - Search by title, author, or ISBN
inStockOnly (optional) - Filter to only in-stock items (boolean)

Response

{
  "items": [
    {
      "id": "inv-001",
      "storeId": "660e8400-e29b-41d4-a716-446655440001",
      "bookId": "bb0e8400-e29b-41d4-a716-446655440006",
      "book": {
        "id": "bb0e8400-e29b-41d4-a716-446655440006",
        "isbn": "9780316769174",
        "title": "The Catcher in the Rye",
        "authors": ["J.D. Salinger"],
        "coverUrl": "https://covers.bookwish.app/9780316769174.jpg"
      },
      "quantity": 5,
      "priceCents": 1599,
      "condition": "new",
      "location": "Fiction A-D, Shelf 3",
      "notes": "Popular title, restock regularly",
      "createdAt": "2024-01-10T09:00:00Z",
      "updatedAt": "2024-03-15T14:20:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Errors

401 Unauthorized - Not authenticated
403 Forbidden - No store access
500 InternalServerError - Server error

Example

curl "https://api.bookwish.app/inventory?storeId=660e8400-e29b-41d4-a716-446655440001&search=catcher&inStockOnly=true" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Inventory Item

Get a specific inventory item by ID.

GET /inventory/:id

Authentication

Required (Bearer token - store owner/staff only)

Path Parameters

id - Inventory item ID

Query Parameters

storeId (required) - Store ID

Response

{
  "id": "inv-001",
  "storeId": "660e8400-e29b-41d4-a716-446655440001",
  "bookId": "bb0e8400-e29b-41d4-a716-446655440006",
  "book": {
    "id": "bb0e8400-e29b-41d4-a716-446655440006",
    "isbn": "9780316769174",
    "isbn13": "9780316769174",
    "title": "The Catcher in the Rye",
    "authors": ["J.D. Salinger"],
    "publisher": "Little, Brown and Company",
    "coverUrl": "https://covers.bookwish.app/9780316769174.jpg",
    "pageCount": 277
  },
  "quantity": 5,
  "priceCents": 1599,
  "costCents": 899,
  "condition": "new",
  "location": "Fiction A-D, Shelf 3",
  "notes": "Popular title, restock regularly",
  "squareItemId": "XYZABC123",
  "createdAt": "2024-01-10T09:00:00Z",
  "updatedAt": "2024-03-15T14:20:00Z"
}

Errors

401 Unauthorized - Not authenticated
403 Forbidden - No store access
404 NotFound - Inventory item not found
500 InternalServerError - Server error

Example

curl "https://api.bookwish.app/inventory/inv-001?storeId=660e8400-e29b-41d4-a716-446655440001" \
  -H "Authorization: Bearer YOUR_TOKEN"

Add Inventory Item

Add a new book to store inventory.

POST /inventory

Authentication

Required (Bearer token - store owner/staff only)

Request Body

{
  "storeId": "660e8400-e29b-41d4-a716-446655440001",
  "bookId": "bb0e8400-e29b-41d4-a716-446655440006",
  "quantity": 10,
  "priceCents": 1599,
  "costCents": 899,
  "condition": "new",
  "location": "Fiction A-D, Shelf 3",
  "notes": "New arrival"
}

Condition Values

new - Brand new condition
used_like_new - Used but like new
used_very_good - Used, very good condition
used_good - Used, good condition
used_acceptable - Used, acceptable condition

Response

{
  "id": "inv-002",
  "storeId": "660e8400-e29b-41d4-a716-446655440001",
  "bookId": "bb0e8400-e29b-41d4-a716-446655440006",
  "book": {
    "id": "bb0e8400-e29b-41d4-a716-446655440006",
    "isbn": "9780316769174",
    "title": "The Catcher in the Rye",
    "authors": ["J.D. Salinger"],
    "coverUrl": "https://covers.bookwish.app/9780316769174.jpg"
  },
  "quantity": 10,
  "priceCents": 1599,
  "costCents": 899,
  "condition": "new",
  "location": "Fiction A-D, Shelf 3",
  "notes": "New arrival",
  "createdAt": "2024-03-21T10:00:00Z",
  "updatedAt": "2024-03-21T10:00:00Z"
}

Errors

400 ValidationError - Invalid request body
401 Unauthorized - Not authenticated
403 Forbidden - No store access
404 NotFound - Book not found
409 Conflict - Inventory item already exists for this book
500 InternalServerError - Server error

Example

curl -X POST "https://api.bookwish.app/inventory" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "storeId": "660e8400-e29b-41d4-a716-446655440001",
    "bookId": "bb0e8400-e29b-41d4-a716-446655440006",
    "quantity": 10,
    "priceCents": 1599,
    "condition": "new"
  }'

Update Inventory Item

Update inventory item details (price, condition, location, notes).

PUT /inventory/:id

Authentication

Required (Bearer token - store owner/staff only)

Path Parameters

id - Inventory item ID

Request Body

{
  "storeId": "660e8400-e29b-41d4-a716-446655440001",
  "priceCents": 1299,
  "condition": "used_like_new",
  "location": "Fiction A-D, Shelf 2",
  "notes": "Sale price"
}

Response

{
  "id": "inv-001",
  "storeId": "660e8400-e29b-41d4-a716-446655440001",
  "bookId": "bb0e8400-e29b-41d4-a716-446655440006",
  "quantity": 5,
  "priceCents": 1299,
  "condition": "used_like_new",
  "location": "Fiction A-D, Shelf 2",
  "notes": "Sale price",
  "updatedAt": "2024-03-21T11:30:00Z"
}

Errors

400 ValidationError - Invalid request body
401 Unauthorized - Not authenticated
403 Forbidden - No store access
404 NotFound - Inventory item not found
500 InternalServerError - Server error

Example

curl -X PUT "https://api.bookwish.app/inventory/inv-001" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "storeId": "660e8400-e29b-41d4-a716-446655440001",
    "priceCents": 1299,
    "notes": "Sale price"
  }'

Adjust Quantity

Adjust inventory quantity (for stock changes, sales, returns).

PUT /inventory/:id/adjust

Authentication

Required (Bearer token - store owner/staff only)

Path Parameters

id - Inventory item ID

Request Body

{
  "storeId": "660e8400-e29b-41d4-a716-446655440001",
  "adjustment": -2,
  "reason": "Sold 2 copies in-store"
}

Response

{
  "id": "inv-001",
  "storeId": "660e8400-e29b-41d4-a716-446655440001",
  "bookId": "bb0e8400-e29b-41d4-a716-446655440006",
  "quantity": 3,
  "previousQuantity": 5,
  "adjustment": -2,
  "updatedAt": "2024-03-21T12:00:00Z"
}

Errors

400 ValidationError - Invalid request body or insufficient quantity
401 Unauthorized - Not authenticated
403 Forbidden - No store access
404 NotFound - Inventory item not found
500 InternalServerError - Server error

Example

curl -X PUT "https://api.bookwish.app/inventory/inv-001/adjust" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "storeId": "660e8400-e29b-41d4-a716-446655440001",
    "adjustment": -2,
    "reason": "Sold 2 copies in-store"
  }'

Delete Inventory Item

Remove an item from inventory.

DELETE /inventory/:id

Authentication

Required (Bearer token - store owner/staff only)

Path Parameters

id - Inventory item ID

Query Parameters

storeId (required) - Store ID

Response

{
  "success": true,
  "message": "Inventory item deleted successfully"
}

Errors

401 Unauthorized - Not authenticated
403 Forbidden - No store access
404 NotFound - Inventory item not found
500 InternalServerError - Server error

Example

curl -X DELETE "https://api.bookwish.app/inventory/inv-001?storeId=660e8400-e29b-41d4-a716-446655440001" \
  -H "Authorization: Bearer YOUR_TOKEN"

Bulk Import from CSV

Import multiple inventory items from a CSV file.

POST /inventory/bulk-import

Authentication

Required (Bearer token - store owner only)

Request Body

Content-Type: multipart/form-data
Field name: file
File format: CSV
Required columns: isbn, quantity, price, condition
Optional columns: cost, location, notes

CSV Format

isbn,quantity,price,condition,cost,location,notes
9780316769174,5,15.99,new,8.99,"Fiction A-D, Shelf 3","Popular title"
9780061120084,3,14.99,new,7.99,"Fiction A-D, Shelf 4",""

Query Parameters

storeId (required) - Store ID

Response

{
  "success": true,
  "imported": 2,
  "failed": 0,
  "errors": []
}

Errors

400 ValidationError - Invalid CSV format or data
401 Unauthorized - Not authenticated
403 Forbidden - Not the store owner
500 InternalServerError - Server error

Example

curl -X POST "https://api.bookwish.app/inventory/bulk-import?storeId=660e8400-e29b-41d4-a716-446655440001" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@inventory.csv"

Sync with Square

Sync inventory with Square POS system.

POST /inventory/sync-square

Authentication

Required (Bearer token - store owner only)

Query Parameters

storeId (required) - Store ID

Request Body

{
  "mode": "import"
}

Sync Modes

import - Import items from Square to BookWish
export - Export items from BookWish to Square
two-way - Bidirectional sync

Response

{
  "success": true,
  "synced": 45,
  "created": 12,
  "updated": 33,
  "errors": []
}

Errors

400 ValidationError - Invalid sync mode
401 Unauthorized - Not authenticated
403 Forbidden - Not the store owner or Square not connected
500 InternalServerError - Server error

Example

curl -X POST "https://api.bookwish.app/inventory/sync-square?storeId=660e8400-e29b-41d4-a716-446655440001" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "import"}'

Connect Square Account

Initiate Square OAuth connection.

GET /integrations/square/connect

Authentication

Required (Bearer token - store owner only)

Query Parameters

storeId (required) - Store ID

Response

Redirects to Square OAuth authorization page.

Errors

401 Unauthorized - Not authenticated
403 Forbidden - Not the store owner
500 InternalServerError - Server error

Example

curl "https://api.bookwish.app/integrations/square/connect?storeId=660e8400-e29b-41d4-a716-446655440001" \
  -H "Authorization: Bearer YOUR_TOKEN"

Square OAuth Callback

Handle Square OAuth callback (called by Square).

GET /integrations/square/callback

Authentication

None required (OAuth callback)

Query Parameters

code - Authorization code from Square
state - State parameter containing store ID

Response

Redirects to BookWish app with success/error status.

Inventory Item Object Fields

Field	Type	Description
`id`	string	Unique inventory item identifier
`storeId`	string	Store ID
`bookId`	string	Book ID
`book`	object	Book details object
`quantity`	number	Current stock quantity
`priceCents`	number	Selling price in cents
`costCents`	number	Cost price in cents (optional)
`condition`	string	Book condition
`location`	string	Physical location in store
`notes`	string	Additional notes
`squareItemId`	string	Square POS item ID (if synced)
`createdAt`	string	Creation timestamp (ISO 8601)
`updatedAt`	string	Last update timestamp (ISO 8601)

Get Inventory​

Authentication​

Query Parameters​

Response​

Errors​

Example​

Get Inventory Item​

Authentication​

Path Parameters​

Query Parameters​

Response​

Errors​

Example​

Add Inventory Item​

Authentication​

Request Body​

Condition Values​

Response​

Errors​

Example​

Update Inventory Item​

Authentication​

Path Parameters​

Request Body​

Response​

Errors​

Example​

Adjust Quantity​

Authentication​

Path Parameters​

Request Body​

Response​

Errors​

Example​

Delete Inventory Item​

Authentication​

Path Parameters​

Query Parameters​

Response​

Errors​

Example​

Bulk Import from CSV​

Authentication​

Request Body​

CSV Format​

Query Parameters​

Response​

Errors​

Example​

Sync with Square​

Authentication​

Query Parameters​

Request Body​

Sync Modes​

Response​

Errors​

Example​

Connect Square Account​

Authentication​

Query Parameters​

Response​

Errors​

Example​

Square OAuth Callback​

Authentication​

Query Parameters​

Response​

Inventory Item Object Fields​

Get Inventory

Authentication

Query Parameters

Response

Errors

Example

Get Inventory Item

Authentication

Path Parameters

Query Parameters

Response

Errors

Example

Add Inventory Item

Authentication

Request Body

Condition Values

Response

Errors

Example

Update Inventory Item

Authentication

Path Parameters

Request Body

Response

Errors

Example

Adjust Quantity

Authentication

Path Parameters

Request Body

Response

Errors

Example

Delete Inventory Item

Authentication

Path Parameters

Query Parameters

Response

Errors

Example

Bulk Import from CSV

Authentication

Request Body

CSV Format

Query Parameters

Response

Errors

Example

Sync with Square

Authentication

Query Parameters

Request Body

Sync Modes

Response

Errors

Example

Connect Square Account

Authentication

Query Parameters

Response

Errors

Example

Square OAuth Callback

Authentication

Query Parameters

Response

Inventory Item Object Fields