Credits (Madeni)
All routes under /api/v1/credits require authentication.
Credit tabs track money owed to the shop. They are automatically created when a sale uses the Credit payment method.
Credit Tab Statuses
| Status | Description |
|---|---|
open | No payment made yet |
partially_paid | Some payments recorded |
settled | Fully paid |
written_off | Debt forgiven |
GET /credits
List credit tabs with filtering.
Auth: Required
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
status | string | open, partially_paid, settled, written_off |
customer_id | uuid | Filter by customer |
overdue | boolean | Only overdue tabs |
page | int | Page number |
page_size | int | Items per page |
Response: Paginated CreditTab list.
GET /credits/customers/:customer_id
Get full credit profile for a customer.
Auth: Required
Response:
{
"success": true,
"data": {
"customer": { "id": "...", "name": "..." },
"tabs": [ ... ],
"payments": [ ... ],
"total_outstanding": 75000,
"overdue_count": 2
}
}POST /credits/customers/:customer_id/payments
Record a payment against a customer's balance.
Auth: Required
Request Body:
{
"amount": 25000,
"method": "M-Pesa",
"reference": "MPesa Ref 123",
"note": "Partial payment for January"
}Payment Methods: Cash, M-Pesa, Tigo Pesa, Bank
Response: CreditPayment object.
POST /credits/customers/:customer_id/remind
Send an SMS payment reminder.
Auth: Required
Response: CreditMessage object with status: "sent".
POST /credits/customers/:customer_id/messages
Log a communication attempt.
Auth: Required
Request Body:
{
"kind": "whatsapp",
"body": "Customer confirmed they will pay on Friday"
}Kind values: whatsapp, call, sms
Response: CreditMessage object.
POST /credits/customers/:customer_id/notes
Add an internal staff note.
Auth: Required
Request Body:
{
"body": "Customer called to discuss payment plan"
}Response: CreditNote object.
POST /credits/:tab_id/write-off
Write off (forgive) a credit tab.
Auth: Required
Request Body:
{
"reason": "Customer is unable to pay"
}Response: CreditTab with status: "written_off".
Warning: This is a destructive operation. The agent will confirm before executing.