Add or Replace Customer Postal Address

You can create or replace a customer's postal address using the following endpoint and sample payload:

POST https://example-gotransverse.com/billing/2/customers/{customer_id}/addresses

This endpoint can also create EMAIL and TELECOM addresses for customers. Refer to Add or Replace Customer Email Address and Add or Replace Customer Phone Number.

Learn what you need to know to successfully create an address in the Considerations, Before You Start, Request, and Response sections below.


Considerations

Consider the following when adding a postal address to a customer:

  • A customer can have up to four postal addresses, one for each purpose.

  • An address cannot be edited or deleted. It can only be replaced with a new address of the same address_type and purpose.

Before You Start

You will need the following when creating a new postal address:

  • The id of the customer entity to update as the endpoint's {customer_id} path parameter.

Request

Copy 
{
    "address_type": "postal",
    "purpose": "SHIPPING",
    "country": "USA",
    "city": "Detroit",
    "line1": "173 Main St",
    "region_or_state": "MI",
    "postal_code": "48190"
}
Create Customer Postal Address Request Fields
Name Description Data Type Required or Optional Notes

address_type

The type of address to add or update. POSTAL is the required value when creating a postal address.

string

Required

 

purpose

The purpose of the postal address. Available values are:

  • BILLING — The address that appears on the invoices generated by the customer's billing accounts.

  • SERVICE — The default address for services added to the customer's billing accounts.

  • SHIPPING — The physical address to receive shipments.

  • PAYMENT — The address associated with payments. The address is for information purposes only and not referenced by other areas of the system.

string

Required

When a postal address of the same purpose is posted, the previous address is overwritten.

 

country

The country of the postal address.

string

Required

Refer to Country Codes.

city

The city of the postal address.

string

Optional

 

region_or_state

The region, state, or territory of the postal address.

string

Optional

Addresses for Canada, Mexico, and the United States of America require a valid region_or_state value.

Refer to Region or State Codes.

attention

Additional line for postal address.

string

Optional

  

postal_code

The postal code for the postal address.

string

Optional

Addresses for Canada, Mexico, and the United States of America require a valid postal_code value.

line1

The first line of the postal address.

string

Required

 

line2

The second line of the postal address.

string

Optional

  

p_code

A code used by the Avalara Communications Tax processor to represent the address when calculating taxes.

The value is populated by Avalara and is only editable when p_code_overridden = TRUE.

string

Optional

Required when the p_code_overridden value is TRUE.

incorporated

Specifies if the address is considered incorporated and used by the Avalara Communications Tax processor when calculating taxes.

  • TRUE — The address is in a city of other incorporated area.

  • FALSE — (default) The address is not in a city of other incorporated area.

The value is populated by Avalara and is only editable when p_code_overridden = TRUE.

boolean

Optional

  

p_code_overridden

Specifies if the p_code and incorporated values provided by Avalara can be edited and saved.

  • TRUE — The p_code and incorporated values can be edited and will not be updated by Avalara.

  • FALSE — (default) The p_code and incorporated values are updated by Avalara.

boolean

Optional

 

Response

When successful, the new address entity is returned with an id assigned.

Copy 
{
    "address_type": "postal",
    "id": "21082",
    "purpose": "SHIPPING",
    "country": "USA",
    "city": "Detroit",
    "line1": "173 Main St",
    "region_or_state": "MI",
    "postal_code": "48190"
}

 

 

 

Topic Updated: 4/2025.