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

# Customers

> Create, list, retrieve, and delete customer records associated with your business.

## The customer object

A customer represents a buyer who has interacted with your business through Orafi. Customers are typically created automatically during payment flows.

<ResponseField name="id" type="string">
  Unique identifier for the customer.
</ResponseField>

<ResponseField name="firstname" type="string">
  Customer's first name.
</ResponseField>

<ResponseField name="lastname" type="string">
  Customer's last name.
</ResponseField>

<ResponseField name="email" type="string">
  Customer's email address.
</ResponseField>

<ResponseField name="mode" type="string[]">
  Environments the customer has interacted in. Contains `test`, `live`, or both.
</ResponseField>

<ResponseField name="totalSpent" type="number" default="0">
  Aggregate amount the customer has spent across all completed transactions.
</ResponseField>

<ResponseField name="createdAt" type="datetime">
  When the customer record was created.
</ResponseField>

<ResponseField name="updatedAt" type="datetime">
  When the customer record was last updated.
</ResponseField>

<ResponseExample>
  ```json The customer object theme={null}
  {
    "id": "cmjr4c7qq0000v8hozkzz4em5",
    "firstname": "Melvin",
    "lastname": "Charles",
    "email": "mekus@orafi.app",
    "mode": ["test"],
    "totalSpent": 0,
    "createdAt": "2025-12-29T12:12:29.615Z",
    "updatedAt": "2025-12-29T12:12:29.615Z"
  }
  ```
</ResponseExample>

***

## Create a customer

<div className="api-method-box">
  <span className="api-method post">POST</span> `/customers/create`
</div>

Manually creates a customer record.

<Note>
  In most flows, customers are created **automatically** when a payment is completed. Manual creation is intended for pre-registration, data migrations, or account-based billing.
</Note>

### Request body

<ParamField body="firstname" type="string" required>
  Customer's first name.
</ParamField>

<ParamField body="lastname" type="string" required>
  Customer's last name.
</ParamField>

<ParamField body="email" type="string" required>
  Customer's email address.
</ParamField>

<ResponseExample>
  ```bash cURL theme={null}
  curl -X POST https://api.orafi.app/customers/create \
    -H "Content-Type: application/json" \
    -H "x-api-key: ora_test_your_api_key" \
    -d '{
      "firstname": "John",
      "lastname": "Doe",
      "email": "john@example.com"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.orafi.app/customers/create", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": "ora_test_your_api_key"
    },
    body: JSON.stringify({
      firstname: "John",
      lastname: "Doe",
      email: "john@example.com"
    })
  });
  ```

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

  response = requests.post(
      "https://api.orafi.app/customers/create",
      headers={
          "Content-Type": "application/json",
          "x-api-key": "ora_test_your_api_key"
      },
      json={
          "firstname": "John",
          "lastname": "Doe",
          "email": "john@example.com"
      }
  )
  ```

  ```json 200 theme={null}
  {
    "success": true,
    "message": "Customer created successfully",
    "data": {
      "id": "cmjx0kiie0003v86cfqsve9fj",
      "firstname": "John",
      "lastname": "Doe",
      "email": "john@example.com",
      "mode": ["test"],
      "totalSpent": 0
    }
  }
  ```
</ResponseExample>

***

## List customers

<div className="api-method-box">
  <span className="api-method get">GET</span> `/customers`
</div>

Returns a paginated list of customers. All query parameters are optional.

### Query parameters

<ParamField query="amountSpent" type="string">
  Filter by spending range. One of `BELOW10USDT`, `FROM10TO30USDT`, `FROM30TO100USDT`, `FROM100TO200USDT`, `FROM200TO500USDT`, `ABOVE500USDT`.
</ParamField>

<ParamField query="mode" type="string">
  Filter by environment. `test` or `live`.
</ParamField>

<ParamField query="limit" type="number" default="20">
  Maximum number of results per page.
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor. Results start after the referenced customer.
</ParamField>

<ResponseExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.orafi.app/customers?mode=test&limit=10" \
    -H "x-api-key: ora_test_your_api_key"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.orafi.app/customers?mode=test&limit=10",
    { headers: { "x-api-key": "ora_test_your_api_key" } }
  );
  ```

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

  response = requests.get(
      "https://api.orafi.app/customers",
      headers={"x-api-key": "ora_test_your_api_key"},
      params={"mode": "test", "limit": 10}
  )
  ```

  ```json 200 theme={null}
  {
    "success": true,
    "message": "Customers fetched successfully",
    "data": {
      "customers": [
        {
          "id": "cmjr4c7qq0000v8hozkzz4em5",
          "firstname": "Melvin",
          "lastname": "Charles",
          "email": "mekus@orafi.app",
          "mode": ["test"],
          "totalSpent": 0,
          "userCustomers": [
            { "createdAt": "2025-12-29T12:12:29.615Z" }
          ]
        }
      ],
      "count": 1,
      "nextCursor": null,
      "hasNextPage": false
    }
  }
  ```
</ResponseExample>

***

## Retrieve a customer

<div className="api-method-box">
  <span className="api-method get">GET</span> `/customers/{customerId}`
</div>

Returns the details of a specific customer.

### Path parameters

<ParamField path="customerId" type="string" required>
  The customer ID to retrieve.
</ParamField>

<ResponseExample>
  ```bash cURL theme={null}
  curl -X GET https://api.orafi.app/customers/cmjr4c7qq0000v8hozkzz4em5 \
    -H "x-api-key: ora_test_your_api_key"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.orafi.app/customers/cmjr4c7qq0000v8hozkzz4em5",
    { headers: { "x-api-key": "ora_test_your_api_key" } }
  );
  ```

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

  response = requests.get(
      "https://api.orafi.app/customers/cmjr4c7qq0000v8hozkzz4em5",
      headers={"x-api-key": "ora_test_your_api_key"}
  )
  ```

  ```json 200 theme={null}
  {
    "success": true,
    "message": "Customer fetched successfully",
    "data": {
      "id": "cmjr4c7qq0000v8hozkzz4em5",
      "firstname": "Melvin",
      "lastname": "Charles",
      "email": "mekus@orafi.app",
      "mode": ["test"],
      "totalSpent": 0,
      "userCustomers": [
        { "createdAt": "2025-12-29T12:12:29.615Z" }
      ]
    }
  }
  ```
</ResponseExample>

***

## Delete a customer

<div className="api-method-box">
  <span className="api-method delete">DELETE</span> `/customers/{customerId}`
</div>

Permanently deletes a customer record. This action cannot be undone.

<Warning>
  Deleting a customer is **irreversible**. Only use this for duplicate records, accidental creation, or compliance-related data removal requests. We recommend keeping records for transaction history and reconciliation.
</Warning>

### Path parameters

<ParamField path="customerId" type="string" required>
  The customer ID to delete.
</ParamField>

<ResponseExample>
  ```bash cURL theme={null}
  curl -X DELETE https://api.orafi.app/customers/cmjr4c7qq0000v8hozkzz4em5 \
    -H "x-api-key: ora_test_your_api_key"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.orafi.app/customers/cmjr4c7qq0000v8hozkzz4em5",
    {
      method: "DELETE",
      headers: { "x-api-key": "ora_test_your_api_key" }
    }
  );
  ```

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

  response = requests.delete(
      "https://api.orafi.app/customers/cmjr4c7qq0000v8hozkzz4em5",
      headers={"x-api-key": "ora_test_your_api_key"}
  )
  ```

  ```json 200 theme={null}
  {
    "success": true,
    "message": "User Deleted successfully",
    "data": null
  }
  ```
</ResponseExample>