> For the complete index of the 402pay docs, see [llms.txt](https://developer.402pay.co/llms.txt).

# Create a customer

Add a customer before they pay, such as an account from your own system.

`POST https://dash.402pay.co/api/v1/customers`

Customers are added for you when checkout collects an email, or when a payment names one in `customer_email`. Create one yourself to set their details before they pay: later payments with the same email link to them. You receive `customer.created`. Customers can't be deleted.

`blocked` isn't taken here. To stop someone from paying, create them, then [update them](https://developer.402pay.co/api/customers/update.md) with `blocked` set to `true`.

### Body

- `email` (string, required): Unique among your customers.
- `name` (string): Up to 80 characters. Defaults to one made from the email, such as Mateo Garcia for `mateo.garcia@example.com`.
- `note` (string): For your team, up to 500 characters.

### Errors

- 400 `invalid_request` A field is missing, unknown or out of range. `field` names it.
- 409 `customer_exists` Another customer already has this email.

Any request can also fail on its key or its body. See [errors](https://developer.402pay.co/api/errors.md).

Request, cURL:

```bash
curl -X POST "https://dash.402pay.co/api/v1/customers" \
  -H "Authorization: Bearer $PAY402_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mateo García",
    "email": "mateo.garcia@example.com",
    "note": "Invoiced monthly."
  }'
```

Request, Node.js:

```js
const response = await fetch("https://dash.402pay.co/api/v1/customers", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAY402_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Mateo García",
    email: "mateo.garcia@example.com",
    note: "Invoiced monthly."
  }),
});
const { data } = await response.json();
```

Request, Python:

```python
import os

import requests

response = requests.post(
    "https://dash.402pay.co/api/v1/customers",
    headers={
        "Authorization": f"Bearer {os.environ['PAY402_SECRET_KEY']}",
    },
    json={
        "name": "Mateo García",
        "email": "mateo.garcia@example.com",
        "note": "Invoiced monthly."
    },
)
data = response.json()["data"]
```

Response, 201 Created:

```json
{
  "data": {
    "id": "cst_6OOyvqK7aSwN8Ve8",
    "kind": "customer",
    "name": "Mateo García",
    "email": "mateo.garcia@example.com",
    "blocked": false,
    "note": "Invoiced monthly.",
    "stats": {
      "payments_count": 0,
      "incomplete_count": 0,
      "volume": {
        "amount": 0,
        "currency": "USD"
      },
      "average": null,
      "last_payment_at": null,
      "preferred_rail": null
    },
    "created_at": "2026-09-27T18:31:10.909Z",
    "updated_at": "2026-09-27T18:31:10.909Z"
  }
}
```