Suppliers
All routes under /api/v1/suppliers require authentication. Payment creation routes additionally require Owner role.
Supplier Management
GET /suppliers
List suppliers with filtering.
Auth: Required
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
search | string | Search by name/category |
status | string | active, inactive, on_hold |
page | int | Page number |
page_size | int | Items per page |
Response: Paginated supplier list.
POST /suppliers
Create a new supplier.
Auth: Required
Request Body:
{
"name": "Coca-Cola Distributors",
"category": "Beverages",
"rep": "Mr. Kimaro",
"phone": "+255712345678",
"email": "sales@cocacola.co.tz",
"address": "Industrial Area, Dar es Salaam",
"payment_terms": 30,
"status": "active",
"notes": "Delivers every Tuesday"
}Response: Supplier object.
GET /suppliers/stats
Get supplier overview statistics.
Auth: Required
Response:
{
"success": true,
"data": {
"total_suppliers": 15,
"active_suppliers": 12,
"total_outstanding": 4500000,
"deliveries_this_month": 8,
"payments_this_month": 3200000
}
}GET /suppliers/:id
Get a single supplier with outstanding balance.
Auth: Required
Response: Supplier object with outstanding_balance.
PATCH /suppliers/:id
Update a supplier.
Auth: Required
Request Body: Same as POST /suppliers but all fields optional.
DELETE /suppliers/:id
Deactivate a supplier.
Auth: Required
Response (200): {"success": true}
Deliveries
GET /suppliers/deliveries
Global list of all deliveries.
Auth: Required
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
unpaid | boolean | Only unpaid deliveries |
supplier | uuid | Filter by supplier |
page | int | Page number |
page_size | int | Items per page |
POST /suppliers/deliveries
Record a delivery globally.
Auth: Required
Request Body:
{
"supplier_id": "uuid",
"invoice_number": "INV-001",
"delivery_date": "2024-01-15T00:00:00Z",
"items_count": 50,
"total_value": 750000,
"status": "delivered",
"is_paid": false,
"notes": "Full delivery received"
}GET /suppliers/deliveries/:id
Get delivery detail.
PATCH /suppliers/deliveries/:id
Update a delivery.
DELETE /suppliers/deliveries/:id
Delete a delivery.
POST /suppliers/deliveries/:id/pay
Pay against a specific delivery.
Auth: Required + Owner
Request Body:
{
"amount": 750000,
"payment_method": "bank",
"reference": "Transfer ref 123",
"notes": "Full payment for INV-001"
}Payments
GET /suppliers/payments
Global list of all supplier payments.
Auth: Required
Query: supplier (uuid), page, page_size
GET /suppliers/:id/payments
List payments for a specific supplier.
Auth: Required
Query: page, page_size
POST /suppliers/:id/pay
Pay a supplier.
Auth: Required + Owner
Request Body:
{
"amount": 500000,
"payment_method": "cash",
"reference": "",
"notes": "Monthly payment"
}Supplier-Specific Delivery Routes
GET /suppliers/:id/deliveries
List deliveries for a specific supplier.
POST /suppliers/:id/deliveries
Record a delivery for a specific supplier.