# Manage customers

> Add, edit, credit and close customer accounts, and set up the custom fields and sign-in apps your storefront uses.

Source: https://docs.coritan.com/organizations/customers/

In the dashboard:

- /dashboard/organizations/…/customers: https://www.coritan.com/dashboard/organizations

Customers are the accounts people hold on your storefront. Most customers register themselves, but you can also create one, correct their details, add credit to their balance or close their account from the organization's **Customers** tab. The same tab holds the custom fields you store on customers and services, and your OAuth clients.

## Before you begin

- Any member can see customers. Creating, editing and closing them takes the owner or admin role, and adding credit takes the billing role or higher.
- A customer account belongs to your organization only. It is separate from any Coritan account, even one with the same email.

## Find a customer

1. In the [dashboard](https://www.coritan.com/dashboard/organizations), open the organization, then the **Customers** tab.
2. Type in **Search customers** to match a name, email, public handle, company or customer number, or choose a status in the list next to it.
3. Select a customer to open their details.

The details show the account's status and badges such as **Email verified**, **Staff account** for a member's own account and **Social sign-in only** for an account with no password. Below them are the **Credit balance**, **Currency**, **Country**, **Last sign-in** and any custom fields. **View services** and **View invoices** open those tabs filtered to the customer.

## Create a customer

1. On the **Customers** tab, select **New customer**.
2. Enter their **Email** and a **Password** of at least 8 characters.
3. Add a **First name**, **Last name**, **Company** and **Phone** if you have them.
4. Leave **Preferred currency** empty to use the default for their country, or enter a three-letter code such as `EUR`.
5. Select **Create customer**.

The customer can sign in on your storefront straight away, and receives your organization's welcome email. Your [webhooks](/organizations/webhooks/) receive `customer.created`.

## Edit a customer

1. Open the customer and select **Edit**.
2. Change the **Email**, names, **Company**, **Phone**, **Status** or **Currency**. A new currency applies to the whole account.
3. Select **Save changes**.

When you change the email, the old address receives a message about the change. Setting **Status** to **Suspended** or **Closed** stops the customer's sessions working at once and cancels any open invitations to share a server with them.

## Add credit

1. Open the customer. The credit form is under their details.
2. Enter an **Amount** above zero and a **Description**, which appears on their credit history.
3. Select **Add credit**.

The dashboard confirms the new balance. The customer can pay invoices with it, and an invoice paid from credit is not part of a [payout](/organizations/billing/payouts/).

## Close a customer's account

1. Open the customer and select **Delete**.
2. Type the customer's email to confirm, then select **Delete customer**.

> [!WARNING]
> The customer can no longer sign in, and their open sessions stop working. The account is kept with the status `closed`, together with its services and invoices, so you can set it back to **Active** with **Edit**.

## Add a custom field

Custom fields hold extra facts about a customer or a service, such as a VAT number.

1. On the **Customers** tab, in **Custom fields**, select **New field**.
2. Enter a **Label**, such as `VAT number`, and a **Key**, such as `vat_number`. The key starts with a letter, uses lowercase letters, digits and underscores, and cannot be changed later.
3. Choose a **Type** and whether it **Applies to** a **Customer** or a **Service**.
4. Add a **Default value** and tick **Required** if you need them.
5. Select **Add field**.

> [!IMPORTANT]
> Only the **Number** and **Date** types save at present. The other types in the list answer `Invalid field_type`. Through the API, `field_type` takes `string`, `number`, `boolean`, `date`, `json` or `enum`.

When you or your storefront send custom field values for a customer, the API refuses a key that is not defined (`Unknown custom field 'vat'`) and a missing required one (`Required custom field 'vat_number' is missing`). To delete a field, select the bin icon on its row and type its key. The values already stored on customers and services are deleted with it.

## Create an OAuth client

The **OAuth clients** card, visible to owners and admins, registers an application with its **Name**, **Redirect URIs** (full `http` or `https` addresses, one per line), **Allowed scopes** and **Grant types**. Select **New client**, fill them in and select **Create client**. The client secret is shown once, so copy it before you close the dialog.

> [!NOTE]
> Coritan stores the client and its secret, but it does not run an OAuth sign-in flow for them yet, so an application cannot use a client to sign a customer in.

## Troubleshooting

`Email already registered in this organization`
: Another customer of your organization has that email. Search for them instead.

`Customer limit reached (100/100)`
: Your organization holds as many customers as Coritan allows it. Close accounts you no longer need, or ask [support](https://www.coritan.com/dashboard/support) to raise the limit.

`Currency GBP is not enabled`
: Coritan does not take payment in that currency. Leave the currency empty or choose another.

`Amount must be positive`
: Enter an amount above zero.

## Related

- [Manage customer services](/organizations/customer-services/)
- [Manage customer invoices](/organizations/billing/invoices/)
- [Sign customers in to your storefront](/organizations/storefront/customer-sign-in/)
- [Look after customers in the staff console](/organizations/staff-console/customers/)

## With the API

List customers, newest first. `q` searches, `status_filter` takes `active`, `suspended`, `closed` or `banned`, and `limit` (1–200, default 50) and `offset` page the list. Add `with_total=true` for `{items, total, limit, offset, counts}`, where `counts` gives the number of customers in each status for the same search.

```bash
curl "https://api.coritan.com/api/v1/orgs/acme/customers?q=alex&with_total=true" \
  -H "Authorization: Bearer $CORITAN_TOKEN"
```

Create a customer with `email` and `password` (at least 8 characters), and optionally `first_name`, `last_name`, `company`, `phone`, `currency` and `custom_fields`:

```bash
curl -X POST https://api.coritan.com/api/v1/orgs/acme/customers \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "alex@example.com", "password": "a-long-passphrase", "first_name": "Alex", "currency": "EUR"}'
```

Read one with `GET /customers/{customer_id}`, and change it with `PATCH` on the same path and any of the fields above plus `status`. `DELETE /customers/{customer_id}` closes the account and answers `{"message": "Customer deactivated"}`.

Add credit with the amount and the description as query parameters. The answer is the new balance:

```bash
curl -X POST "https://api.coritan.com/api/v1/orgs/acme/customers/812/credit/add?amount=10.00&description=Goodwill" \
  -H "Authorization: Bearer $CORITAN_TOKEN"
```

```json
{"credit_balance": 25.0}
```

Custom fields are `GET /custom-fields` (filter with `applies_to`), `POST /custom-fields` with `field_name`, `label`, `field_type`, `applies_to` (`customer`, `service` or `product`), `options`, `default_value` and `required`, and `DELETE /custom-fields/{field_id}`. OAuth clients are `GET /oauth-clients` and `POST /oauth-clients` with `name`, `redirect_uris`, `allowed_scopes` and `grant_types`; the answer carries `client_secret` once.

## API

- `GET /api/v1/orgs/{org_slug}/customers`: The org's customers, newest first (https://docs.coritan.com/api/reference/organizations/customers/customers/#op-get-api-v1-orgs-org-slug-customers)
- `POST /api/v1/orgs/{org_slug}/customers`: Create customer (https://docs.coritan.com/api/reference/organizations/customers/customers/#op-post-api-v1-orgs-org-slug-customers)
- `GET /api/v1/orgs/{org_slug}/customers/{customer_id}`: Get customer (https://docs.coritan.com/api/reference/organizations/customers/customers/#op-get-api-v1-orgs-org-slug-customers-customer-id)
- `PATCH /api/v1/orgs/{org_slug}/customers/{customer_id}`: Update customer (https://docs.coritan.com/api/reference/organizations/customers/customers/#op-patch-api-v1-orgs-org-slug-customers-customer-id)
- `DELETE /api/v1/orgs/{org_slug}/customers/{customer_id}`: Deactivate customer (https://docs.coritan.com/api/reference/organizations/customers/customers/#op-delete-api-v1-orgs-org-slug-customers-customer-id)
- `POST /api/v1/orgs/{org_slug}/customers/{customer_id}/credit/add`: Add credit (https://docs.coritan.com/api/reference/organizations/customers/customers/#op-post-api-v1-orgs-org-slug-customers-customer-id-credit-add)
- `GET /api/v1/orgs/{org_slug}/custom-fields`: List custom fields (https://docs.coritan.com/api/reference/organizations/customers/custom-fields/#op-get-api-v1-orgs-org-slug-custom-fields)
- `POST /api/v1/orgs/{org_slug}/custom-fields`: Create custom field (https://docs.coritan.com/api/reference/organizations/customers/custom-fields/#op-post-api-v1-orgs-org-slug-custom-fields)
- `DELETE /api/v1/orgs/{org_slug}/custom-fields/{field_id}`: Delete custom field (https://docs.coritan.com/api/reference/organizations/customers/custom-fields/#op-delete-api-v1-orgs-org-slug-custom-fields-field-id)
- `GET /api/v1/orgs/{org_slug}/oauth-clients`: List OAuth clients (https://docs.coritan.com/api/reference/organizations/customers/oauth-clients/#op-get-api-v1-orgs-org-slug-oauth-clients)
- `POST /api/v1/orgs/{org_slug}/oauth-clients`: Create OAuth client (https://docs.coritan.com/api/reference/organizations/customers/oauth-clients/#op-post-api-v1-orgs-org-slug-oauth-clients)