> ## 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.

# Create a customer

> Create a new customer record on the workspace.

Creates an **onye** (a customer) on the workspace that owns your
secret key. Pass the resulting `uid` as `onye` when creating an ugwo
to attach the payment to this customer.

## Body parameters

<ParamField body="email" type="string" required>
  Customer's email address. Lowercased on save. Must be a valid email.
</ParamField>

<ParamField body="ref" type="string">
  Your own reference (max 150 chars), typically a user ID in your
  system.

  **Case-sensitive.** `"Id"` and `"id"` are stored and looked up as
  distinct values.
</ParamField>

<ParamField body="first_name" type="string">
  Up to 100 chars. Title-cased on save (`"ada"` → `"Ada"`).
</ParamField>

<ParamField body="last_name" type="string">
  Up to 100 chars. Title-cased on save.
</ParamField>

<ParamField body="billing_address" type="object">
  Optional billing address. The object as a whole may be omitted, but
  when you provide it **every field must be present.** For a field you
  don't have a value for (such as `address2`), pass an empty string
  (`""`) rather than omitting it. All fields are strings.

  * `address`: 1–100 chars
  * `address2`: 0–100 chars (pass `""` when not available)
  * `city`: 1–50 chars
  * `state`: 1–50 chars
  * `zip`: 1–10 chars
  * `country`: exactly 2 chars (ISO-3166-1 alpha-2)
</ParamField>

<ParamField body="meta" type="object">
  Free-form `{ string: string | null }` map for tagging; for example,
  a marketing source or internal segment.
</ParamField>

## Response

<ResponseField name="uid" type="string">Customer ID (`ony.…`).</ResponseField>
<ResponseField name="email" type="string">Email address (lowercased).</ResponseField>
<ResponseField name="ref" type="string | null">Your reference.</ResponseField>
<ResponseField name="first_name" type="string | null">First name (title-cased).</ResponseField>
<ResponseField name="last_name" type="string | null">Last name (title-cased).</ResponseField>
<ResponseField name="billing_address" type="object | null">The address you provided.</ResponseField>
<ResponseField name="meta" type="object">Echo of metadata.</ResponseField>
<ResponseField name="status" type="string">Customer status; `active` for new records.</ResponseField>
<ResponseField name="created_at" type="string">ISO-8601 timestamp.</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.kwugwo.africa/v1/onye \
    -H "Authorization: Bearer $KWUGWO_SECRET_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "email": "ada@example.com",
      "ref": "user_8821",
      "first_name": "Ada",
      "last_name": "Okeke",
      "billing_address": {
        "address": "12 Marina",
        "address2": "",
        "city": "Lagos",
        "state": "Lagos",
        "zip": "101001",
        "country": "NG"
      },
      "meta": { "source": "shopify" }
    }'
  ```

  ```js Node theme={null}
  const onye = await fetch("https://api.kwugwo.africa/v1/onye", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.KWUGWO_SECRET_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      email: "ada@example.com",
      ref: "user_8821",
      first_name: "Ada",
      last_name: "Okeke",
    }),
  }).then(r => r.json());
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init("https://api.kwugwo.africa/v1/onye");
  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_POST           => true,
      CURLOPT_HTTPHEADER     => [
          'Authorization: Bearer ' . getenv('KWUGWO_SECRET_KEY'),
          'Content-Type: application/json',
      ],
      CURLOPT_POSTFIELDS => json_encode([
          'email'      => 'ada@example.com',
          'ref'        => 'user_8821',
          'first_name' => 'Ada',
          'last_name'  => 'Okeke',
      ]),
  ]);
  $onye = json_decode(curl_exec($ch), true);
  curl_close($ch);
  ```

  ```python Python theme={null}
  import os, requests

  onye = requests.post(
      "https://api.kwugwo.africa/v1/onye",
      headers={"Authorization": f"Bearer {os.environ['KWUGWO_SECRET_KEY']}"},
      json={
          "email": "ada@example.com",
          "ref": "user_8821",
          "first_name": "Ada",
          "last_name": "Okeke",
      },
  ).json()
  ```

  ```go Go theme={null}
  body, _ := json.Marshal(map[string]any{
      "email":      "ada@example.com",
      "ref":        "user_8821",
      "first_name": "Ada",
      "last_name":  "Okeke",
  })
  req, _ := http.NewRequest("POST", "https://api.kwugwo.africa/v1/onye", bytes.NewReader(body))
  req.Header.Set("Authorization", "Bearer "+os.Getenv("KWUGWO_SECRET_KEY"))
  req.Header.Set("Content-Type", "application/json")
  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "uid": "ony.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE",
    "email": "ada@example.com",
    "ref": "user_8821",
    "first_name": "Ada",
    "last_name": "Okeke",
    "billing_address": {
      "address": "12 Marina",
      "address2": "",
      "city": "Lagos",
      "state": "Lagos",
      "zip": "101001",
      "country": "NG"
    },
    "meta": { "source": "shopify" },
    "status": "active",
    "created_at": "2026-05-15T09:14:22+00:00"
  }
  ```
</ResponseExample>