> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kwugwo.africa/llms.txt
> Use this file to discover all available pages before exploring further.

# The Customer object

> An onye: a payer you want to recognise across payments.

An **onye** is a customer record on your workspace. Customers are
optional: you can create an ugwo with just `onye_email` and Kwugwo will
find or create the customer for you. Create them explicitly when you
want to attach your own user ID, names or billing address.

## Attributes

**uid** `string`

Unique identifier, `ony.XXXX.YYYYYYYYYYYYYYYYYYYYYYYY`.

**email** `string`

Email address, lowercased. Unique per workspace.

**first\_name** `string | null`

First name, title-cased (`ada` → `Ada`).

**last\_name** `string | null`

Last name, title-cased.

**nzube\_ref** `string | null`

Your reference for this customer, typically your user ID. You set it
as `ref` on [create](https://docs.kwugwo.africa/customers/create.md) and
[update](https://docs.kwugwo.africa/customers/update.md); it is returned as `nzube_ref`.
Case-sensitive.

**billing\_address** `object | null`

**properties**

**address** `string`

Street address.

**address2** `string`

Second line; `""` when unused.

**city** `string`

City.

**state** `string`

State or region.

**zip** `string`

Postal code.

**country** `string`

ISO-3166-1 alpha-2 code, e.g. `NG`.

**created\_at** `string`

ISO-8601 timestamp.

**updated\_at** `string`

ISO-8601 timestamp.

**meta** `object`

Your `{ "key": "value" }` metadata. `{}` when there is none.

**total\_successful\_activities** `integer`

Number of successful payment attempts by this customer.

**total\_failed\_activities** `integer`

Number of failed payment attempts by this customer.

**latest\_ugwo\_activity** `string | object | null`

The customer's most recent [activity](https://docs.kwugwo.africa/ugwo/activity-object.md). On
[Get a customer](https://docs.kwugwo.africa/customers/get.md) this is the full Activity object;
everywhere else (list, create, update, delete, nested in an ugwo, and
webhooks) it is just the activity ID, `act.…`. `null` if the customer
has never paid.

```json The Customer object theme={"system"}
{
  "uid": "ony.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE",
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Okeke",
  "nzube_ref": "user_8821",
  "billing_address": {
    "address": "12 Marina",
    "address2": "",
    "city": "Lagos",
    "state": "Lagos",
    "zip": "101001",
    "country": "NG"
  },
  "created_at": "2026-05-15T09:14:22+00:00",
  "updated_at": "2026-05-15T09:14:22+00:00",
  "meta": { "source": "shopify" },
  "total_successful_activities": 3,
  "total_failed_activities": 1,
  "latest_ugwo_activity": "act.VCvr.qnbBJaElzSTHOcaTzxbuDlIs"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.