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

# Customers

> Keep a list of the people and businesses who pay you.

Customers are the people and businesses you invoice and make payment links for. They're your own records: nothing about a customer is sent to a payment network, so you can add them before your account is verified.

Scopes: `customers:read`, `customers:write`.

## Create a customer

```bash curl theme={null}
curl https://api.talescria.com/v1/customers \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: customer-acme" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Studio Ltd",
    "email": "accounts@acme.example",
    "additionalEmails": ["finance@acme.example"]
  }'
```

```python Python theme={null}
resp = requests.post(
    "https://api.talescria.com/v1/customers",
    headers={"Authorization": f"Bearer {token}", "Idempotency-Key": "customer-acme"},
    json={
        "name": "Acme Studio Ltd",
        "email": "accounts@acme.example",
        "additionalEmails": ["finance@acme.example"],
    },
    timeout=30,
)
customer = resp.json()["customer"]
```

`name` and `email` are required. You can also add up to five `additionalEmails` (copied on invoices), a `phone` and an `address`. Emails are stored in lower case.

## Update a customer

`PATCH /v1/customers/{id}` changes only the fields you send. Send `null` to clear `phone` or `address`.

```bash theme={null}
curl -X PATCH https://api.talescria.com/v1/customers/$CUSTOMER_ID \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"phone": null}'
```

## Delete a customer

`DELETE /v1/customers/{id}` removes the customer from your list. Payment links and invoices you made for them still show who they were for.

## Use customers

* **Invoices** are issued to a customer: see [Invoices](https://docs.talescria.com/guides/invoices.md).
* **Payment links** can name a customer with `customerId`, for your records: see [Payment links](https://docs.talescria.com/guides/payment-links.md).


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