Customer Address

Version 2019-04

The Customer Address resource represents stores the addresses that a customer has entered. Each customer can have multiple addresses associated with them.

For more information about the Customer resource, see Customer.

What you can do with Customer Address

The Shopify API lets you do the following with the Customer Address resource. More detailed versions of these general actions may be available:

GET /admin/api/2019-04/customers/#{customer_id}/addresses.json Retrieves a list of addresses for a customer
GET /admin/api/2019-04/customers/#{customer_id}/addresses/#{address_id}.json Retrieves details for a single customer address
POST /admin/api/2019-04/customers/#{customer_id}/addresses.json Creates a new address for a customer
PUT /admin/api/2019-04/customers/#{customer_id}/addresses/#{address_id}.json Updates an existing customer address
DELETE /admin/api/2019-04/customers/#{customer_id}/addresses/#{address_id}.json Removes an address from a customer’s address list
PUT /admin/api/2019-04/customers/#{customer_id}/addresses/set.json?address_ids[]=1053317330&operation=destroy Performs bulk operations for multiple customer addresses
PUT /admin/api/2019-04/customers/#{customer_id}/addresses/#{address_id}/default.json Sets the default address for a customer

Customer Address properties

address1	`"address1": "1 Rue des Carrieres"` The customer's mailing address
address2	`"address2": "Suite 1234"` An additional field for the customer's mailing address.
city	`"city": "Montreal"` The customer's city, town, or village.
country	`"country": "Canada"` The customer's country.
country_code read-only	`"country_code": "CA"` The two-letter country code corresponding to the customer's country.
country_name	`"country_name": "Canada"` The customer’s normalized country name.
company	`"company": "Fancy Co."` The customer’s company.
first_name	`"first_name": "Samuel"` The customer’s first name.
last_name	`"last_name": "de Champlain"` The customer’s last name.
name	`"name": "Samuel de Champlain"` The customer’s first and last names.
phone	`"phone": "819-555-5555"` The customer’s phone number at this address.
province	`"province": "Quebec"` The customer’s region name. Typically a province, a state, or a prefecture.
province_code read-only	`"province_code": "QC"` The two-letter code for the customer’s region.
zip	`"zip": "G1R 4P5"` The customer’s postal code, also known as zip, postcode, Eircode, etc.

Endpoints

GET /admin/api/2019-04/customers/#{customer_id}/addresses.json

Retrieves a list of addresses for a customer.

Retrieve all of a customer’s addresses

GET /admin/api/2019-04/customers/#{customer_id}/addresses.json

View 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 a limited number of addresses for a customer

GET /admin/api/2019-04/customers/#{customer_id}/addresses.json?limit=1&page=1

View 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
    }
  ]
}

GET /admin/api/2019-04/customers/#{customer_id}/addresses/#{address_id}.json

Retrieves details a single customer address.

Retrieve a single customer address

GET /admin/api/2019-04/customers/#{customer_id}/addresses/#{address_id}.json

View 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
  }
}

POST /admin/api/2019-04/customers/#{customer_id}/addresses.json

Creates a new address for a customer.

Create a new address for a customer

POST /admin/api/2019-04/customers/#{customer_id}/addresses.json

{
  "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"
  }
}

View Response

HTTP/1.1 201 Created
{
  "customer_address": {
    "id": 1053317328,
    "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
  }
}

PUT /admin/api/2019-04/customers/#{customer_id}/addresses/#{address_id}.json

Updates an existing customer address.

Update the postal code of a customer address

PUT /admin/api/2019-04/customers/#{customer_id}/addresses/#{address_id}.json

{
  "address": {
    "id": 207119551,
    "zip": "90210"
  }
}

View 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": "90210",
    "phone": "555-625-1199",
    "name": "",
    "province_code": "KY",
    "country_code": "US",
    "country_name": "United States",
    "default": true
  }
}

DELETE /admin/api/2019-04/customers/#{customer_id}/addresses/#{address_id}.json

Removes an address from a customer’s address list.

Remove a customer address

DELETE /admin/api/2019-04/customers/#{customer_id}/addresses/#{address_id}.json

View Response

HTTP/1.1 200 OK
{
}

Removing a customer’s default address fails and returns an error

DELETE /admin/api/2019-04/customers/#{customer_id}/addresses/#{address_id}.json

View Response

HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "base": [
      "Cannot delete the customer’s default address"
    ]
  }
}

PUT /admin/api/2019-04/customers/#{customer_id}/addresses/set.json?address_ids[]=1053317330&operation=destroy

Performs bulk operations for multiple customer addresses.

Destroy multiple customer addresses

PUT /admin/api/2019-04/customers/#{customer_id}/addresses/set.json?address_ids[]=1053317330&operation=destroy

View Response

HTTP/1.1 200 OK
{
}

PUT /admin/api/2019-04/customers/#{customer_id}/addresses/#{address_id}/default.json

Sets the default address for a customer.

Set a default address for a customer

PUT /admin/api/2019-04/customers/#{customer_id}/addresses/#{address_id}/default.json

View Response

HTTP/1.1 200 OK
{
  "customer_address": {
    "id": 1053317331,
    "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
  }
}

Version 2019-07

The Customer Address resource represents stores the addresses that a customer has entered. Each customer can have multiple addresses associated with them.

For more information about the Customer resource, see Customer.

What you can do with Customer Address

The Shopify API lets you do the following with the Customer Address resource. More detailed versions of these general actions may be available:

GET /admin/api/2019-07/customers/#{customer_id}/addresses.json Retrieves a list of addresses for a customer
GET /admin/api/2019-07/customers/#{customer_id}/addresses/#{address_id}.json Retrieves details for a single customer address
POST /admin/api/2019-07/customers/#{customer_id}/addresses.json Creates a new address for a customer
PUT /admin/api/2019-07/customers/#{customer_id}/addresses/#{address_id}.json Updates an existing customer address
DELETE /admin/api/2019-07/customers/#{customer_id}/addresses/#{address_id}.json Removes an address from a customer’s address list
PUT /admin/api/2019-07/customers/#{customer_id}/addresses/set.json?address_ids[]=1053317330&operation=destroy Performs bulk operations for multiple customer addresses
PUT /admin/api/2019-07/customers/#{customer_id}/addresses/#{address_id}/default.json Sets the default address for a customer

Customer Address properties

address1	`"address1": "1 Rue des Carrieres"` The customer's mailing address
address2	`"address2": "Suite 1234"` An additional field for the customer's mailing address.
city	`"city": "Montreal"` The customer's city, town, or village.
country	`"country": "Canada"` The customer's country.
country_code read-only	`"country_code": "CA"` The two-letter country code corresponding to the customer's country.
country_name	`"country_name": "Canada"` The customer’s normalized country name.
company	`"company": "Fancy Co."` The customer’s company.
first_name	`"first_name": "Samuel"` The customer’s first name.
last_name	`"last_name": "de Champlain"` The customer’s last name.
name	`"name": "Samuel de Champlain"` The customer’s first and last names.
phone	`"phone": "819-555-5555"` The customer’s phone number at this address.
province	`"province": "Quebec"` The customer’s region name. Typically a province, a state, or a prefecture.
province_code read-only	`"province_code": "QC"` The two-letter code for the customer’s region.
zip	`"zip": "G1R 4P5"` The customer’s postal code, also known as zip, postcode, Eircode, etc.

Endpoints

GET /admin/api/2019-07/customers/#{customer_id}/addresses.json

Retrieves a list of addresses for a customer.

Retrieve all of a customer’s addresses

GET /admin/api/2019-07/customers/#{customer_id}/addresses.json

View 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 a limited number of addresses for a customer

GET /admin/api/2019-07/customers/#{customer_id}/addresses.json?limit=1&page=1

View 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
    }
  ]
}

GET /admin/api/2019-07/customers/#{customer_id}/addresses/#{address_id}.json

Retrieves details a single customer address.

Retrieve a single customer address

GET /admin/api/2019-07/customers/#{customer_id}/addresses/#{address_id}.json

View 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
  }
}

POST /admin/api/2019-07/customers/#{customer_id}/addresses.json

Creates a new address for a customer.

Create a new address for a customer

POST /admin/api/2019-07/customers/#{customer_id}/addresses.json

{
  "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"
  }
}

View Response

HTTP/1.1 201 Created
{
  "customer_address": {
    "id": 1053317328,
    "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
  }
}

PUT /admin/api/2019-07/customers/#{customer_id}/addresses/#{address_id}.json

Updates an existing customer address.

Update the postal code of a customer address

PUT /admin/api/2019-07/customers/#{customer_id}/addresses/#{address_id}.json

{
  "address": {
    "id": 207119551,
    "zip": "90210"
  }
}

View 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": "90210",
    "phone": "555-625-1199",
    "name": "",
    "province_code": "KY",
    "country_code": "US",
    "country_name": "United States",
    "default": true
  }
}

DELETE /admin/api/2019-07/customers/#{customer_id}/addresses/#{address_id}.json

Removes an address from a customer’s address list.

Remove a customer address

DELETE /admin/api/2019-07/customers/#{customer_id}/addresses/#{address_id}.json

View Response

HTTP/1.1 200 OK
{
}

Removing a customer’s default address fails and returns an error

DELETE /admin/api/2019-07/customers/#{customer_id}/addresses/#{address_id}.json

View Response

HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "base": [
      "Cannot delete the customer’s default address"
    ]
  }
}

PUT /admin/api/2019-07/customers/#{customer_id}/addresses/set.json?address_ids[]=1053317330&operation=destroy

Performs bulk operations for multiple customer addresses.

Destroy multiple customer addresses

PUT /admin/api/2019-07/customers/#{customer_id}/addresses/set.json?address_ids[]=1053317330&operation=destroy

View Response

HTTP/1.1 200 OK
{
}

PUT /admin/api/2019-07/customers/#{customer_id}/addresses/#{address_id}/default.json

Sets the default address for a customer.

Set a default address for a customer

PUT /admin/api/2019-07/customers/#{customer_id}/addresses/#{address_id}/default.json

View Response

HTTP/1.1 200 OK
{
  "customer_address": {
    "id": 1053317331,
    "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
  }
}

Version 2019-10

The Customer Address resource represents stores the addresses that a customer has entered. Each customer can have multiple addresses associated with them.

For more information about the Customer resource, see Customer.

What you can do with Customer Address

The Shopify API lets you do the following with the Customer Address resource. More detailed versions of these general actions may be available:

GET /admin/api/2019-10/customers/#{customer_id}/addresses.json Retrieves a list of addresses for a customer
GET /admin/api/2019-10/customers/#{customer_id}/addresses/#{address_id}.json Retrieves details for a single customer address
POST /admin/api/2019-10/customers/#{customer_id}/addresses.json Creates a new address for a customer
PUT /admin/api/2019-10/customers/#{customer_id}/addresses/#{address_id}.json Updates an existing customer address
DELETE /admin/api/2019-10/customers/#{customer_id}/addresses/#{address_id}.json Removes an address from a customer’s address list
PUT /admin/api/2019-10/customers/#{customer_id}/addresses/set.json?address_ids[]=1053317330&operation=destroy Performs bulk operations for multiple customer addresses
PUT /admin/api/2019-10/customers/#{customer_id}/addresses/#{address_id}/default.json Sets the default address for a customer

Customer Address properties

address1	`"address1": "1 Rue des Carrieres"` The customer's mailing address
address2	`"address2": "Suite 1234"` An additional field for the customer's mailing address.
city	`"city": "Montreal"` The customer's city, town, or village.
country	`"country": "Canada"` The customer's country.
country_code read-only	`"country_code": "CA"` The two-letter country code corresponding to the customer's country.
country_name	`"country_name": "Canada"` The customer’s normalized country name.
company	`"company": "Fancy Co."` The customer’s company.
first_name	`"first_name": "Samuel"` The customer’s first name.
last_name	`"last_name": "de Champlain"` The customer’s last name.
name	`"name": "Samuel de Champlain"` The customer’s first and last names.
phone	`"phone": "819-555-5555"` The customer’s phone number at this address.
province	`"province": "Quebec"` The customer’s region name. Typically a province, a state, or a prefecture.
province_code read-only	`"province_code": "QC"` The two-letter code for the customer’s region.
zip	`"zip": "G1R 4P5"` The customer’s postal code, also known as zip, postcode, Eircode, etc.

Endpoints

GET /admin/api/2019-10/customers/#{customer_id}/addresses.json

Retrieves a list of addresses for a customer. Note: As of version 2019-10, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.

Retrieve all of a customer’s addresses

GET /admin/api/2019-10/customers/#{customer_id}/addresses.json

View 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 a limited number of addresses for a customer

GET /admin/api/2019-10/customers/#{customer_id}/addresses.json?limit=1

View 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
    }
  ]
}

GET /admin/api/2019-10/customers/#{customer_id}/addresses/#{address_id}.json

Retrieves details a single customer address.

Retrieve a single customer address

GET /admin/api/2019-10/customers/#{customer_id}/addresses/#{address_id}.json

View 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
  }
}

POST /admin/api/2019-10/customers/#{customer_id}/addresses.json

Creates a new address for a customer.

Create a new address for a customer

POST /admin/api/2019-10/customers/#{customer_id}/addresses.json

{
  "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"
  }
}

View Response

HTTP/1.1 201 Created
{
  "customer_address": {
    "id": 1053317328,
    "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
  }
}

PUT /admin/api/2019-10/customers/#{customer_id}/addresses/#{address_id}.json

Updates an existing customer address.

Update the postal code of a customer address

PUT /admin/api/2019-10/customers/#{customer_id}/addresses/#{address_id}.json

{
  "address": {
    "id": 207119551,
    "zip": "90210"
  }
}

View 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": "90210",
    "phone": "555-625-1199",
    "name": "",
    "province_code": "KY",
    "country_code": "US",
    "country_name": "United States",
    "default": true
  }
}

DELETE /admin/api/2019-10/customers/#{customer_id}/addresses/#{address_id}.json

Removes an address from a customer’s address list.

Remove a customer address

DELETE /admin/api/2019-10/customers/#{customer_id}/addresses/#{address_id}.json

View Response

HTTP/1.1 200 OK
{
}

Removing a customer’s default address fails and returns an error

DELETE /admin/api/2019-10/customers/#{customer_id}/addresses/#{address_id}.json

View Response

HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "base": [
      "Cannot delete the customer’s default address"
    ]
  }
}

PUT /admin/api/2019-10/customers/#{customer_id}/addresses/set.json?address_ids[]=1053317330&operation=destroy

Performs bulk operations for multiple customer addresses.

Destroy multiple customer addresses

PUT /admin/api/2019-10/customers/#{customer_id}/addresses/set.json?address_ids[]=1053317330&operation=destroy

View Response

HTTP/1.1 200 OK
{
}

PUT /admin/api/2019-10/customers/#{customer_id}/addresses/#{address_id}/default.json

Sets the default address for a customer.

Set a default address for a customer

PUT /admin/api/2019-10/customers/#{customer_id}/addresses/#{address_id}/default.json

View Response

HTTP/1.1 200 OK
{
  "customer_address": {
    "id": 1053317331,
    "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
  }
}

Version 2020-01 (Latest)

The Customer Address resource represents stores the addresses that a customer has entered. Each customer can have multiple addresses associated with them.

For more information about the Customer resource, see Customer.

What you can do with Customer Address

The Shopify API lets you do the following with the Customer Address resource. More detailed versions of these general actions may be available:

GET /admin/api/2020-01/customers/#{customer_id}/addresses.json Retrieves a list of addresses for a customer
GET /admin/api/2020-01/customers/#{customer_id}/addresses/#{address_id}.json Retrieves details for a single customer address
POST /admin/api/2020-01/customers/#{customer_id}/addresses.json Creates a new address for a customer
PUT /admin/api/2020-01/customers/#{customer_id}/addresses/#{address_id}.json Updates an existing customer address
DELETE /admin/api/2020-01/customers/#{customer_id}/addresses/#{address_id}.json Removes an address from a customer’s address list
PUT /admin/api/2020-01/customers/#{customer_id}/addresses/set.json?address_ids[]=1053317330&operation=destroy Performs bulk operations for multiple customer addresses
PUT /admin/api/2020-01/customers/#{customer_id}/addresses/#{address_id}/default.json Sets the default address for a customer

Customer Address properties

address1	`"address1": "1 Rue des Carrieres"` The customer's mailing address
address2	`"address2": "Suite 1234"` An additional field for the customer's mailing address.
city	`"city": "Montreal"` The customer's city, town, or village.
country	`"country": "Canada"` The customer's country.
country_code read-only	`"country_code": "CA"` The two-letter country code corresponding to the customer's country.
country_name	`"country_name": "Canada"` The customer’s normalized country name.
company	`"company": "Fancy Co."` The customer’s company.
first_name	`"first_name": "Samuel"` The customer’s first name.
last_name	`"last_name": "de Champlain"` The customer’s last name.
name	`"name": "Samuel de Champlain"` The customer’s first and last names.
phone	`"phone": "819-555-5555"` The customer’s phone number at this address.
province	`"province": "Quebec"` The customer’s region name. Typically a province, a state, or a prefecture.
province_code read-only	`"province_code": "QC"` The two-letter code for the customer’s region.
zip	`"zip": "G1R 4P5"` The customer’s postal code, also known as zip, postcode, Eircode, etc.

Endpoints

GET /admin/api/2020-01/customers/#{customer_id}/addresses.json

Retrieve all of a customer’s addresses

GET /admin/api/2020-01/customers/#{customer_id}/addresses.json

View 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 a limited number of addresses for a customer

GET /admin/api/2020-01/customers/#{customer_id}/addresses.json?limit=1

View 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
    }
  ]
}

GET /admin/api/2020-01/customers/#{customer_id}/addresses/#{address_id}.json

Retrieves details a single customer address.

Retrieve a single customer address

GET /admin/api/2020-01/customers/#{customer_id}/addresses/#{address_id}.json

View 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
  }
}

POST /admin/api/2020-01/customers/#{customer_id}/addresses.json

Creates a new address for a customer.

Create a new address for a customer

POST /admin/api/2020-01/customers/#{customer_id}/addresses.json

{
  "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"
  }
}

View Response

HTTP/1.1 201 Created
{
  "customer_address": {
    "id": 1053317328,
    "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
  }
}

PUT /admin/api/2020-01/customers/#{customer_id}/addresses/#{address_id}.json

Updates an existing customer address.

Update the postal code of a customer address

PUT /admin/api/2020-01/customers/#{customer_id}/addresses/#{address_id}.json

{
  "address": {
    "id": 207119551,
    "zip": "90210"
  }
}

View 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": "90210",
    "phone": "555-625-1199",
    "name": "",
    "province_code": "KY",
    "country_code": "US",
    "country_name": "United States",
    "default": true
  }
}

DELETE /admin/api/2020-01/customers/#{customer_id}/addresses/#{address_id}.json

Removes an address from a customer’s address list.

Remove a customer address

DELETE /admin/api/2020-01/customers/#{customer_id}/addresses/#{address_id}.json

View Response

HTTP/1.1 200 OK
{
}

Removing a customer’s default address fails and returns an error

DELETE /admin/api/2020-01/customers/#{customer_id}/addresses/#{address_id}.json

View Response

HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "base": [
      "Cannot delete the customer’s default address"
    ]
  }
}

PUT /admin/api/2020-01/customers/#{customer_id}/addresses/set.json?address_ids[]=1053317330&operation=destroy

Performs bulk operations for multiple customer addresses.

Destroy multiple customer addresses

PUT /admin/api/2020-01/customers/#{customer_id}/addresses/set.json?address_ids[]=1053317330&operation=destroy

View Response

HTTP/1.1 200 OK
{
}

PUT /admin/api/2020-01/customers/#{customer_id}/addresses/#{address_id}/default.json

Sets the default address for a customer.

Set a default address for a customer

PUT /admin/api/2020-01/customers/#{customer_id}/addresses/#{address_id}/default.json

View Response

HTTP/1.1 200 OK
{
  "customer_address": {
    "id": 1053317331,
    "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
  }
}

Version 2020-04 (Release candidate)

The Customer Address resource represents stores the addresses that a customer has entered. Each customer can have multiple addresses associated with them.

For more information about the Customer resource, see Customer.

What you can do with Customer Address

The Shopify API lets you do the following with the Customer Address resource. More detailed versions of these general actions may be available:

GET /admin/api/2020-04/customers/#{customer_id}/addresses.json Retrieves a list of addresses for a customer
GET /admin/api/2020-04/customers/#{customer_id}/addresses/#{address_id}.json Retrieves details for a single customer address
POST /admin/api/2020-04/customers/#{customer_id}/addresses.json Creates a new address for a customer
PUT /admin/api/2020-04/customers/#{customer_id}/addresses/#{address_id}.json Updates an existing customer address
DELETE /admin/api/2020-04/customers/#{customer_id}/addresses/#{address_id}.json Removes an address from a customer’s address list
PUT /admin/api/2020-04/customers/#{customer_id}/addresses/set.json?address_ids[]=1053317330&operation=destroy Performs bulk operations for multiple customer addresses
PUT /admin/api/2020-04/customers/#{customer_id}/addresses/#{address_id}/default.json Sets the default address for a customer

Customer Address properties

address1	`"address1": "1 Rue des Carrieres"` The customer's mailing address
address2	`"address2": "Suite 1234"` An additional field for the customer's mailing address.
city	`"city": "Montreal"` The customer's city, town, or village.
country	`"country": "Canada"` The customer's country.
country_code read-only	`"country_code": "CA"` The two-letter country code corresponding to the customer's country.
country_name	`"country_name": "Canada"` The customer’s normalized country name.
company	`"company": "Fancy Co."` The customer’s company.
first_name	`"first_name": "Samuel"` The customer’s first name.
last_name	`"last_name": "de Champlain"` The customer’s last name.
name	`"name": "Samuel de Champlain"` The customer’s first and last names.
phone	`"phone": "819-555-5555"` The customer’s phone number at this address.
province	`"province": "Quebec"` The customer’s region name. Typically a province, a state, or a prefecture.
province_code read-only	`"province_code": "QC"` The two-letter code for the customer’s region.
zip	`"zip": "G1R 4P5"` The customer’s postal code, also known as zip, postcode, Eircode, etc.

Endpoints

GET /admin/api/2020-04/customers/#{customer_id}/addresses.json

Retrieve all of a customer’s addresses

GET /admin/api/2020-04/customers/#{customer_id}/addresses.json

View 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 a limited number of addresses for a customer

GET /admin/api/2020-04/customers/#{customer_id}/addresses.json?limit=1

View 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
    }
  ]
}

GET /admin/api/2020-04/customers/#{customer_id}/addresses/#{address_id}.json

Retrieves details a single customer address.

Retrieve a single customer address

GET /admin/api/2020-04/customers/#{customer_id}/addresses/#{address_id}.json

View 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
  }
}

POST /admin/api/2020-04/customers/#{customer_id}/addresses.json

Creates a new address for a customer.

Create a new address for a customer

POST /admin/api/2020-04/customers/#{customer_id}/addresses.json

{
  "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"
  }
}

View Response

HTTP/1.1 201 Created
{
  "customer_address": {
    "id": 1053317328,
    "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
  }
}

PUT /admin/api/2020-04/customers/#{customer_id}/addresses/#{address_id}.json

Updates an existing customer address.

Update the postal code of a customer address

PUT /admin/api/2020-04/customers/#{customer_id}/addresses/#{address_id}.json

{
  "address": {
    "id": 207119551,
    "zip": "90210"
  }
}

View 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": "90210",
    "phone": "555-625-1199",
    "name": "",
    "province_code": "KY",
    "country_code": "US",
    "country_name": "United States",
    "default": true
  }
}

DELETE /admin/api/2020-04/customers/#{customer_id}/addresses/#{address_id}.json

Removes an address from a customer’s address list.

Remove a customer address

DELETE /admin/api/2020-04/customers/#{customer_id}/addresses/#{address_id}.json

View Response

HTTP/1.1 200 OK
{
}

Removing a customer’s default address fails and returns an error

DELETE /admin/api/2020-04/customers/#{customer_id}/addresses/#{address_id}.json

View Response

HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "base": [
      "Cannot delete the customer’s default address"
    ]
  }
}

PUT /admin/api/2020-04/customers/#{customer_id}/addresses/set.json?address_ids[]=1053317330&operation=destroy

Performs bulk operations for multiple customer addresses.

Destroy multiple customer addresses

PUT /admin/api/2020-04/customers/#{customer_id}/addresses/set.json?address_ids[]=1053317330&operation=destroy

View Response

HTTP/1.1 200 OK
{
}

PUT /admin/api/2020-04/customers/#{customer_id}/addresses/#{address_id}/default.json

Sets the default address for a customer.

Set a default address for a customer

PUT /admin/api/2020-04/customers/#{customer_id}/addresses/#{address_id}/default.json

View Response

HTTP/1.1 200 OK
{
  "customer_address": {
    "id": 1053317331,
    "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
  }
}