# Create a customer

Adds a new customer to the store. The email is required.

```http
POST https://larm.sa/stores/{storeId}/v1/customers
```

Scope: `customers.list:write`

The new account has no password and is not active. It becomes a real account when the owner of the email registers on the store and proves the email with a code, so an app can never open another person's orders or points. If the email or phone already belongs to a customer you receive `CUSTOMER_EXISTS`: find them with [List customers](/api/customers-list). When no name is sent, the part of the email before @ becomes the name.

## Headers

| Field | Type | Required | Description |
|---|---|---|---|
| `Idempotency-Key` | string | yes |  |


## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `email` | string (email) | yes | Saved in lowercase. |
| `phone` | string | no | A valid phone in any form. It comes back in E.164 format. |
| `name` | string | no |  |
| `first_name` | string | no |  |
| `last_name` | string | no |  |


## Response

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | object | yes |  |
| `data.id` | string | yes |  |
| `data.name` | string | yes |  |
| `data.first_name` | string | no |  |
| `data.last_name` | string | no |  |
| `data.phone` | string \| null | yes | Phone number in E.164 format, such as +966512345678, or null if it is not a valid number. |
| `data.email` | string \| null (email) | yes |  |
| `data.orders_count` | integer | yes | Delivered orders that were not refunded. |
| `data.total_spent` | string | yes | The total of those orders in SAR. |
| `data.last_order_at` | string \| null (date-time) | no |  |
| `data.created_at` | string (date-time) | yes |  |
| `execution` | object | no | Who executed the request: the app, version, installation and store. Field names here are camelCase. |
| `execution.appId` | string (uuid) | no |  |
| `execution.versionId` | string (uuid) | no |  |
| `execution.installationId` | string (uuid) | no |  |
| `execution.storeId` | string (uuid) | no |  |
| `execution.requestId` | string (uuid) | no |  |
| `execution.generation` | integer | no |  |
| `execution.routeEpoch` | integer | no |  |
| `execution.appAuthEpoch` | integer | no |  |
| `execution.grantRevision` | integer | no |  |
| `meta` | object | yes |  |
| `meta.request_id` | string (uuid) | no | The request ID; include it in any support request. |


## Example request

```bash
curl -X POST "https://larm.sa/stores/$STORE_ID/v1/customers" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: $UUID" \
  -H "Content-Type: application/json" \
  -d '{ "email": "sara@example.com", "phone": "0512345678", "first_name": "Sara", "last_name": "Alotaibi" }'
```


## Example response (200)

```json
{
  "data": {
    "id": "5821",
    "name": "Sara Alotaibi",
    "first_name": "Sara",
    "last_name": "Alotaibi",
    "phone": "+966512345678",
    "email": "sara@example.com",
    "orders_count": 0,
    "total_spent": "0.00",
    "last_order_at": null,
    "created_at": "2026-11-02T10:04:00.000Z"
  },
  "execution": {
    "appId": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
    "versionId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "installationId": "c7e4a1f2-6b3d-4e8a-9c05-1d2f3a4b5c6d",
    "storeId": "5b1d7a62-0c4e-4f38-9a51-2e7b3c9d8f10",
    "requestId": "3f0c2b8e-7a51-4c1e-9d0a-5b6f1e2d4c3a",
    "generation": 1,
    "routeEpoch": 4,
    "appAuthEpoch": 1,
    "grantRevision": 2
  },
  "meta": {
    "request_id": "3f0c2b8e-7a51-4c1e-9d0a-5b6f1e2d4c3a"
  }
}
```


## Errors

| HTTP | Code | Meaning |
|---|---|---|
| 400 | `IDEMPOTENCY_KEY_REQUIRED` | No Idempotency-Key header. |
| 409 | `CUSTOMER_EXISTS` | A customer already has this email or phone. |
| 422 | `INVALID_EMAIL` | The email is missing or not valid. |
| 422 | `INVALID_PHONE` | The phone is not valid. |
| 422 | `INVALID_TEXT` | A name is empty or too long. |
| 422 | `UNKNOWN_FIELD` | Unknown field. |
| 403 | `SCOPE_REQUIRED` | The token does not carry the required scope. |
| 503 | `APPS_SCOPE_RUNTIME_NOT_READY` | The resource is not enabled on this merchant's store yet. |