Create or update a customer

Customers are the people and businesses that you sell products to.

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.

1
2
3
4
1{
2  "email": "jo@example.com",
3  "name": "Jo Brown"
4}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
1{
2  "data": {
3    "id": "ctm_01hv6y1jedq4p1n0yqn5ba3ky4",
4    "status": "active",
5    "custom_data": null,
6    "name": "Jo Brown",
7    "email": "jo@example.com",
8    "marketing_consent": false,
9    "locale": "en",
10    "created_at": "2024-04-11T15:57:24.813Z",
11    "updated_at": "2024-04-11T15:57:24.813Z",
12    "import_meta": null
13  },
14  "meta": {
15    "request_id": "9bcdcc29-e180-4055-ad3d-d37e5dc5e56d"
16  }
17}

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

1
2
3
4
5
6
7
8
1{
2  "description": "Head Office",
3  "first_line": "4050 Jefferson Plaza, 41st Floor",
4  "city": "New York",
5  "postal_code": "10021",
6  "region": "NY",
7  "country_code": "US"
8}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "data": {
3    "id": "add_01hv8gq3318ktkfengj2r75gfx",
4    "status": "active",
5    "customer_id": "ctm_01hv6y1jedq4p1n0yqn5ba3ky4",
6    "description": "Head Office",
7    "first_line": "4050 Jefferson Plaza, 41st Floor",
8    "second_line": null,
9    "city": "New York",
10    "postal_code": "10021",
11    "region": "NY",
12    "country_code": "US",
13    "custom_data": null,
14    "created_at": "2024-04-12T06:42:58.785Z",
15    "updated_at": "2024-04-12T06:42:58.785Z",
16    "import_meta": null
17  },
18  "meta": {
19    "request_id": "dd6bbb71-6551-4e4a-843c-b10611cddb6e"
20  }

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.

1
2
3
4
5
6
7
8
9
10
11
1{
2  "name": "Uplift Inc.",
3  "company_number": "555775291485",
4  "tax_identifier": "555952383",
5  "contacts": [
6    {
7      "name": "Parker Jones",
8      "email": "parker@example.com"
9    }
10  ]
11}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "data": {
3    "id": "biz_01hv8hkr641vmpwytx38znv56k",
4    "status": "active",
5    "customer_id": "ctm_01hv6y1jedq4p1n0yqn5ba3ky4",
6    "name": "Uplift Inc.",
7    "company_number": "555775291485",
8    "tax_identifier": "555952383",
9    "contacts": [
10      {
11        "name": "Parker Jones",
12        "email": "parker@example.com"
13      }
14    ],
15    "custom_data": null,
16    "created_at": "2024-04-12T06:58:37.892Z",
17    "updated_at": "2024-04-12T06:58:37.892Z",
18    "import_meta": null
19  },
20  "meta": {

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 your customer in the 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 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 your 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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1Paddle.Checkout.open({
2  settings: {
3      theme: "light",
4      locale: "en"
5  },
6  "customer": {
7    "id": "ctm_01gm82kny0ad1tk358gxmsq87m",
8    "address": {
9      "id": "add_01gm82v81g69n9hdb0v9sw6j40"
10    },
11    "business": {
12      "id": "biz_01gnymqsj1etmestb4yhemdavm"
13    }
14  },
15  items: [
16      {
17          priceId: 'pri_01gm81eqze2vmmvhpjg13bfeqg',
18          quantity: 1
19      },
20      {

Update a customer, address, or business

Update a customer, address, or business when your 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.

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.

1
2
3
1{
2  "status": "archived"
3}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
1{
2  "data": {
3    "id": "ctm_01h8441jn5pcwrfhwh78jqt8hk",
4    "status": "archived",
5    "name": "Sam Miller",
6    "email": "sam@example.com",
7    "marketing_consent": false,
8    "locale": "en",
9    "created_at": "2023-08-18T10:46:18.533Z",
10    "updated_at": "2023-08-18T10:46:18.533Z"
11  },
12  "meta": {
13    "request_id": "31858add-0308-4c26-90fb-266e16be0c8c"
14  }
15}

Events

Related pages