Customers

Kibanda remembers each customer so they never type the same thing twice: their name, saved delivery addresses, and the M-Pesa number they pay with. The API lets you read that, add your own notes and tags, and link each customer to the record in your CRM or ERP.

The customer object

{
  "id": "ct_…",
  "object": "customer",
  "name": "Achieng Otieno",
  "phone": "+254712345678",
  "mpesa_phone": "+254712345678",
  "whatsapp_user_id": "254712345678",
  "email": "achieng@example.com",
  "notes": "Gate B, call on arrival",
  "tags": ["vip"],
  "payment_terms": "default",
  "delivered_orders": 12,
  "refused_orders": 0,
  "order_count": 13,
  "total_spent": 512000,
  "addresses": [{ "id": "ad_…", "object": "address", "label": "Home", "lat": -1.2921, "lng": 36.7856, "landmark": "Blue gate", "last_used": 1792716000 }],
  "external_id": "res.partner/4211",
  "metadata": {},
  "last_message_at": 1792716000,
  "created": 1792000000
}

order_count, total_spent and addresses are included when you retrieve one customer. phone can be null for WhatsApp username users who haven't shared their number.

Create a customer

POST /v1/customers — e.g. importing from Shopify or Odoo. When they later message the shop on WhatsApp they're recognised, and their saved details apply.

Parameter
`phone`	Required. `+254712345678`, `0712 345 678`, …
`name`, `email`, `notes`, `tags`, `mpesa_phone`, `external_id`, `metadata`
`upsert`	`true` to update the existing customer with this phone instead of getting `409 customer_exists`.

Update a customer

POST /v1/customers/{id} — name, email, notes, tags (replaces the list), mpesa_phone, payment_terms (default = the shop's rules, pay_first, trusted), external_id, metadata.

Saved addresses

POST /v1/customers/{id}/addresses — lat, lng (required), label, landmark. Offered at checkout so the customer doesn't share a pin.
DELETE /v1/customers/{id}/addresses/{address_id}

Retrieve and list

GET /v1/customers/{id}
GET /v1/customers — filters: phone, email, external_id, tag, created_gte, created_lt.

Keeping your CRM in sync

Subscribe to customer.created. For each, find or create the person in your system (match on phone).
Write your id back: POST /v1/customers/{id} with {"external_id": "res.partner/4211"}.
From then on, every order carries customer.external_id, so you can file it without a lookup.