Products API

Product catalog and management endpoints.

Products API

The Products API provides endpoints for managing your product catalog, including creating, updating, and searching products.

Endpoints

GET /api/products

Retrieve products with filtering and pagination.

Query Parameters:

  • page (number): Page number (default: 1)
  • limit (number): Items per page (default: 20, max: 100)
  • search (string): Search term for name or SKU
  • category (string): Filter by category ID
  • status (string): Filter by status (active, inactive)
  • sort (string): Sort field (name, created_at, price)
  • order (string): Sort order (asc, desc)

Example Request:

GET /api/products?page=1&limit=20&search=widget&category=electronics&sort=name&order=asc

Response:

{
  "data": [
    {
      "id": "prod_123",
      "name": "Smart Widget",
      "sku": "SW-001",
      "description": "An intelligent widget",
      "category": {
        "id": "cat_456",
        "name": "Electronics"
      },
      "cost_price": 25.00,
      "selling_price": 49.99,
      "barcode": "1234567890123",
      "is_active": true,
      "inventory": {
        "total_stock": 150,
        "available_stock": 145,
        "reserved_stock": 5
      },
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T14:20:00Z"
    }
  ],
  "meta": {
    "total": 1250,
    "page": 1,
    "limit": 20,
    "hasMore": true
  }
}

GET /api/products/:id

Retrieve a specific product by ID.

Response:

{
  "data": {
    "id": "prod_123",
    "name": "Smart Widget",
    "sku": "SW-001",
    "description": "An intelligent widget",
    "category": {
      "id": "cat_456",
      "name": "Electronics"
    },
    "cost_price": 25.00,
    "selling_price": 49.99,
    "barcode": "1234567890123",
    "is_active": true,
    "inventory_by_warehouse": [
      {
        "warehouse_id": "wh_789",
        "warehouse_name": "Main Warehouse",
        "quantity": 100
      },
      {
        "warehouse_id": "wh_790",
        "warehouse_name": "West Coast",
        "quantity": 50
      }
    ],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T14:20:00Z"
  }
}

POST /api/products

Create a new product.

Request Body:

{
  "name": "New Widget",
  "sku": "NW-001",
  "description": "A new widget product",
  "category_id": "cat_456",
  "cost_price": 30.00,
  "selling_price": 59.99,
  "barcode": "2345678901234",
  "reorder_point": 20,
  "max_stock_level": 500,
  "is_active": true
}

Response:

{
  "data": {
    "id": "prod_124",
    "name": "New Widget",
    "sku": "NW-001",
    "description": "A new widget product",
    "category": {
      "id": "cat_456",
      "name": "Electronics"
    },
    "cost_price": 30.00,
    "selling_price": 59.99,
    "barcode": "2345678901234",
    "reorder_point": 20,
    "max_stock_level": 500,
    "is_active": true,
    "created_at": "2024-01-15T16:00:00Z",
    "updated_at": "2024-01-15T16:00:00Z"
  }
}

PUT /api/products/:id

Update an existing product.

Request Body:

{
  "name": "Updated Widget Name",
  "selling_price": 64.99,
  "is_active": false
}

Response:

{
  "data": {
    "id": "prod_124",
    "name": "Updated Widget Name",
    "selling_price": 64.99,
    "is_active": false,
    "updated_at": "2024-01-15T16:30:00Z"
  }
}

DELETE /api/products/:id

Delete a product (soft delete - sets is_active to false).

Response:

{
  "data": {
    "message": "Product successfully deleted"
  }
}

GET /api/products/search

Search products by barcode or text.

Query Parameters:

  • q (string): Search query
  • type (string): Search type (barcode, text, sku)

Example:

GET /api/products/search?q=1234567890123&type=barcode

Response:

{
  "data": [
    {
      "id": "prod_123",
      "name": "Smart Widget",
      "sku": "SW-001",
      "barcode": "1234567890123",
      "selling_price": 49.99,
      "inventory": {
        "total_stock": 150,
        "available_stock": 145
      }
    }
  ]
}