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.
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.
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
Create a customer
Create a customer to create a transaction for a person or business.
Go to Paddle > Customers.
Click New customer.
Enter the details for your new address.
Click Save customer when you're done.
Create an address
Create an address related to a customer to say where a person or business is located.
Go to Paddle > Customers.
Find the customer you'd like to add an address to in the list, then click the ... action menu and choose View customer. If you haven't created a customer already, you can create one.
Under the Addresses heading, click New address.
Enter the details for your new customer.
Click Save address when you're done.
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.
Go to Paddle > Customers.
Find the customer you'd like to add a business to in the list, then click the ... action menu and choose View customer. If you haven't created a customer already, you can create one.
Under the Businesses heading, click New business.
Enter the details for your new business.
Click Save business when you're done.
Common errors
customer_already_exists | There's already a customer entity with the email address that you're using to create or update a customer. List customers using the API, passing the email query parameter to find the existing entity. |
customer_email_invalid | Email address for a customer is invalid. Check that there are no unsupported characters and it's formatted correctly. |
address_location_not_allowed | Paddle doesn't support the country for an address. Check that the country is supported. |
Events
customer.created | Occurs when you create a customer, or when Paddle.js creates a customer at checkout. |
address.created | Occurs when you create an address, or when Paddle.js creates an address at checkout. |
business.created | Occurs when you create a business, or when Paddle.js creates a business at checkout. |
