For AI agents and LLMs: a structured documentation index is available at /llms.txt. Every page has a Markdown sibling — append .md to any URL.

Skip to content
Docs

Create or update customers

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

AI summary

Create and manage customer, address, and business entities in Paddle via the dashboard or API — Paddle Checkout creates customers automatically, but you can also create them ahead of time for invoicing workflows.

  • • Customer email addresses must be unique — Paddle reuses an existing customer entity when the same email is entered at checkout.
  • • Invoices require additional fields beyond checkout: customer.name, address.first_line, address.postal_code, and address.region must all be present for compliant invoice generation.
  • • Updating a customer, address, or business after it's been linked to a billed or completed transaction does not update that transaction — use the revise transaction operation instead.

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

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 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 only asks for the required information to complete a purchase online. This includes a customer's email address and country.

As invoices are legal documents, Paddle requires more data against customers and addresses to make sure that they're compliant across the markets we serve.

Checkout (automatically-collected transactions)Invoices (manually-collected transactions)
customer.name✗✓
customer.email✓✓
address.first_line✗✓
address.second_line✗✗
address.city✗✗
address.postal_codeIn some markets✓
address.regionIn some markets✓
address.country_code✓✓

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

When creating invoices, you can add contacts to a business to automatically send them a copy of invoices from Paddle.

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

Create a customer

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

  1. Go to Paddle > Customers.
  2. Click New customer
  3. Enter the details for your new customer.
  4. Click Save when you're done.

Illustration of the create customer drawer in Paddle.

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.

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

POST /customers
Request
{
  "email": "jo@example.com",
  "name": "Jo Brown"
}
Response (201 Created)
{
  "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"
  }
}

Create an address

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

  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 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.

Illustration of the create address drawer in Paddle.

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

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.

GET /customers
Response (200 OK)
{
  "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
    }
  }
}

Create address

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. You can optionally include address lines, a description, and custom_data.

POST /customers/{customer_id}/addresses
Request
{
  "description": "Head Office",
  "first_line": "4050 Jefferson Plaza, 41st Floor",
  "city": "New York",
  "postal_code": "10021",
  "region": "NY",
  "country_code": "US"
}
Response (201 Created)
{
  "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"
  }
}

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.

  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 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.

Illustration of the create business drawer in Paddle. It shows fields for name, tax ID, and company ID.

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

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.

GET /customers
Response (200 OK)
{
  "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
    }
  }
}

Create business

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.

POST /customers/{customer_id}/businesses
Request
{
  "name": "Uplift Inc.",
  "company_number": "555775291485",
  "tax_identifier": "555952383",
  "contacts": [
    {
      "name": "Parker Jones",
      "email": "parker@example.com"
    }
  ]
}
Response (201 Created)
{
  "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"
  }
}

Events

customer.created Occurs when a customer is created.
address.created Occurs when an address is created.
business.created Occurs when a business is created.

Common errors

customer_already_exists
The customer being created already exists.
customer_email_invalid
You are trying to create or update a customer with an invalid email address.
address_location_not_allowed
You are trying to create or update an address with a location not supported by Paddle.

Was this page helpful?