📋 Management API

Suppliers, Clients, and Units Management Endpoints

Suppliers

GET /suppliers Admin / Employee

List all suppliers with filtering, search, and pagination support.

Query Parameters

  • status (optional: active, inactive, archived)
  • county (optional, filter by county)
  • q (optional, search by name, business_name, email, or phone_number)
  • include_archived (optional, default: false)
  • page, per_page (optional; default 1 / 20)

Example:

GET /suppliers?status=active&q=john&page=1&per_page=20

200 OK - Success

{
  "suppliers": [
    {
      "id": 1,
      "name": "John Doe",
      "business_name": "Fresh Produce Co",
      "email": "john@example.com",
      "phone_number": "+254712345678",
      "status": "active",
      "county": "Nairobi",
      "location": "Westlands",
      "created_at": "2025-01-15T10:30:00",
      "updated_at": "2025-01-15T10:30:00"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "pages": 1,
    "has_next": false,
    "has_prev": false
  }
}
GET /suppliers/<supplier_id> Admin / Employee

Get detailed information about a specific supplier.

200 OK - Success

{
  "supplier": {
    "id": 1,
    "name": "John Doe",
    "business_name": "Fresh Produce Co",
    "email": "john@example.com",
    "phone_number": "+254712345678",
    "status": "active",
    "county": "Nairobi",
    "location": "Westlands",
    "created_at": "2025-01-15T10:30:00",
    "updated_at": "2025-01-15T10:30:00"
  }
}
POST /suppliers Admin Only

Create a new supplier.

Request Body (JSON)

  • name (required)
  • phone_number (required)
  • business_name (optional)
  • email (optional, must be unique if provided)
  • county (optional)
  • location (optional)
  • status (optional: active/inactive/archived, default: active)

Example:

{
  "name": "John Doe",
  "phone_number": "+254712345678",
  "business_name": "Fresh Produce Co",
  "email": "john@example.com",
  "county": "Nairobi",
  "location": "Westlands",
  "status": "active"
}

201 Created - Success

400 - Missing required fields

409 - Email already registered

PUT /suppliers/<supplier_id> Admin Only

Update supplier information. All fields are optional.

200 OK - Success

404 - Not Found

409 - Email already registered

POST /suppliers/<supplier_id>/activate Admin Only

Activate a supplier (set status to active).

200 OK - Success

400 - Already active or archived

404 - Not Found

POST /suppliers/<supplier_id>/deactivate Admin Only

Deactivate a supplier (set status to inactive).

200 OK - Success

400 - Already inactive or archived

404 - Not Found

POST /suppliers/<supplier_id>/archive Admin Only

Archive a supplier (soft delete, sets status to archived).

200 OK - Success

400 - Already archived

404 - Not Found

DELETE /suppliers/<supplier_id> Admin Only

Delete a supplier (same as archive - soft delete).

200 OK - Success

404 - Not Found

Clients

GET /clients Admin / Employee

List all clients with filtering, search, and pagination support.

Query Parameters

  • status (optional: active, inactive, archived)
  • county (optional, filter by county)
  • q (optional, search by name, business_name, email, or contact person fields)
  • include_archived (optional, default: false)
  • page, per_page (optional; default 1 / 20)

Example:

GET /clients?status=active&county=Nairobi&page=1&per_page=20

200 OK - Success

{
  "clients": [
    {
      "id": 1,
      "name": "ABC Corporation",
      "business_name": "ABC Corp Ltd",
      "email": "contact@abccorp.com",
      "primary_contact_person": "Jane Smith",
      "primary_contact_person_email": "jane@abccorp.com",
      "primary_contact_person_phone_number": "+254712345678",
      "secondary_contact_person": "Bob Johnson",
      "secondary_contact_person_email": "bob@abccorp.com",
      "secondary_contact_person_phone_number": "+254798765432",
      "main_contact_phone_number": "+254712345678",
      "main_contact_email": "info@abccorp.com",
      "status": "active",
      "county": "Nairobi",
      "location": "CBD",
      "created_at": "2025-01-15T10:30:00",
      "updated_at": "2025-01-15T10:30:00"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "pages": 1,
    "has_next": false,
    "has_prev": false
  }
}
GET /clients/<client_id> Admin / Employee

Get detailed information about a specific client.

200 OK - Success

POST /clients Admin Only

Create a new client.

Request Body (JSON)

  • name (required)
  • email (required, must be unique)
  • business_name (optional)
  • primary_contact_person (optional)
  • primary_contact_person_email (optional)
  • primary_contact_person_phone_number (optional)
  • secondary_contact_person (optional)
  • secondary_contact_person_email (optional)
  • secondary_contact_person_phone_number (optional)
  • main_contact_phone_number (optional)
  • main_contact_email (optional)
  • county (optional)
  • location (optional)
  • status (optional: active/inactive/archived, default: active)

Example:

{
  "name": "ABC Corporation",
  "email": "contact@abccorp.com",
  "business_name": "ABC Corp Ltd",
  "primary_contact_person": "Jane Smith",
  "primary_contact_person_email": "jane@abccorp.com",
  "primary_contact_person_phone_number": "+254712345678",
  "county": "Nairobi",
  "location": "CBD",
  "status": "active"
}

201 Created - Success

400 - Missing required fields

409 - Email already registered

PUT /clients/<client_id> Admin Only

Update client information. All fields are optional.

200 OK - Success

404 - Not Found

409 - Email already registered

POST /clients/<client_id>/activate Admin Only

Activate a client (set status to active).

200 OK - Success

400 - Already active or archived

404 - Not Found

POST /clients/<client_id>/deactivate Admin Only

Deactivate a client (set status to inactive).

200 OK - Success

400 - Already inactive or archived

404 - Not Found

POST /clients/<client_id>/archive Admin Only

Archive a client (soft delete, sets status to archived).

200 OK - Success

400 - Already archived

404 - Not Found

DELETE /clients/<client_id> Admin Only

Delete a client (same as archive - soft delete).

200 OK - Success

404 - Not Found

Units

GET /units Admin / Employee

List all units with filtering, search, and pagination support.

Query Parameters

  • status (optional: active, inactive, archived)
  • q (optional, search by name, code, or symbol)
  • include_archived (optional, default: false)
  • page, per_page (optional; default 1 / 20)

Example:

GET /units?status=active&q=kilogram&page=1&per_page=20

200 OK - Success

{
  "units": [
    {
      "id": 1,
      "name": "Kilogram",
      "code": "KG",
      "symbol": "kg",
      "status": "active",
      "created_at": "2025-01-15T10:30:00",
      "updated_at": "2025-01-15T10:30:00"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "pages": 1,
    "has_next": false,
    "has_prev": false
  }
}
GET /units/<unit_id> Admin / Employee

Get detailed information about a specific unit.

200 OK - Success

{
  "unit": {
    "id": 1,
    "name": "Kilogram",
    "code": "KG",
    "symbol": "kg",
    "status": "active",
    "created_at": "2025-01-15T10:30:00",
    "updated_at": "2025-01-15T10:30:00"
  }
}
POST /units Admin Only

Create a new unit.

Request Body (JSON)

  • name (required)
  • code (required, must be unique)
  • symbol (required)
  • status (optional: active/inactive/archived, default: active)

Example:

{
  "name": "Kilogram",
  "code": "KG",
  "symbol": "kg",
  "status": "active"
}

201 Created - Success

400 - Missing required fields

409 - Code already exists

PUT /units/<unit_id> Admin Only

Update unit information. All fields are optional.

200 OK - Success

404 - Not Found

409 - Code already exists

POST /units/<unit_id>/activate Admin Only

Activate a unit (set status to active).

200 OK - Success

400 - Already active or archived

404 - Not Found

POST /units/<unit_id>/deactivate Admin Only

Deactivate a unit (set status to inactive).

200 OK - Success

400 - Already inactive or archived

404 - Not Found

POST /units/<unit_id>/archive Admin Only

Archive a unit (soft delete, sets status to archived).

200 OK - Success

400 - Already archived

404 - Not Found

DELETE /units/<unit_id> Admin Only

Delete a unit (same as archive - soft delete).

200 OK - Success

404 - Not Found