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

# Create customer

> Create a new customer record.

**Required scope:** `customers:write`
**Rate limit:** 60 requests/minute
**Status code on success:** `201 Created`
**Idempotency:** supported – pass `Idempotency-Key` to safely retry. See [Idempotency](/developer-api/idempotency).

## Request body

| Field        | Type           | Required | Notes                             |
| ------------ | -------------- | -------- | --------------------------------- |
| `email`      | string (email) | yes      | Must be unique within your tenant |
| `first_name` | string         | no       | Up to 255 characters              |
| `last_name`  | string         | no       | Up to 255 characters              |

PII fields are stored encrypted at rest with deterministic lookup hashes used
for de-duplication.

## Response

```json theme={null}
{
  "id": "c0ffee00-0000-4000-8000-000000000002",
  "email": "newcustomer@example.com",
  "first_name": "Jamie",
  "last_name": "New",
  "total_ltv": "0.00",
  "created_at": "2026-04-26T01:23:45Z",
  "location_id": null
}
```

## Errors

* `409 "Customer with this email already exists"` – a customer with that
  email already exists in your tenant. Look up the existing record via
  `GET /developer/customers?search={email}`.
* `409 "Idempotency-Key was reused with a different request body. Use a fresh Idempotency-Key for a different operation."` – the supplied `Idempotency-Key` was reused with a different request body
  within the 24h replay window. See [Idempotency](/developer-api/idempotency).
* `409 "A duplicate request is already being processed. Please wait a moment and try again."` – a request with the same `Idempotency-Key` is still in flight. Retry
  shortly.
* `422` – Validation error (e.g. malformed email).

## Examples

```bash theme={null}
curl -X POST \
  -H "X-API-Key: vg_live_EXAMPLEdoNotUseThis123456" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newcustomer@example.com",
    "first_name": "Jamie",
    "last_name": "New"
  }' \
  https://api.vouchergrid.com/api/v1/developer/customers
```

```ts theme={null}
const res = await fetch(
  "https://api.vouchergrid.com/api/v1/developer/customers",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.VOUCHERGRID_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      email: "newcustomer@example.com",
      first_name: "Jamie",
      last_name: "New",
    }),
  },
);
const customer = await res.json();
```