🔒
Requires write_customer access scope.

The Create Address API enables creating a new address for a specific customer.

This API is especially useful for:

Adding a new shipping or billing address to a customer's profile.
Managing customer address details for orders and deliveries.
Supporting multi-address features for customers.

Note: The operation is scoped to a specific shop, identified by its unique domain prefix (shopdomain), ensuring all updates are applied to the correct store.

Request Parameters

Public Request Parameters

📘
Public Request Parameters

Path Parameters

Field	Type	Required	Description	Example
`customer_id`	string	Yes	Unique identifier of the customer.

Body Parameters

Field	Type	Required	Example	Description
`address.country`	string	No	`"United States"`	Country name of the address, required at least 1 character. e.g., "China".
`address.country_code`	string	No	`US`	ISO country code, required at least 1 character, e.g., "CN" for China.
`address.first_name`	string	No	`John"`	The first name of the person receiving the shipment or package.
`address.last_name`	string	No	`"Doe"`	The last name of the person receiving the shipment or package.
`address.address1`	string	No	`"123 Main St"`	This field represents the main address line, such as the house number and street name. It is used to specify the primary location of the address.
`address.address2`	string	No	`"Suite 200"`	This field represents an additional address line, such as an apartment number or suite number. It is used to provide more specific information about the location of the address.
`address.area`	string	No	`"Manhattan"`	Area or region of the address.
`address.city`	string	No	"New York"	City of the address. This field specifies the name of the city or town where the address is located.
`address.province`	string	No	`"New York"`	Province or state of the address. This field specifies the administrative division or region within a country.
`address.province_code`	string	No	`US-NM`	Province code of the address. This field specifies the abbreviated or standardized code representing the province or state.
`address.company`	string	No		Company name associated with the address.
`address.phone`	string	No	`1231231234`	Phone number associated with the consignee.
`address.phone_area_code`	string	No	`1`	Area code for the phone number. This field specifies the code used to identify a specific geographic area for telephone calls.
`address.zip`	string	No		Postal or ZIP code of the address. This field specifies the code used to identify a specific geographic area for mail delivery.
`address.gender`	string	No	`"male"`	Gender of the person, optional field. Acceptable values are "male" and "female".
`address.email`	string	No	`"john@example.com"`	Email address for the consignee. This field is used to specify the email address of the person receiving the shipment or package.
`address.default`	boolean	No	`true`	Indicates if this is the default address. "true" if this is the first address created for the user, otherwise "false".

Response Description

Public Response Fields

📘
Public Response Parameters

Success Response

Field	Type	Example	Description
`code`	string	`"success"`	Response status code
`message`	string		Descriptive message of the response
`data.cursor`	string	`"cursor_123"`	Pagination token
`data.has_more`	boolean	`true`	More results available
`data.addresses`			List of addresses
`data.addresses.id`	string	`"addr_123"`	Unique address ID
`data.addresses.customer_id`	string	`"cust_456"`	Owning customer ID
`data.addresses.first_name`	string	`"John"`	Recipient first name
`data.addresses.last_name`	string	`"Doe"`	Recipient last name
`data.addresses.company`	string	`"ACME Inc"`	Company name
`data.addresses.address1`	string	`"123 Main St"`	Primary address line
`data.addresses.address2`	string	`"Suite 200"`	Secondary address line
`data.addresses.city`	string	`"New York"`	City name
`data.addresses.province`	string	`"New York"`	State/province
`data.addresses.country`	string	`"United States"`	Country name
`data.addresses.zip`	string	`"10001"`	Postal code
`data.addresses.province_code`	string	`"NY"`	Province abbreviation
`data.addresses.country_code`	string	`"US"`	ISO country code
`data.addresses.gender`	string	`"male"`	Recipient gender
`data.addresses.phone`	string	`"12125551234"`	Contact number
`data.addresses.phone_area_code`	string	`"212"`	Phone area code
`data.addresses.area`	string	`"Manhattan"`	District/region
`data.addresses.email`	string	`"john@example.com"`	Contact email
`data.addresses.name`	string	`"John Doe"`	Full recipient name
`data.addresses.country_name`	string	`"United States"`	Official country name
`data.addresses.default`	boolean	`true`	Default address flag

Error Response

Field	Type	Example	Description
`code`	string	`InvalidParameter`	Error http message
`message`	string	``	Error message

API Structure Overview