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

# Eaglecart Customers API: Create and Manage Profiles

> Full reference for the Eaglecart Customers API — list, retrieve, create, and update customer profiles with request examples and full response schemas.

The Customers API gives you access to every customer record in your Eaglecart store. Use it to sync customer data with your CRM, build loyalty program integrations, segment audiences for marketing campaigns, or automate account creation when customers register through external channels.

> [!NOTE]
>
> Eaglecart supports GDPR right-to-erasure requests. To submit a data erasure request for a customer, contact Eaglecart support with the customer ID. Erasure removes all personally identifiable information associated with the account and cannot be undone.

***

## The Customer Object

**id** `string`

Unique identifier for the customer (e.g. `cus_01HABC456`).

**first\_name** `string`

Customer's first name.

**last\_name** `string`

Customer's last name.

**email** `string`

Customer's email address. Must be unique within your store.

**phone** `string`

Customer's phone number in E.164 format (e.g. `+14155552671`).

**total\_orders** `integer`

Total number of orders the customer has placed in your store.

**total\_spent** `number`

Total amount the customer has spent across all orders, in your store's base currency.

**created\_at** `string`

ISO 8601 timestamp of when the customer account was created.

**default\_address** `object`

The customer's default shipping address.

**address fields**

**first\_name** `string`

First name on the address.

**last\_name** `string`

Last name on the address.

**address1** `string`

Street address, line 1.

**address2** `string`

Street address, line 2 (apartment, suite, etc.).

**city** `string`

City.

**province** `string`

State, province, or region.

**country\_code** `string`

ISO 3166-1 alpha-2 country code (e.g. `US`, `GB`).

**zip** `string`

Postal or ZIP code.

***

## List Customers

Retrieve a paginated list of all customers in your store. Filter by email to look up a specific customer without knowing their ID.

`GET /customers`

**email** `string`

Filter to return the customer with this exact email address.

**limit** `integer`

Number of customers to return per page. Defaults to `20`. Maximum is `100`.

**page** `integer`

Page number to retrieve. Defaults to `1`.

```bash cURL theme={null}
curl "https://api.eaglecart.com/v1/customers?limit=3" \
  -H "Authorization: Bearer ec_live_xxxxxxxxxxxx"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.eaglecart.com/v1/customers?limit=3',
  { headers: { 'Authorization': 'Bearer ec_live_xxxxxxxxxxxx' } }
);
const data = await response.json();
```

```json Response theme={null}
{
  "data": [
    {
      "id": "cus_01HABC456",
      "first_name": "Jamie",
      "last_name": "Rivera",
      "email": "jamie@example.com",
      "phone": "+14155552671",
      "total_orders": 7,
      "total_spent": 549.43,
      "created_at": "2023-11-05T09:22:00Z",
      "default_address": {
        "first_name": "Jamie",
        "last_name": "Rivera",
        "address1": "123 Main St",
        "address2": null,
        "city": "San Francisco",
        "province": "CA",
        "country_code": "US",
        "zip": "94103"
      }
    }
  ],
  "meta": { "page": 1, "limit": 3, "total": 1540 }
}
```

***

## Get a Customer

Retrieve a single customer by their ID.

`GET /customers/:id`

**id** `string` *required*

The unique ID of the customer to retrieve.

```bash cURL theme={null}
curl https://api.eaglecart.com/v1/customers/cus_01HABC456 \
  -H "Authorization: Bearer ec_live_xxxxxxxxxxxx"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.eaglecart.com/v1/customers/cus_01HABC456',
  { headers: { 'Authorization': 'Bearer ec_live_xxxxxxxxxxxx' } }
);
const customer = await response.json();
```

```json Response theme={null}
{
  "id": "cus_01HABC456",
  "first_name": "Jamie",
  "last_name": "Rivera",
  "email": "jamie@example.com",
  "phone": "+14155552671",
  "total_orders": 7,
  "total_spent": 549.43,
  "created_at": "2023-11-05T09:22:00Z",
  "default_address": {
    "first_name": "Jamie",
    "last_name": "Rivera",
    "address1": "123 Main St",
    "address2": null,
    "city": "San Francisco",
    "province": "CA",
    "country_code": "US",
    "zip": "94103"
  }
}
```

***

## Create a Customer

Create a new customer account in your store. Email addresses must be unique — attempting to create a customer with a duplicate email returns `422 Unprocessable Entity`.

`POST /customers`

**email** `string` *required*

Customer's email address. Must be unique within your store.

**first\_name** `string`

Customer's first name.

**last\_name** `string`

Customer's last name.

**phone** `string`

Customer's phone number in E.164 format.

**default\_address** `object`

Default shipping address to associate with the new customer.

```bash cURL theme={null}
curl -X POST https://api.eaglecart.com/v1/customers \
  -H "Authorization: Bearer ec_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alex@example.com",
    "first_name": "Alex",
    "last_name": "Chen",
    "phone": "+12025550187"
  }'
```

```javascript JavaScript theme={null}
const response = await fetch('https://api.eaglecart.com/v1/customers', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ec_live_xxxxxxxxxxxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'alex@example.com',
    first_name: 'Alex',
    last_name: 'Chen',
    phone: '+12025550187'
  })
});
const customer = await response.json();
```

```json Response theme={null}
{
  "id": "cus_01HNEWCUS1",
  "first_name": "Alex",
  "last_name": "Chen",
  "email": "alex@example.com",
  "phone": "+12025550187",
  "total_orders": 0,
  "total_spent": 0.00,
  "created_at": "2024-06-11T14:00:00Z",
  "default_address": null
}
```

***

## Update a Customer

Update an existing customer's profile. Send only the fields you want to modify.

`PATCH /customers/:id`

**id** `string` *required*

The unique ID of the customer to update.

**first\_name** `string`

Updated first name.

**last\_name** `string`

Updated last name.

**phone** `string`

Updated phone number in E.164 format.

**default\_address** `object`

Updated default shipping address. Providing this field replaces the existing default address entirely.

```bash cURL theme={null}
curl -X PATCH https://api.eaglecart.com/v1/customers/cus_01HNEWCUS1 \
  -H "Authorization: Bearer ec_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+12025559999",
    "default_address": {
      "address1": "456 Oak Ave",
      "city": "Austin",
      "province": "TX",
      "country_code": "US",
      "zip": "73301"
    }
  }'
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.eaglecart.com/v1/customers/cus_01HNEWCUS1',
  {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer ec_live_xxxxxxxxxxxx',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      phone: '+12025559999',
      default_address: {
        address1: '456 Oak Ave',
        city: 'Austin',
        province: 'TX',
        country_code: 'US',
        zip: '73301'
      }
    })
  }
);
const updated = await response.json();
```

```json Response theme={null}
{
  "id": "cus_01HNEWCUS1",
  "first_name": "Alex",
  "last_name": "Chen",
  "email": "alex@example.com",
  "phone": "+12025559999",
  "updated_at": "2024-06-11T15:30:00Z",
  "default_address": {
    "address1": "456 Oak Ave",
    "address2": null,
    "city": "Austin",
    "province": "TX",
    "country_code": "US",
    "zip": "73301"
  }
}
```

***

## Error Handling

The Customers API uses standard HTTP status codes. All error responses include a JSON body with a `code` field and a human-readable `message`.

| Status | Code | What it means | How to fix it |
| - | - | - | - |
| `400 Bad Request` | `invalid_params` | A required field is missing or has an invalid value (e.g. malformed phone number). | Check the `message` field for the specific validation error and correct your request. |
| `401 Unauthorized` | `missing_api_key` / `invalid_api_key` | No `Authorization` header was sent, or the key is revoked. | Add a valid `Authorization: Bearer <key>` header. |
| `403 Forbidden` | `insufficient_scope` | Your key does not have `read:customers` or `write:customers` as required. | Re-generate your key with the correct scopes in **Settings → Developer → API Keys**. |
| `404 Not Found` | `customer_not_found` | No customer with the given ID exists in your store. | Confirm the customer ID is correct. |
| `422 Unprocessable Entity` | `email_already_exists` | A customer with the provided email address already exists. | Use a unique email address or retrieve the existing customer with `GET /customers?email=`. |
| `429 Too Many Requests` | `rate_limit_exceeded` | You have exceeded 1,000 requests per minute. | Wait until `X-RateLimit-Reset` and retry with exponential backoff. |
| `500 Internal Server Error` | `internal_error` | An unexpected server error occurred. | Retry after a short delay. If the problem persists, contact Eaglecart support. |


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