> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# Create or update customers

Customers, addresses, and businesses are the people and businesses that make purchases. Paddle automatically creates customers as part of checkout.

---

Customers are the people and businesses that make purchases. Paddle creates customers for you as part of checkout, or you can create them yourself.

{% callout type="info" %}
If you're looking to update customer, address, and business information on a completed checkout or issued invoice, see [Revise customer details on a billed or completed transaction](https://developer.paddle.com/build/sell/transactions/revise-transaction-customer-details.md)
{% /callout %}

## How it works

All purchases in Paddle require a customer. Customers are lightweight entities that hold key information like name, email, and localization information. They have two subentities:

- **Addresses**, which hold information about billing addresses
- **Businesses**, which hold information that you need when working with a business

Customers can have multiple addresses and businesses against them — useful when you're dealing with a large customer with offices in different locations. They can be linked to multiple subscriptions, too.

### Paddle Checkout creates customers

If you offer products using a self-serve motion, letting customers sign up and pay for subscriptions using a checkout, you don't generally need to create customers yourself. [Paddle Checkout](https://developer.paddle.com/concepts/sell/self-serve-checkout.md) automatically creates customers, addresses, and businesses as part of the checkout process.

When a customer enters an email address at checkout and there's already an existing customer entity for them in your system, Paddle uses the existing customer entity rather than creating a new one. This means transactions and subscriptions for the same customer are kept together, and lets you create complex multi-subscription offerings.

Paddle always creates a new address for a customer, even if matching addresses are found. This is because addresses are closely related to payment methods.

### Required fields for invoicing

To make buying as frictionless as possible, [Paddle Checkout](https://developer.paddle.com/concepts/sell/self-serve-checkout.md) only asks for the required information to complete a purchase online. This includes a customer's email address and country.

As [invoices](https://developer.paddle.com/concepts/sell/sales-assisted-invoice.md) are legal documents, Paddle requires more data against customers and addresses to make sure that they're compliant across the markets we serve.

{% collapsible title="Required fields for checkout and invoices" %}

|                        |                                               Checkout (automatically-collected transactions)                                                | Invoices (manually-collected transactions) |
| ---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------: |
| `customer.name`        |                                                           ✗                                                           |            ✓            |
| `customer.email`       |                                                             ✓                                                             |            ✓            |
| `address.first_line`   |                                                           ✗                                                           |            ✓            |
| `address.second_line`  |                                                           ✗                                                           |          ✗          |
| `address.city`         |                                                           ✗                                                           |          ✗          |
| `address.postal_code`  | In some markets  |            ✓            |
| `address.region`       |                                        In some markets                                          |            ✓            |
| `address.country_code` |                                                             ✓                                                             |            ✓            |

{% /collapsible %}

You don't have to set a business for a transaction, even when working with an invoice.

### Update information for completed transactions

Billed and completed transactions are considered financial records for compliance purposes. This means they can't be deleted or changed directly. If you update a customer, address, or business after it's been added to a transaction, the information against the transaction isn't updated.

You can revise customer information for billed or completed transactions to update information like tax or VAT number, address details, or customer name.

To learn more, see [Revise customer details on a billed or completed transaction](https://developer.paddle.com/build/sell/transactions/revise-transaction-customer-details#background.md)

## Create a customer

Create a customer to create a transaction for a person or business.

{% callout type="warning" %}
Customer email addresses must be unique in your system. Customers can be linked to multiple subscriptions, so there's no need to create a new customer for each subscription.
{% /callout %}

{% tabs sync="interaction-preference" %}
{% tab-item title="Dashboard" %}

{% instruction-steps %}

1. Go to **Paddle > Customers**.
2. Click {% mock-button icon="carbon:add" %}New customer
3. Enter the details for your new customer.
4. Click Save when you're done.

{% /instruction-steps %}

{% /dashboard-instructions %}

{% /tab-item %}

{% tab-item title="API" %}

Send a `POST` request to the `/customers` endpoint to create a customer.

Include `email` in your request. We recommend including `name` too — it's required for [billing by invoice](https://developer.paddle.com/build/invoices/create-issue-invoices.md).

You can optionally include `locale` to specify the language of emails Paddle sends, and `custom_data` to add your own structured key-value data.

{% api-example method="POST" path="/customers" href="/api-reference/customers/create-customer" %}

```json
{
  "email": "jo@example.com",
  "name": "Jo Brown"
}
```

```json
{
  "data": {
    "id": "ctm_01hv6y1jedq4p1n0yqn5ba3ky4",
    "status": "active",
    "custom_data": null,
    "name": "Jo Brown",
    "email": "jo@example.com",
    "marketing_consent": false,
    "locale": "en",
    "created_at": "2024-04-11T15:57:24.813Z",
    "updated_at": "2024-04-11T15:57:24.813Z",
    "import_meta": null
  },
  "meta": {
    "request_id": "9bcdcc29-e180-4055-ad3d-d37e5dc5e56d"
  }
}
```

{% /api-example %}

{% /tab-item %}
{% /tabs %}

## Create an address

Create an address related to a customer to say where a person or business is located.

{% tabs sync="interaction-preference" %}
{% tab-item title="Dashboard" %}

{% instruction-steps %}

1. Go to **Paddle > Customers**.
2. Find the customer you'd like to add an address to in the list, then click the  button and choose {% mock-button icon="carbon:view" %}View customer. If you haven't created a customer already, you can create one.
3. Under the **Addresses** heading, click New address
4. Enter the details for your new customer.
5. Click Save when you're done.

{% /instruction-steps %}

{% /dashboard-instructions %}

{% /tab-item %}

{% tab-item title="API" %}

Create an address using the API in two steps:

1. **Get a customer**  
   Get the Paddle ID of the customer you want to create an address for. You can skip this if you already have it.
2. **Create address**
   Send a `POST` request to the `/customers/{customer_id}/addresses` endpoint to create an address.

### Get a customer {% step=true %}

Send a `GET` request to the `/customers` endpoint to list customers.

Extract the Paddle ID of the customer you want to create an address for. You can skip this if you already have it.

{% api-example method="GET" path="/customers" href="/api-reference/customers/list-customers" %}

```json
{
  "data": [
    {
      "id": "ctm_01hv6y1jedq4p1n0yqn5ba3ky4",
      "status": "active",
      "custom_data": null,
      "name": "Jo Brown-Anderson",
      "email": "jo@example.com",
      "marketing_consent": false,
      "locale": "en",
      "created_at": "2024-04-11T15:57:24.813Z",
      "updated_at": "2024-04-11T15:59:56.658719Z",
      "import_meta": null
    },
    {
      "id": "ctm_01h844q4mznqpgqgm6evgw1w63",
      "status": "active",
      "custom_data": null,
      "name": "Jamie Price",
      "email": "jamie@example.com",
      "marketing_consent": false,
      "locale": "en",
      "created_at": "2023-08-18T10:58:05.087Z",
      "updated_at": "2024-04-11T15:55:02.727195Z",
      "import_meta": null
    },
    {
      "id": "ctm_01h844p3h41s12zs5mn4axja51",
      "status": "active",
      "custom_data": null,
      "name": "Alex Wilson",
      "email": "alex@example.com",
      "marketing_consent": false,
      "locale": "en",
      "created_at": "2023-08-18T10:57:31.172Z",
      "updated_at": "2024-04-11T15:55:19.492484Z",
      "import_meta": null
    },
    {
      "id": "ctm_01hrffh7gvp29kc7xahm8wddwa",
      "status": "active",
      "custom_data": null,
      "name": "Sam Miller",
      "email": "sam@example.com",
      "marketing_consent": false,
      "locale": "en",
      "created_at": "2024-03-08T16:49:53.691Z",
      "updated_at": "2024-04-11T16:03:57.924146Z",
      "import_meta": null
    }
  ],
  "meta": {
    "request_id": "913dee78-d496-4d13-a93e-09d834c208dd",
    "pagination": {
      "per_page": 50,
      "next": "https://api.paddle.com/customers?after=ctm_01h8441jn5pcwrfhwh78jqt8hk",
      "has_more": false,
      "estimated_total": 4
    }
  }
}
```

{% /api-example %}

### Create address {% step=true %}

Send a `POST` request to the `/customers/{customer_id}/addresses` endpoint to create an address.

Include `country_code` in your request. For some countries, `postal_code` or `region` is also required — see [supported countries](https://developer.paddle.com/concepts/sell/supported-countries-locales.md). You can optionally include address lines, a description, and `custom_data`.

{% api-example method="POST" path="/customers/{customer_id}/addresses" href="/api-reference/addresses/create-address" %}

```json
{
  "description": "Head Office",
  "first_line": "4050 Jefferson Plaza, 41st Floor",
  "city": "New York",
  "postal_code": "10021",
  "region": "NY",
  "country_code": "US"
}
```

```json
{
  "data": {
    "id": "add_01hv8gq3318ktkfengj2r75gfx",
    "status": "active",
    "customer_id": "ctm_01hv6y1jedq4p1n0yqn5ba3ky4",
    "description": "Head Office",
    "first_line": "4050 Jefferson Plaza, 41st Floor",
    "second_line": null,
    "city": "New York",
    "postal_code": "10021",
    "region": "NY",
    "country_code": "US",
    "custom_data": null,
    "created_at": "2024-04-12T06:42:58.785Z",
    "updated_at": "2024-04-12T06:42:58.785Z",
    "import_meta": null
  },
  "meta": {
    "request_id": "dd6bbb71-6551-4e4a-843c-b10611cddb6e"
  }
}
```

{% /api-example %}

{% /tab-item %}
{% /tabs %}

## Create a business

You should add a business if you're dealing with a company. You don't need to add a business if you're working with a private individual.

{% tabs sync="interaction-preference" %}
{% tab-item title="Dashboard" %}

{% instruction-steps %}

1. Go to **Paddle > Customers**.
2. Find the customer you'd like to add a business to in the list, then click the  button and choose {% mock-button icon="carbon:view" %}View customer. If you haven't created a customer already, you can create one.
3. Under the **Businesses** heading, click New business
4. Enter the details for your new business.
5. Click Save when you're done.

{% /instruction-steps %}

{% /dashboard-instructions %}

{% /tab-item %}

{% tab-item title="API" %}

Create a business using the API in two steps:

1. **Get a customer**  
   Get the Paddle ID of the customer you want to create a business for. You can skip this if you already have it.
2. **Create business**
   Send a `POST` request to the `/customers/{customer_id}/businesses` endpoint to create a business.

### Get a customer {% step=true %}

Send a `GET` request to the `/customers` endpoint to list customers.

Extract the Paddle ID of the customer you want to create a business for. You can skip this if you already have it.

{% api-example method="GET" path="/customers" href="/api-reference/customers/list-customers" %}

```json
{
  "data": [
    {
      "id": "ctm_01hv6y1jedq4p1n0yqn5ba3ky4",
      "status": "active",
      "custom_data": null,
      "name": "Jo Brown-Anderson",
      "email": "jo@example.com",
      "marketing_consent": false,
      "locale": "en",
      "created_at": "2024-04-11T15:57:24.813Z",
      "updated_at": "2024-04-11T15:59:56.658719Z",
      "import_meta": null
    },
    {
      "id": "ctm_01h844q4mznqpgqgm6evgw1w63",
      "status": "active",
      "custom_data": null,
      "name": "Jamie Price",
      "email": "jamie@example.com",
      "marketing_consent": false,
      "locale": "en",
      "created_at": "2023-08-18T10:58:05.087Z",
      "updated_at": "2024-04-11T15:55:02.727195Z",
      "import_meta": null
    },
    {
      "id": "ctm_01h844p3h41s12zs5mn4axja51",
      "status": "active",
      "custom_data": null,
      "name": "Alex Wilson",
      "email": "alex@example.com",
      "marketing_consent": false,
      "locale": "en",
      "created_at": "2023-08-18T10:57:31.172Z",
      "updated_at": "2024-04-11T15:55:19.492484Z",
      "import_meta": null
    },
    {
      "id": "ctm_01hrffh7gvp29kc7xahm8wddwa",
      "status": "active",
      "custom_data": null,
      "name": "Sam Miller",
      "email": "sam@example.com",
      "marketing_consent": false,
      "locale": "en",
      "created_at": "2024-03-08T16:49:53.691Z",
      "updated_at": "2024-04-11T16:03:57.924146Z",
      "import_meta": null
    }
  ],
  "meta": {
    "request_id": "913dee78-d496-4d13-a93e-09d834c208dd",
    "pagination": {
      "per_page": 50,
      "next": "https://api.paddle.com/customers?after=ctm_01h8441jn5pcwrfhwh78jqt8hk",
      "has_more": false,
      "estimated_total": 4
    }
  }
}
```

{% /api-example %}

### Create business {% step=true %}

Send a `POST` request to the `/customers/{customer_id}/businesses` endpoint to create a business.

Include `name` in your request. We recommend including `tax_identifier` so Paddle charges the correct amount of tax. Add `contacts` to automatically copy them on invoices. You can also include `company_number` (appears on invoices) and `custom_data`.

{% api-example method="POST" path="/customers/{customer_id}/businesses" href="/api-reference/businesses/create-business" %}

```json
{
  "name": "Uplift Inc.",
  "company_number": "555775291485",
  "tax_identifier": "555952383",
  "contacts": [
    {
      "name": "Parker Jones",
      "email": "parker@example.com"
    }
  ]
}
```

```json
{
  "data": {
    "id": "biz_01hv8hkr641vmpwytx38znv56k",
    "status": "active",
    "customer_id": "ctm_01hv6y1jedq4p1n0yqn5ba3ky4",
    "name": "Uplift Inc.",
    "company_number": "555775291485",
    "tax_identifier": "555952383",
    "contacts": [
      {
        "name": "Parker Jones",
        "email": "parker@example.com"
      }
    ],
    "custom_data": null,
    "created_at": "2024-04-12T06:58:37.892Z",
    "updated_at": "2024-04-12T06:58:37.892Z",
    "import_meta": null
  },
  "meta": {
    "request_id": "e925073f-12cd-4871-825d-2c43632edbc0"
  }
}
```

{% /api-example %}

{% /tab-item %}

{% /tabs %}