Skip to Content
C-Ushuru v1.0 is now available
API ReferenceCustomers API

Customers API

Manage customer records for your business transactions. Customers are the individuals or businesses you sell to.

Overview

The Customers API allows you to:

  • List customers with filtering and pagination
  • Create new customer records
  • Search customers by name, TIN, or phone number
  • Update customer information
  • View customer transaction history
  • Delete customer records

Customer Structure

Key Fields

FieldDescription
customer_noUnique customer identifier/code
custNmCustomer name (individual or business)
tinTax Identification Number (for B2B transactions)
phoneContact phone number
emailContact email address
addressPhysical or postal address
branch_idBranch this customer belongs to
is_activeWhether the customer is active

TIN Format

FormatExampleDescription
PXXXXXXXXXCP000123456XPersonal TIN (11 characters)
AXXXXXXXXXXA000123456ZBusiness/Company TIN

List Customers

Get all customers for your account.

GET/api/v1/customers

List Customers

Retrieve all customers for your client account with optional filtering.

Authentication
Parameters
branch_id
string · query

Filter customers by branch ID

search
string · query

Search by name, TIN, or phone number

status
string · query

Filter by status (active, inactive)

page
integer · query

Page number for pagination

per_page
integer · query

Items per page (max 100)

Response

Status: 200 OK

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "customer_no": "CUST001",
      "name": "ABC Trading Ltd",
      "tin": "P000123456X",
      "phone": "+254712345678",
      "email": "info@abctrading.co.ke",
      "address": "Moi Avenue, Nairobi",
      "branch_id": "00",
      "is_active": true,
      "total_transactions": 45,
      "created_at": "2025-01-01T10:00:00Z"
    },
    {
      "id": 2,
      "customer_no": "CUST002",
      "name": "Jane Wanjiku",
      "tin": null,
      "phone": "+254722345678",
      "email": "jane@email.com",
      "address": "Westlands, Nairobi",
      "branch_id": "00",
      "is_active": true,
      "total_transactions": 12,
      "created_at": "2025-01-05T10:00:00Z"
    }
  ],
  "meta": {
    "total": 150,
    "per_page": 25,
    "current_page": 1,
    "last_page": 6,
    "timestamp": "2025-01-15T14:30:00Z"
  }
}

Create Customer

Register a new customer for your account.

POST/api/v1/customers

Create Customer

Register a new customer with their details.

Authentication
Request BodyJSON

Field Descriptions

FieldTypeRequiredDescription
branch_idstringYesBranch ID this customer belongs to (e.g., “00”)
customer_nostringYesUnique customer identifier/code (max 50 chars)
custNmstringYesCustomer name - individual or business (max 255 chars)
tinstringNoTax Identification Number (format: P000XXXXXXX)
phonestringNoContact phone number (max 50 chars)
emailstringNoContact email address (max 255 chars)
addressstringNoPhysical or postal address (max 500 chars)
metadataobjectNoAdditional custom metadata

Response

Status: 201 Created

{
  "status": "success",
  "message": "Customer created successfully",
  "data": {
    "id": 3,
    "customer_no": "CUST003",
    "name": "XYZ Enterprises",
    "tin": "P000789012Y",
    "phone": "+254733345678",
    "email": "contact@xyz.co.ke",
    "address": "Industrial Area, Nairobi",
    "branch_id": "00",
    "is_active": true,
    "created_at": "2025-01-17T10:00:00Z"
  },
  "meta": {
    "timestamp": "2025-01-17T10:00:00Z",
    "request_id": "req_abc123"
  }
}

Get Customer Details

Retrieve details of a specific customer including their transaction history.

GET/api/v1/customers/{customerId}

Get Customer Details

Retrieve detailed information about a specific customer including transaction summary.

Authentication
Parameters
customerId*
integer · path

Customer ID

Response

Status: 200 OK

{
  "status": "success",
  "data": {
    "id": 1,
    "customer_no": "CUST001",
    "name": "ABC Trading Ltd",
    "tin": "P000123456X",
    "phone": "+254712345678",
    "email": "info@abctrading.co.ke",
    "address": "Moi Avenue, Nairobi",
    "branch_id": "00",
    "branch_name": "Head Office",
    "is_active": true,
    "metadata": {},
    "transaction_summary": {
      "total_transactions": 45,
      "total_sales_amount": 1250000.00,
      "this_month_transactions": 8,
      "last_transaction_at": "2025-01-14T16:30:00Z"
    },
    "recent_transactions": [
      {
        "id": "uuid-123",
        "type": "sales",
        "invoice_no": "INV-045",
        "amount": 15000.00,
        "status": "success",
        "created_at": "2025-01-14T16:30:00Z"
      }
    ],
    "created_at": "2025-01-01T10:00:00Z",
    "updated_at": "2025-01-14T16:30:00Z"
  }
}

Status: 404 Not Found

{
  "status": "error",
  "message": "Customer not found"
}

Update Customer

Update an existing customer’s information.

PUT/api/v1/customers/{customerId}

Update Customer

Update customer information. All fields are optional - only provided fields will be updated.

Authentication
Parameters
customerId*
integer · path

Customer ID

Request BodyJSON

Response

Status: 200 OK

{
  "status": "success",
  "message": "Customer updated successfully",
  "data": {
    "id": 1,
    "customer_no": "CUST001",
    "name": "ABC Trading Ltd - Updated",
    "tin": "P000123456X",
    "phone": "+254712999999",
    "email": "updated@abctrading.co.ke",
    "address": "New Location, Westlands, Nairobi",
    "branch_id": "00",
    "is_active": true,
    "updated_at": "2025-01-17T15:00:00Z"
  }
}

Delete Customer

Delete a customer (soft delete).

DELETE/api/v1/customers/{customerId}

Delete Customer

Soft delete a customer. Historical transaction records with this customer are preserved.

Authentication
Parameters
customerId*
integer · path

Customer ID to delete

Response

Status: 200 OK

{
  "status": "success",
  "message": "Customer deleted successfully"
}

Note: Historical transaction records with this customer are preserved for audit purposes. The customer will no longer appear in search results or dropdown lists.

Search Customers

Search for customers by name, TIN, or phone number.

GET/api/v1/customers/search

Search Customers

Quick search endpoint for finding customers. Useful for autocomplete in sales forms.

Authentication
Parameters
q*
string · query

Search query (min 2 characters)

branch_id
string · query

Limit search to specific branch

limit
integer · query

Maximum results to return (default 10, max 50)

Response

Status: 200 OK

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "customer_no": "CUST001",
      "name": "ABC Trading Ltd",
      "tin": "P000123456X",
      "phone": "+254712345678"
    },
    {
      "id": 5,
      "customer_no": "CUST005",
      "name": "ABC Supplies",
      "tin": "P000456789Z",
      "phone": "+254745678901"
    }
  ],
  "meta": {
    "count": 2,
    "query": "ABC"
  }
}

Get Customer Transactions

Retrieve all transactions for a specific customer.

GET/api/v1/customers/{customerId}/transactions

Get Customer Transactions

Retrieve transaction history for a specific customer with pagination.

Authentication
Parameters
customerId*
integer · path

Customer ID

type
string · query

Filter by transaction type (sales, purchases)

from_date
string · query

Start date (YYYY-MM-DD)

to_date
string · query

End date (YYYY-MM-DD)

page
integer · query

Page number

Response

Status: 200 OK

{
  "status": "success",
  "data": [
    {
      "id": "uuid-123",
      "type": "sales",
      "invoice_no": "INV-045",
      "total_amount": 15000.00,
      "tax_amount": 2400.00,
      "status": "success",
      "branch_id": "00",
      "created_at": "2025-01-14T16:30:00Z"
    },
    {
      "id": "uuid-122",
      "type": "sales",
      "invoice_no": "INV-040",
      "total_amount": 8500.00,
      "tax_amount": 1360.00,
      "status": "success",
      "branch_id": "00",
      "created_at": "2025-01-10T11:00:00Z"
    }
  ],
  "meta": {
    "total": 45,
    "per_page": 25,
    "current_page": 1,
    "last_page": 2
  }
}

Error Responses

400 Bad Request

{
  "status": "error",
  "message": "Validation failed",
  "errors": {
    "customer_no": ["The customer_no has already been taken."],
    "tin": ["The tin format is invalid."]
  }
}

404 Not Found

{
  "status": "error",
  "message": "Customer not found"
}

409 Conflict

{
  "status": "error",
  "message": "Customer with this customer_no already exists in this branch"
}

Code Examples

JavaScript

const axios = require('axios');
 
const apiKey = process.env.CTAX_API_KEY;
const baseURL = 'https://c-ushuru.com/api/v1';
 
// List all customers
const customers = await axios.get(`${baseURL}/customers`, {
  headers: { Authorization: `Bearer ${apiKey}` }
});
 
// Create a new customer
const newCustomer = await axios.post(`${baseURL}/customers`, {
  branch_id: '00',
  customer_no: 'CUST003',
  custNm: 'XYZ Enterprises',
  tin: 'P000789012Y',
  phone: '+254733345678',
  email: 'contact@xyz.co.ke'
}, {
  headers: { Authorization: `Bearer ${apiKey}` }
});
 
// Search customers
const searchResults = await axios.get(`${baseURL}/customers/search`, {
  params: { q: 'XYZ', limit: 10 },
  headers: { Authorization: `Bearer ${apiKey}` }
});
 
// Get customer transactions
const transactions = await axios.get(`${baseURL}/customers/1/transactions`, {
  params: { type: 'sales', from_date: '2025-01-01' },
  headers: { Authorization: `Bearer ${apiKey}` }
});

PHP

use GuzzleHttp\Client;
 
$client = new Client([
    'base_uri' => 'https://c-ushuru.com/api/v1/',
    'headers' => [
        'Authorization' => 'Bearer ' . env('CTAX_API_KEY'),
        'Content-Type' => 'application/json',
    ],
]);
 
// List all customers
$customers = $client->get('customers');
 
// Create a new customer
$response = $client->post('customers', [
    'json' => [
        'branch_id' => '00',
        'customer_no' => 'CUST003',
        'custNm' => 'XYZ Enterprises',
        'tin' => 'P000789012Y',
        'phone' => '+254733345678',
    ],
]);
 
// Search customers
$search = $client->get('customers/search', [
    'query' => ['q' => 'XYZ', 'limit' => 10],
]);

Python

import requests
import os
 
api_key = os.environ['CTAX_API_KEY']
base_url = 'https://c-ushuru.com/api/v1'
headers = {'Authorization': f'Bearer {api_key}'}
 
# List all customers
response = requests.get(f'{base_url}/customers', headers=headers)
customers = response.json()['data']
 
# Create a new customer
new_customer = requests.post(
    f'{base_url}/customers',
    json={
        'branch_id': '00',
        'customer_no': 'CUST003',
        'custNm': 'XYZ Enterprises',
        'tin': 'P000789012Y',
        'phone': '+254733345678',
    },
    headers=headers
)
 
# Search customers
search = requests.get(
    f'{base_url}/customers/search',
    params={'q': 'XYZ', 'limit': 10},
    headers=headers
)

Best Practices

  1. Unique Customer Numbers - Use a consistent numbering system (e.g., CUST001, CUST002)
  2. Record TIN for B2B - Always capture TIN for business customers
  3. Branch Assignment - Assign customers to the branch they primarily transact with
  4. Regular Updates - Keep customer contact information current
  5. Use Search - Leverage the search endpoint for quick lookups during sales
  6. Walk-in Customers - Create a generic “Walk-in” customer for cash sales without customer details
Last updated on
Users APIBranches API