Address
Private Address API endpoints
Add a delivery address to a customer of your shop. Whether region or region_id is required depends on the country: countries that have regions require region_id and reject region, countries without regions require region and reject region_id. When neither is sent, the API tries to derive the region from the country and zip before validating.
Request body
first_nameRequiredstringlast_nameRequiredstringphoneoptionalstring | nullRequired unless the shop has optional phone numbers enabled. Must be a valid international phone number.
company_nameoptionalstring | nulladdress_oneRequiredstringaddress_twooptionalstring | nullcityRequiredstringzipRequiredstringcountry_idRequiredintegerID of a known shipping country.
region_idoptionalintegerRequired when the country has regions, and prohibited when it has none. Must be a region of country_id. When neither region_id nor region is sent, the API first tries to derive the region from the country code and zip.
regionoptionalstringFree-text region, required when the country has no regions and prohibited when it has them. When neither region nor region_id is sent, the API first tries to derive the region from the country code and zip.
customer_idRequiredintegerID of the customer the address belongs to.
ReturnsAddress
Address object response
Error responses
422objectValidation failed, for example a customer_id that is not a customer of your shop, an unknown country_id, a region_id that does not belong to that country, a region/region_id combination that does not match the country, an invalid phone number, or a zip outside 3-16 characters.
Update an address. All required fields must be sent again, but optional fields (company_name, address_two, and phone when the shop makes it optional) are merged: leaving one out keeps its current value, and sending it as an explicit null clears it. The address must belong to a customer of your shop.
Path parameters
address_idRequiredintegerAddress ID
Format: integer.
Request body
first_nameRequiredstringlast_nameRequiredstringphoneoptionalstring | nullRequired unless the shop has optional phone numbers enabled. Must be a valid international phone number.
company_nameoptionalstring | nulladdress_oneRequiredstringaddress_twooptionalstring | nullcityRequiredstringzipRequiredstringcountry_idRequiredintegerID of a known shipping country.
region_idoptionalintegerRequired when the country has regions, and prohibited when it has none. Must be a region of country_id. When neither region_id nor region is sent, the API first tries to derive the region from the country code and zip.
regionoptionalstringFree-text region, required when the country has no regions and prohibited when it has them. When neither region nor region_id is sent, the API first tries to derive the region from the country code and zip.
ReturnsAddress
Address object response
Error responses
404objectThe address does not exist or does not belong to a customer of your shop.
422objectValidation failed, for example an unknown country_id, a region_id that does not belong to that country, a region/region_id combination that does not match the country, an invalid phone number, or a zip outside 3-16 characters.
Delete an address. An address that is still linked to a subscription, or to an order awaiting delivery or a future shipment, cannot be deleted.
Path parameters
address_idRequiredintegerAddress ID
Format: integer.
ReturnsAddress
The deleted address
Error responses
404objectThe address does not exist or does not belong to a customer of your shop.
422objectThe address is in use: it is the shipping or billing address of a subscription, or the shipping address of an order awaiting delivery or a future shipment.