Paddle Billing


Address entities hold billing address information for a customer. They're sub-entities of customers.

Addresses store components of a customer billing address. They're always created against a customer entity.

You can create as many addresses as you like against a customer — useful for billing companies with different locations.

Address entities hold address components like:

  • Country
  • ZIP/postal code
  • State (region)
  • A short, internal description for this address

Customers, addresses, and businesses work with checkouts, transactions, and subscriptions to bill for products and prices.

You can't bill a customer without an address. To make buying as frictionless as possible, Paddle only requires a country except in some regions where a ZIP or postal code is also required.

Learn how to create a complete customer with a related address and business. See: Work with customers

There's no delete operation for addresses. Use the update an address operation to archive addresses when you no longer need them. See: Delete entities



Unique Paddle ID for this address entity, prefixed with add_.


Paddle ID for the customer related to this address, prefixed with cus_.

descriptionstring or null

Memorable description for this address.

first_linestring or null

First line of this address.

second_linestring or null

Second line of this address.

citystring or null

City of this address.

postal_codestring or null

ZIP or postal code of this address. Required for some countries.

regionstring or null

State, county, or region of this address.


Supported two-letter ISO 3166-1 alpha-2 country code for this address.

custom_dataobject or null

Your own structured key-value data.


Whether this entity can be used in Paddle.


RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.


RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.

import_metaobject or null

Import information for this entity. null if this entity is not imported.

external_idstring or null

Reference or identifier for this entity from the solution where it was imported from.


Name of the platform where this entity was imported from.

List addresses for a customer
Create an addresses for a customer
Get an address for a customer
Update an address for a customer