The REST Admin API is a legacy API as of October 1, 2024. Starting April 1, 2025, all new public apps must be built exclusively with the GraphQL Admin API. For details and migration steps, visit our migration guide.
Customer Address
Requires
customers access scope.Requires access to protected customer data.
The Customer Address resource represents addresses that a customer has added. Each customer can have multiple addresses associated with them.
For more information about the Customer resource, see Customer.
Was this section helpful?
#
Endpoints
- post/admin/api/2025-01/customers/{customer_
id}/addresses. json Creates a new address for a customer - get/admin/api/2025-01/customers/{customer_
id}/addresses. json?limit=1 Retrieves a list of addresses for a customer - get/admin/api/2025-01/customers/{customer_
id}/addresses/{address_ id}. json Retrieves details for a single customer address - put/admin/api/2025-01/customers/{customer_
id}/addresses/{address_ id}. json Updates an existing customer address - put/admin/api/2025-01/customers/{customer_
id}/addresses/{address_ id}/default. json Sets the default address for a customer - put/admin/api/2025-01/customers/{customer_
id}/addresses/set. json?address_ ids[]=1053317311&operation=destroy Performs bulk operations for multiple customer addresses - del/admin/api/2025-01/customers/{customer_
id}/addresses/{address_ id}. json Removes an address from a customer’s address list
Anchor to
The Customer Address resource
Anchor to
Properties
address1
->
address1
The customer's mailing address
address2
->
address2
An additional field for the customer's mailing address.
city
->
city
The customer's city, town, or village.
country
->
country
The customer's country.
The two-letter country code corresponding to the customer's country.
country_name
->
country
The customer’s normalized country name.
company
->
company
The customer’s company.
customer_id
deprecated
The unique identifier for the customer.
first_name
The customer’s first name.
The unique identifier for the address.
last_name
->
lastName
The customer’s last name.
name
->
name
The customer’s first and last names.
Was this section helpful?
{}
The Customer Address resource
{
"address1": "1 Rue des Carrieres",
"address2": "Suite 1234",
"city": "Montreal",
"country": "Canada",
"country_code": "CA",
"country_name": "Canada",
"company": "Fancy Co.",
"customer_id": {
"id": 1073339470
},
"first_name": "Samuel",
"id": 207119551,
"last_name": "de Champlain",
"name": "Samuel de Champlain",
"phone": "819-555-5555",
"province": "Quebec",
"province_code": "QC",
"zip": "G1R 4P5"
}
Anchor to POST request, Creates a new address for a customerpostCreates a new address for a customer
post
Creates a new address for a customer
Creates a new address for a customer.
api_version
string
required
customer_id
string
required
Was this section helpful?
Create a new address for a customer
Create a new address for a customer
Path parameters
customer_
string
required
Was this section helpful?
post
/admin/api/2025-01/customers/207119551/addresses.
curl -d '{"address":{"address1":"1 Rue des Carrieres","address2":"Suite 1234","city":"Montreal","company":"Fancy Co.","first_name":"Samuel","last_name":"de Champlain","phone":"819-555-5555","province":"Quebec","country":"Canada","zip":"G1R 4P5","name":"Samuel de Champlain","province_code":"QC","country_code":"CA","country_name":"Canada"}}' \
-X POST "https://your-development-store.myshopify.com/admin/api/2025-01/customers/207119551/addresses.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"
{}
Response
JSON
HTTP/1.1 201 Created
{
"customer_address": {
"id": 1053317309,
"customer_id": 207119551,
"first_name": "Samuel",
"last_name": "de Champlain",
"company": "Fancy Co.",
"address1": "1 Rue des Carrieres",
"address2": "Suite 1234",
"city": "Montreal",
"province": "Quebec",
"country": "Canada",
"zip": "G1R 4P5",
"phone": "819-555-5555",
"name": "Samuel de Champlain",
"province_code": "QC",
"country_code": "CA",
"country_name": "Canada",
"default": false
}
}
examples
Create a new address for a customer
curl -d '{"address":{"address1":"1 Rue des Carrieres","address2":"Suite 1234","city":"Montreal","company":"Fancy Co.","first_name":"Samuel","last_name":"de Champlain","phone":"819-555-5555","province":"Quebec","country":"Canada","zip":"G1R 4P5","name":"Samuel de Champlain","province_code":"QC","country_code":"CA","country_name":"Canada"}}' \ -X POST "https://your-development-store.myshopify.com/admin/api/2025-01/customers/207119551/addresses.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json"const { admin, session } = await authenticate.admin(request); const customer_address = new admin.rest.resources.CustomerAddress({session: session}); customer_address.customer_id = 207119551; customer_address.address1 = "1 Rue des Carrieres"; customer_address.address2 = "Suite 1234"; customer_address.city = "Montreal"; customer_address.company = "Fancy Co."; customer_address.first_name = "Samuel"; customer_address.last_name = "de Champlain"; customer_address.phone = "819-555-5555"; customer_address.province = "Quebec"; customer_address.country = "Canada"; customer_address.zip = "G1R 4P5"; customer_address.name = "Samuel de Champlain"; customer_address.province_code = "QC"; customer_address.country_code = "CA"; customer_address.country_name = "Canada"; await customer_address.save({ update: true, });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session customer_address = ShopifyAPI::CustomerAddress.new(session: test_session) customer_address.customer_id = 207119551 customer_address.address1 = "1 Rue des Carrieres" customer_address.address2 = "Suite 1234" customer_address.city = "Montreal" customer_address.company = "Fancy Co." customer_address.first_name = "Samuel" customer_address.last_name = "de Champlain" customer_address.phone = "819-555-5555" customer_address.province = "Quebec" customer_address.country = "Canada" customer_address.zip = "G1R 4P5" customer_address.name = "Samuel de Champlain" customer_address.province_code = "QC" customer_address.country_code = "CA" customer_address.country_name = "Canada" customer_address.save!// Session is built by the OAuth process const customer_address = new shopify.rest.CustomerAddress({session: session}); customer_address.customer_id = 207119551; customer_address.address1 = "1 Rue des Carrieres"; customer_address.address2 = "Suite 1234"; customer_address.city = "Montreal"; customer_address.company = "Fancy Co."; customer_address.first_name = "Samuel"; customer_address.last_name = "de Champlain"; customer_address.phone = "819-555-5555"; customer_address.province = "Quebec"; customer_address.country = "Canada"; customer_address.zip = "G1R 4P5"; customer_address.name = "Samuel de Champlain"; customer_address.province_code = "QC"; customer_address.country_code = "CA"; customer_address.country_name = "Canada"; await customer_address.save({ update: true, });response
HTTP/1.1 201 Created{"customer_address":{"id":1053317309,"customer_id":207119551,"first_name":"Samuel","last_name":"de Champlain","company":"Fancy Co.","address1":"1 Rue des Carrieres","address2":"Suite 1234","city":"Montreal","province":"Quebec","country":"Canada","zip":"G1R 4P5","phone":"819-555-5555","name":"Samuel de Champlain","province_code":"QC","country_code":"CA","country_name":"Canada","default":false}}
Anchor to GET request, Retrieves a list of addresses for a customergetRetrieves a list of addresses for a customer
get
Retrieves a list of addresses for a customer
Retrieves a list of addresses for a customer. Note: This endpoint implements pagination by using links that are provided in the response header. To learn more, refer to Make paginated requests to the REST Admin API.
api_version
string
required
customer_id
string
required
Was this section helpful?
Retrieve a limited number of addresses for a customer
Retrieve a limited number of addresses for a customer
Query parameters
Retrieve all of a customer’s addresses
Retrieve all of a customer’s addresses
Was this section helpful?
get
/admin/api/2025-01/customers/207119551/addresses.
curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-01/customers/207119551/addresses.json?limit=1" \
-H "X-Shopify-Access-Token: {access_token}"
{}
Response
JSON
HTTP/1.1 200 OK
{
"addresses": [
{
"id": 207119551,
"customer_id": 207119551,
"first_name": null,
"last_name": null,
"company": null,
"address1": "Chestnut Street 92",
"address2": "",
"city": "Louisville",
"province": "Kentucky",
"country": "United States",
"zip": "40202",
"phone": "555-625-1199",
"name": "",
"province_code": "KY",
"country_code": "US",
"country_name": "United States",
"default": true
}
]
}
examples
Retrieve a limited number of addresses for a customer
curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-01/customers/207119551/addresses.json?limit=1" \ -H "X-Shopify-Access-Token: {access_token}"await admin.rest.resources.CustomerAddress.all({ session: session, customer_id: 207119551, limit: "1", });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session ShopifyAPI::CustomerAddress.all( session: test_session, customer_id: 207119551, limit: "1", )// Session is built by the OAuth process await shopify.rest.CustomerAddress.all({ session: session, customer_id: 207119551, limit: "1", });response
HTTP/1.1 200 OK{"addresses":[{"id":207119551,"customer_id":207119551,"first_name":null,"last_name":null,"company":null,"address1":"Chestnut Street 92","address2":"","city":"Louisville","province":"Kentucky","country":"United States","zip":"40202","phone":"555-625-1199","name":"","province_code":"KY","country_code":"US","country_name":"United States","default":true}]}Retrieve all of a customer’s addresses
curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-01/customers/207119551/addresses.json" \ -H "X-Shopify-Access-Token: {access_token}"await admin.rest.resources.CustomerAddress.all({ session: session, customer_id: 207119551, });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session ShopifyAPI::CustomerAddress.all( session: test_session, customer_id: 207119551, )// Session is built by the OAuth process await shopify.rest.CustomerAddress.all({ session: session, customer_id: 207119551, });response
HTTP/1.1 200 OK{"addresses":[{"id":207119551,"customer_id":207119551,"first_name":null,"last_name":null,"company":null,"address1":"Chestnut Street 92","address2":"","city":"Louisville","province":"Kentucky","country":"United States","zip":"40202","phone":"555-625-1199","name":"","province_code":"KY","country_code":"US","country_name":"United States","default":true}]}
Anchor to GET request, Retrieves details for a single customer addressgetRetrieves details for a single customer address
get
Retrieves details for a single customer address
Retrieves details for a single customer address.
address_id
string
required
api_version
string
required
customer_id
string
required
Was this section helpful?
Retrieve a single customer address
Retrieve a single customer address
Was this section helpful?
get
/admin/api/2025-01/customers/207119551/addresses/207119551.
curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-01/customers/207119551/addresses/207119551.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}
Response
JSON
HTTP/1.1 200 OK
{
"customer_address": {
"id": 207119551,
"customer_id": 207119551,
"first_name": null,
"last_name": null,
"company": null,
"address1": "Chestnut Street 92",
"address2": "",
"city": "Louisville",
"province": "Kentucky",
"country": "United States",
"zip": "40202",
"phone": "555-625-1199",
"name": "",
"province_code": "KY",
"country_code": "US",
"country_name": "United States",
"default": true
}
}
examples
Retrieve a single customer address
curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-01/customers/207119551/addresses/207119551.json" \ -H "X-Shopify-Access-Token: {access_token}"await admin.rest.resources.CustomerAddress.find({ session: session, customer_id: 207119551, id: 207119551, });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session ShopifyAPI::CustomerAddress.find( session: test_session, customer_id: 207119551, id: 207119551, )// Session is built by the OAuth process await shopify.rest.CustomerAddress.find({ session: session, customer_id: 207119551, id: 207119551, });response
HTTP/1.1 200 OK{"customer_address":{"id":207119551,"customer_id":207119551,"first_name":null,"last_name":null,"company":null,"address1":"Chestnut Street 92","address2":"","city":"Louisville","province":"Kentucky","country":"United States","zip":"40202","phone":"555-625-1199","name":"","province_code":"KY","country_code":"US","country_name":"United States","default":true}}
Anchor to PUT request, Updates an existing customer addressputUpdates an existing customer address
put
Updates an existing customer address
Updates an existing customer address.
address_id
string
required
api_version
string
required
customer_id
string
required
Was this section helpful?
Update the postal code of a customer address
Update the postal code of a customer address
Update the street address of a customer address
Update the street address of a customer address
Was this section helpful?
put
/admin/api/2025-01/customers/207119551/addresses/207119551.
curl -d '{"address":{"id":207119551,"zip":"90210"}}' \
-X PUT "https://your-development-store.myshopify.com/admin/api/2025-01/customers/207119551/addresses/207119551.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"
{}
Response
JSON
HTTP/1.1 200 OK
{
"customer_address": {
"customer_id": 207119551,
"zip": "90210",
"country": "United States",
"province": "Kentucky",
"city": "Louisville",
"address1": "Chestnut Street 92",
"address2": "",
"first_name": null,
"last_name": null,
"company": null,
"phone": "555-625-1199",
"id": 207119551,
"name": "",
"province_code": "KY",
"country_code": "US",
"country_name": "United States",
"default": true
}
}
examples
Update the postal code of a customer address
curl -d '{"address":{"id":207119551,"zip":"90210"}}' \ -X PUT "https://your-development-store.myshopify.com/admin/api/2025-01/customers/207119551/addresses/207119551.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json"const { admin, session } = await authenticate.admin(request); const customer_address = new admin.rest.resources.CustomerAddress({session: session}); customer_address.customer_id = 207119551; customer_address.id = 207119551; customer_address.zip = "90210"; await customer_address.save({ update: true, });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session customer_address = ShopifyAPI::CustomerAddress.new(session: test_session) customer_address.customer_id = 207119551 customer_address.id = 207119551 customer_address.zip = "90210" customer_address.save!// Session is built by the OAuth process const customer_address = new shopify.rest.CustomerAddress({session: session}); customer_address.customer_id = 207119551; customer_address.id = 207119551; customer_address.zip = "90210"; await customer_address.save({ update: true, });response
HTTP/1.1 200 OK{"customer_address":{"customer_id":207119551,"zip":"90210","country":"United States","province":"Kentucky","city":"Louisville","address1":"Chestnut Street 92","address2":"","first_name":null,"last_name":null,"company":null,"phone":"555-625-1199","id":207119551,"name":"","province_code":"KY","country_code":"US","country_name":"United States","default":true}}Update the street address of a customer address
curl -d '{"address":{"id":207119551,"address1":"Apartment 23","address2":"Chestnut Street 92"}}' \ -X PUT "https://your-development-store.myshopify.com/admin/api/2025-01/customers/207119551/addresses/207119551.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json"const { admin, session } = await authenticate.admin(request); const customer_address = new admin.rest.resources.CustomerAddress({session: session}); customer_address.customer_id = 207119551; customer_address.id = 207119551; customer_address.address1 = "Apartment 23"; customer_address.address2 = "Chestnut Street 92"; await customer_address.save({ update: true, });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session customer_address = ShopifyAPI::CustomerAddress.new(session: test_session) customer_address.customer_id = 207119551 customer_address.id = 207119551 customer_address.address1 = "Apartment 23" customer_address.address2 = "Chestnut Street 92" customer_address.save!// Session is built by the OAuth process const customer_address = new shopify.rest.CustomerAddress({session: session}); customer_address.customer_id = 207119551; customer_address.id = 207119551; customer_address.address1 = "Apartment 23"; customer_address.address2 = "Chestnut Street 92"; await customer_address.save({ update: true, });response
HTTP/1.1 200 OK{"customer_address":{"customer_id":207119551,"address1":"Apartment 23","address2":"Chestnut Street 92","country":"United States","province":"Kentucky","zip":"40202","city":"Louisville","first_name":null,"last_name":null,"company":null,"phone":"555-625-1199","id":207119551,"name":"","province_code":"KY","country_code":"US","country_name":"United States","default":true}}
Anchor to PUT request, Sets the default address for a customerputSets the default address for a customer
put
Sets the default address for a customer
Sets the default address for a customer.
address_id
string
required
api_version
string
required
customer_id
string
required
Was this section helpful?
Set a default address for a customer
Set a default address for a customer
Was this section helpful?
put
/admin/api/2025-01/customers/207119551/addresses/1053317312/default.
curl -X PUT "https://your-development-store.myshopify.com/admin/api/2025-01/customers/207119551/addresses/1053317312/default.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}
Response
JSON
HTTP/1.1 200 OK
{
"customer_address": {
"id": 1053317312,
"customer_id": 207119551,
"first_name": "Bob",
"last_name": "Norman",
"company": null,
"address1": "Chestnut Street 92",
"address2": "",
"city": "Louisville",
"province": "Kentucky",
"country": "United States",
"zip": "40202",
"phone": "555-625-1199",
"name": "Bob Norman",
"province_code": "KY",
"country_code": "US",
"country_name": "United States",
"default": true
}
}
examples
Set a default address for a customer
curl -X PUT "https://your-development-store.myshopify.com/admin/api/2025-01/customers/207119551/addresses/1053317312/default.json" \ -H "X-Shopify-Access-Token: {access_token}"const { admin, session } = await authenticate.admin(request); const customer_address = new admin.rest.resources.CustomerAddress({session: session}); customer_address.customer_id = 207119551; customer_address.id = 1053317312; await customer_address.default({});# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session customer_address = ShopifyAPI::CustomerAddress.new(session: test_session) customer_address.customer_id = 207119551 customer_address.id = 1053317312 customer_address.default( session: test_session, )// Session is built by the OAuth process const customer_address = new shopify.rest.CustomerAddress({session: session}); customer_address.customer_id = 207119551; customer_address.id = 1053317312; await customer_address.default({});response
HTTP/1.1 200 OK{"customer_address":{"id":1053317312,"customer_id":207119551,"first_name":"Bob","last_name":"Norman","company":null,"address1":"Chestnut Street 92","address2":"","city":"Louisville","province":"Kentucky","country":"United States","zip":"40202","phone":"555-625-1199","name":"Bob Norman","province_code":"KY","country_code":"US","country_name":"United States","default":true}}
Anchor to PUT request, Performs bulk operations for multiple customer addressesputPerforms bulk operations for multiple customer addresses
put
Performs bulk operations for multiple customer addresses
Performs bulk operations for multiple customer addresses.
address_ids[]
required
Performs bulk operations on a list of customer address IDs. Format: address_ids[]=1&address_ids[]=2&address_ids[]=3.
api_version
string
required
customer_id
string
required
operation
required
Operation to perform by keyword (for example, destroy)
Was this section helpful?
Destroy multiple customer addresses
Destroy multiple customer addresses
Query parameters
address_
required
Performs bulk operations on a list of customer address IDs. Format: address_ids[]=1&address_ids[]=2&address_ids[]=3.
operation=
required
Operation to perform by keyword (for example, destroy)
Was this section helpful?
put
/admin/api/2025-01/customers/207119551/addresses/set.
curl -X PUT "https://your-development-store.myshopify.com/admin/api/2025-01/customers/207119551/addresses/set.json?address_ids%5B%5D=1053317311&operation=destroy" \
-H "X-Shopify-Access-Token: {access_token}"
{}
Response
JSON
HTTP/1.1 200 OK
{}
examples
Destroy multiple customer addresses
curl -X PUT "https://your-development-store.myshopify.com/admin/api/2025-01/customers/207119551/addresses/set.json?address_ids%5B%5D=1053317311&operation=destroy" \ -H "X-Shopify-Access-Token: {access_token}"const { admin, session } = await authenticate.admin(request); const customer_address = new admin.rest.resources.CustomerAddress({session: session}); customer_address.customer_id = 207119551; await customer_address.set({ address_ids: ["1053317311"], operation: "destroy", });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session customer_address = ShopifyAPI::CustomerAddress.new(session: test_session) customer_address.customer_id = 207119551 customer_address.set( session: test_session, address_ids: ["1053317311"], operation: "destroy", )// Session is built by the OAuth process const customer_address = new shopify.rest.CustomerAddress({session: session}); customer_address.customer_id = 207119551; await customer_address.set({ address_ids: ["1053317311"], operation: "destroy", });response
HTTP/1.1 200 OK{}
Anchor to DELETE request, Removes an address from a customer’s address listdelRemoves an address from a customer’s address list
del
Removes an address from a customer’s address list
Removes an address from a customer’s address list.
address_id
string
required
api_version
string
required
customer_id
string
required
Was this section helpful?
Remove a customer address
Remove a customer address
Removing a customer’s default address fails and returns an error
Removing a customer’s default address fails and returns an error
Was this section helpful?
del
/admin/api/2025-01/customers/207119551/addresses/1053317310.
curl -X DELETE "https://your-development-store.myshopify.com/admin/api/2025-01/customers/207119551/addresses/1053317310.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}
Response
JSON
HTTP/1.1 200 OK
{}
examples
Remove a customer address
curl -X DELETE "https://your-development-store.myshopify.com/admin/api/2025-01/customers/207119551/addresses/1053317310.json" \ -H "X-Shopify-Access-Token: {access_token}"await admin.rest.resources.CustomerAddress.delete({ session: session, customer_id: 207119551, id: 1053317310, });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session ShopifyAPI::CustomerAddress.delete( session: test_session, customer_id: 207119551, id: 1053317310, )// Session is built by the OAuth process await shopify.rest.CustomerAddress.delete({ session: session, customer_id: 207119551, id: 1053317310, });response
HTTP/1.1 200 OK{}Removing a customer’s default address fails and returns an error
curl -X DELETE "https://your-development-store.myshopify.com/admin/api/2025-01/customers/207119551/addresses/207119551.json" \ -H "X-Shopify-Access-Token: {access_token}"await admin.rest.resources.CustomerAddress.delete({ session: session, customer_id: 207119551, id: 207119551, });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session ShopifyAPI::CustomerAddress.delete( session: test_session, customer_id: 207119551, id: 207119551, )// Session is built by the OAuth process await shopify.rest.CustomerAddress.delete({ session: session, customer_id: 207119551, id: 207119551, });response
HTTP/1.1 422 Unprocessable Entity{"errors":{"base":["Cannot delete the customer’s default address"]}}