---
title: "Create a customer"
description: "Create a customer"
url: https://docs.invoicefalcon.com/api/customers/create-a-customer/
api: "API v1 reference"
method: POST
path: "/customers"
---

# Create a customer

`POST https://app.invoicefalcon.com/api/v1/external/customers`

Create a customer

## Request body

- `customer` (object, required)
  - `email` (string): e.g. `jane.doe@example.com`
  - `first_name` (string): e.g. `Jane`
  - `last_name` (string): e.g. `Doe`
  - `phone` (string): e.g. `+1 555 010 0199`
  - `tax_number` (string)
  - `eori_number` (string)
  - `tags` (string): e.g. `wholesale, vip`

## Returns

The [customer object](https://docs.invoicefalcon.com/api/customers/).

Rate limit: this call costs 2 points ([rate limits](https://docs.invoicefalcon.com/docs/rate-limiting/)).

## Examples

### Create a customer

```sh
curl -X POST "https://app.invoicefalcon.com/api/v1/external/customers" \
  -H "X-Auth-Token: $INVOICE_FALCON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "email": "jane.doe@example.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "+1 555 010 0199",
      "tags": "wholesale, vip"
    }
  }'
```

### Create with only an email

```sh
curl -X POST "https://app.invoicefalcon.com/api/v1/external/customers" \
  -H "X-Auth-Token: $INVOICE_FALCON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "email": "sam.rivera@example.com"
    }
  }'
```

### Create a business customer with tax numbers

```sh
curl -X POST "https://app.invoicefalcon.com/api/v1/external/customers" \
  -H "X-Auth-Token: $INVOICE_FALCON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "email": "accounts@northwind.example",
      "first_name": "Northwind",
      "last_name": "Traders",
      "tax_number": "GB123456789",
      "eori_number": "GB123456789000"
    }
  }'
```

## 201

Customer created.

```json
{
  "customer": {
    "id": 9203,
    "email": "sam.rivera@example.com",
    "first_name": "Sam",
    "last_name": "Rivera",
    "phone": null,
    "tax_number": null,
    "eori_number": null,
    "tags": "",
    "shopify_customer_id": 7001234999,
    "created_at": "2025-10-02T11:20:00Z",
    "updated_at": "2025-10-02T11:20:00Z"
  }
}
```

## 401

Missing or invalid API key.

```json
{
  "error": "Invalid API key"
}
```

## 403

The store is not on a paid plan. API access requires a paid Invoice Falcon plan.

```json
{
  "error": "REST API access requires a paid plan"
}
```

## 422

Request could not be processed.

```json
{
  "error": "param is missing or the value is empty: customer",
  "errors": {}
}
```

## 429

Rate limit exceeded. Check `X-RateLimit-Reset` header.

```json
{
  "error": "Rate limit exceeded",
  "retry_after": 30,
  "message": "You have exceeded the rate limit of 40 points per 60 seconds. Read requests cost 1 point(s) and write requests cost 2 point(s). Please retry after 30 second(s)."
}
```

