Paddle Billing
Search

Create or update a customer

Customers, addresses, and businesses are related entities in Paddle that hold information about the people and businesses that make purchases. Create customers to start billing.

Customers are the people and businesses that make purchases.

Customer entities are lightweight, storing key information like name, email, and localization information. They have two sub-entities:

  • Addresses, which hold information about billing addresses
  • Businesses, which include 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.

Create a customer

Create a customer to start billing a person or business.

Paddle automatically creates customers and addresses for you as part of the checkout. If a customer enters a tax number, Paddle creates a related business, too.

When you're creating an invoice using the Paddle dashboard, you can add a new customer, address, and business from the new invoice screen.

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.

Send a POST request to the /customers endpoint.

POSThttps://api.paddle.com/customers

Request

Response

If successful, Paddle responds with a copy of the new customer entity.

Create an address

You'll need an address against a customer before you can create a transaction, invoice, or subscription.

To make buying as frictionless as possible, Paddle only requires a buyer's country. This is required for tax calculation and regulatory compliance purposes. You don't need to complete a full address, though we recommend this for customers that you're invoicing.

With Paddle, you can sell in over 200 countries and territories with no extra engineering effort. For a full list of supported countries, see: Supported countries

Some countries or regions require a ZIP or postal code for further tax calculation and regulatory compliance.

Paddle automatically creates a related addresses for a customer as part of the checkout.

When you're creating an invoice using the Paddle dashboard, you can add a new address from the new invoice screen.

Send a POST request to the /customers/{customer_id}/addresses endpoint.

POSThttps://api.paddle.com/customers/{customer_id}/addresses
customer_idstring

Paddle ID of the customer entity to work with.

Request

Response

If successful, Paddle responds with a copy of the new address entity.

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 selling a subscription to a private individual.

Paddle automatically creates a related business for a customer as part of the checkout if they enter a tax number.

When you're creating an invoice using the Paddle dashboard, you can add a new business from the new invoice screen.

You can add contacts to a business. This could be people in accounts or IT who should receive billing related emails. Add as many contacts as you like to a business.

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

POSThttps://api.paddle.com/customers/{customer_id}/businesses
customer_idstring

Paddle ID of the customer entity to work with.

Request

Response

If successful, Paddle responds with a copy of the new business entity.

Create a subscription for a customer

Paddle automatically creates a subscription for a customer when:

  • they pay for recurring products online using the checkout (self-serve)
  • your team create an invoice for recurring products and issue it (sales-assisted)

You can create a new subscription for a customer in the Paddle dashboard by going to Paddle > Customers, then clicking into the customer you'd like to create a subscription for.

Under the Subscriptions section, click New subscription.

Fill out the details to create your subscription.

When you create subscriptions through the Paddle dashboard, Paddle automatically creates an invoice each time a payment is due.

Prefill a customer, address, or business on a checkout

Paddle checkout lets you add a checkout to your website, letting customers sign up and pay for subscriptions. Quickly drop in an overlay checkout or seamlessly integrate an inline checkout. Learn more: Paddle checkout

When working with logged-in users, we recommend passing a customer, address, and business entity to Paddle checkout using Paddle.js. This means customers can easily purchase upgrades or new subscriptions without needing to fill out their details again.

Use the Paddle.Checkout.Open() method and include customer.id.

If you include customer.id, you may also include:

  • customer.address.id
  • customer.business.id

See: Paddle.Checkout.Open()

Update a customer, address, or business

Update a customer, address, or business when a customer's information has changed.

When developing an integration, we recommend using the API to provide a way for customers to update their information themselves in your frontend.

Send a PATCH request to relevant endpoint.

Update a customer

Update an address

Update a business

Updating contacts works like a PUT request. You should send the complete list of contacts that you'd like to be against your entity — including any existing items. If you omit an item, it's removed from the contacts list. See: Work with lists

Archive a customer, address, or business

When you no longer need a customer, address, or business, mark it as archived. The entity remains in Paddle, so you can get information about it, but it can't be applied to new transactions.

To archive a customer, address, or business, update the entity using a PATCH request.

In the body of your request, set status to archived. For example:

Request

Response

If successful, Paddle responds with the complete customer entity. The status is archived.

Events

customer.createdOccurs when you create a customer, or when Paddle.js creates a customer at checkout.
address.createdOccurs when you create an address, or when Paddle.js creates an address at checkout.
business.createdOccurs when you create a business, or when Paddle.js creates a business at checkout.
customer.updatedOccurs when you update a customer, or when Paddle.js updates a customer at checkout.
address.updatedOccurs when you update an address, or when Paddle.js updates an address at checkout.
business.updatedOccurs when you update a business, or when Paddle.js updates a business at checkout.

Related pages