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

# Managing Customers

The Modem Pay API’s customer management is built to help you store and manage customer details efficiently. Below are detailed steps and example requests for creating, retrieving, updating, deleting, and listing customers, as well as listing their payment methods. This allows you to manage customer profiles and payment preferences seamlessly.

***

#### **Create a Customer**

To create a customer, use the `modempay.customers.create()` method, which allows you to add key information like the customer's name, email, phone number, and an optional starting balance. The `distinct` option, when set to `true`, checks for existing customers with matching fields (e.g., email) to avoid duplicate entries. If `distinct` is omitted or set to `false`, a new customer entry will be created without duplicate checks.

**Sample Request:**

<CodeGroup>
  ```typescript nodejs theme={null}
  const customer = await modempay.customers.create(
      { name: "Zypheron Kade", email: "zypheron.kade42@protonmail.com", phone: "7000001" },
      { distinct: true }
  );
  ```

  ```python python theme={null}
  customer = modem_pay.customers.create(
      params={
          "name": "Zypheron Kade",
          "email": "zypheron.kade42@protonmail.com",
          "phone": "7000001",
      },
      options={"distinct": True},
  )
  ```

  ```bash cURL theme={null}
  cURL -X POST "https://api.modempay.com/v1/customers" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <your_api_key>" \
    -d '{
      "name": "Zypheron Kade",
      "email": "zypheron.kade42@protonmail.com",
      "phone": "7000001",
      "config": { "distinct": true }
    }'
  ```
</CodeGroup>

**Sample Response:**

```json theme={null}
{
  "id": "8a8c8a0e-c5d2-4692-a94b-25284d36adc7",
  "balance": 0,
  "name": "Zypheron Kade",
  "email": "zypheron.kade42@protonmail.com",
  "phone": "7000001",
  "business_id": "a10a51ae-05c8-406e-968c-7b1d309a77e0",
  "account_id": "7788dd90-3801-47a6-8597-b46eaa0a7d7d",
  "test_mode": true,
  "updatedAt": "2024-11-11T13:54:10.104Z",
  "createdAt": "2024-11-11T13:54:10.104Z"
}
```

***

#### **Retrieve a Customer**

To fetch a customer’s details, use `modempay.customers.retrieve(customerId)`. Replace `customerId` with the customer’s unique ID.

**Sample Request:**

<CodeGroup>
  ```javascript nodejs  theme={null}
  const customer = await modempay.customers.retrieve(
    "8a8c8a0e-c5d2-4692-a94b-25284d36adc7"
  );
  ```

  ```python python  theme={null}
  customer = modem_pay.customers.retrieve("8a8c8a0e-c5d2-4692-a94b-25284d36adc7")
  ```

  ```bash cURL  theme={null}
  cURL -X GET "https://api.modempay.com/v1/customers/8a8c8a0e-c5d2-4692-a94b-25284d36adc7" \
    -H "Authorization: Bearer <your_api_key>"
  ```
</CodeGroup>

**Sample Response:**

```json theme={null}
{
  "id": "8a8c8a0e-c5d2-4692-a94b-25284d36adc7",
  "name": "Zypheron Kade",
  "email": "zypheron.kade42@protonmail.com",
  "phone": "7000001",
  "balance": 0,
  "business_id": "a10a51ae-05c8-406e-968c-7b1d309a77e0",
  "account_id": "7788dd90-3801-47a6-8597-b46eaa0a7d7d",
  "test_mode": true,
  "createdAt": "2024-11-11T13:54:10.104Z",
  "updatedAt": "2024-11-11T13:54:10.104Z"
}
```

***

#### **Update a Customer**

Update a customer's information using `modempay.customers.update(customerId, params)`. Specify the customer ID and the fields to update.

**Sample Request:**

<CodeGroup>
  ```javascript nodejs  theme={null}
  const customer = await modempay.customers.update(
      "8a8c8a0e-c5d2-4692-a94b-25284d36adc7",
      { name: "Chibuike Okpara" }
  );
  ```

  ```python python  theme={null}
  customer = modem_pay.customers.update(
      id="8a8c8a0e-c5d2-4692-a94b-25284d36adc7", params={"name": "Chibuike Okpara"}
  )
  ```

  ```bash cURL  theme={null}
  cURL -X PUT "https://api.modempay.com/v1/customers/<customer_id>" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <your_api_key>" \
    -d '{
      "data": {
        "<parameter_1>": "<value_1>",
        "<parameter_2>": "<value_2>"
      }
    }'
  ```
</CodeGroup>

**Sample Response:**

```json theme={null}
{
  "id": "8a8c8a0e-c5d2-4692-a94b-25284d36adc7",
  "name": "Chibuike Okpara",
  "email": "zypheron.kade42@protonmail.com",
  "phone": "7000001",
  "balance": 0,
  "business_id": "a10a51ae-05c8-406e-968c-7b1d309a77e0",
  "account_id": "7788dd90-3801-47a6-8597-b46eaa0a7d7d",
  "test_mode": true,
  "createdAt": "2024-11-11T13:54:10.104Z",
  "updatedAt": "2024-11-11T14:56:53.949Z"
}
```

***

#### **Delete a Customer**

Remove a customer from your records using `modempay.customers.delete(customerId)`. This action is irreversible.

**Sample Request:**

<CodeGroup>
  ```javascript nodejs  theme={null}
  await modempay.customers.delete("8a8c8a0e-c5d2-4692-a94b-25284d36adc7");
  ```

  ```python python  theme={null}
  modem_pay.customers.delete("8a8c8a0e-c5d2-4692-a94b-25284d36adc7")
  ```

  ```bash cURL  theme={null}
  cURL -X DELETE "https://api.modempay.com/v1/customers/<customer_id>" \
    -H "Authorization: Bearer <your_api_key>"
  ```
</CodeGroup>

***

#### **List All Customers**

To view all customers, use `modempay.customers.list()`. This returns a list of customers, with pagination options if there are many entries.

**Sample Request:**

<CodeGroup>
  ```javascript nodejs  theme={null}
  const customers = await modempay.customers.list({ limit: 2 });

  // or list by matching terms
  const customers = await modempay.customers.list({ limit:2, search: "caleb" })

  ```
</CodeGroup>

**Sample Response:**

```json theme={null}
{
  "data": [
    {
      "id": "8a8c8a0e-c5d2-4692-a94b-25284d36adc7",
      "name": "Chibuike Okpara",
      "email": "zypheron.kade42@protonmail.com",
      "phone": "7000001",
      "balance": 0,
      "business_id": "a10a51ae-05c8-406e-968c-7b1d309a77e0",
      "account_id": "7788dd90-3801-47a6-8597-b46eaa0a7d7d",
      "test_mode": true,
      "createdAt": "2024-11-11T13:54:10.104Z",
      "updatedAt": "2024-11-11T14:56:53.949Z"
    },
    {
      "id": "0f6e0912-2f2f-4d8b-bd68-ac8c97c44ae6",
      "name": "Zypheron Kade",
      "email": "calebchibuike@modempay.com",
      "phone": "7000002",
      "balance": 0,
      "business_id": "a10a51ae-05c8-406e-968c-7b1d309a77e0",
      "account_id": "7788dd90-3801-47a6-8597-b46eaa0a7d7d",
      "test_mode": true,
      "createdAt": "2024-11-09T14:49:49.490Z",
      "updatedAt": "2024-11-09T14:49:49.490Z"
    }
  ],
  "meta": {
    "total": 3
  }
}
```

***

#### **List Payment Methods for a Customer**

To retrieve the payment methods associated with a specific customer, use their customer ID. This is useful to manage or display available payment methods during checkout.

**Sample Request:**

<CodeGroup>
  ```javascript nodejs  theme={null}
  const paymentMethods = await modempay.customers.listPaymentMethods(
      "8a8c8a0e-c5d2-4692-a94b-25284d36adc7"
  );
  ```
</CodeGroup>

**Sample Response:**

```json theme={null}
{
  "data": [
    {
      "mobilepay": {
        "logo": "https://api.modempay.com/images/qcell.png",
        "type": "mobilepay",
        "group": "wallet-gm",
        "last4": "9944",
        "gateway": "qmoney",
        "fingerprint": "8d84c1b8ba568bce9b2590bfec618a65",
        "gateway_name": "QMoney"
      },
      "id": "ad47ccb9-687c-475b-90dc-1dd3b4cba68e",
      "type": "mobilepay",
      "customer": "8a8c8a0e-c5d2-4692-a94b-25284d36adc7",
      "business_id": "a10a51ae-05c8-406e-968c-7b1d309a77e0",
      "account_id": "7788dd90-3801-47a6-8597-b46eaa0a7d7d",
      "test_mode": true,
      "has_been_detached": false,
      "createdAt": "2024-11-09T11:22:31.169Z",
      "updatedAt": "2024-11-09T11:22:31.169Z"
    }
  ],
  "meta": {
    "total": 1
  }
}
```