> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Update Customer Address

PUT https://api.bigcommerce.com/stores/{store_hash}/v3/customers/addresses
Content-Type: application/json

Updates a Customer Address. Multiple customer addresses can be updated in one call.

**Required Fields**
* **id** -- ID of the *Customer Address*

**Limits**
* Limit of **3** concurrent requests.

**Notes**
* A unique customer address is a combination of the following core address fields:
  * **first_name**
  * **last_name**
  * **company**
  * **phone**
  * **address_type**
  * **address1**
  * **address2**
  * **city**
  * **country_code**
  * **state_or_province**
  * **postal_code**
* An attempt to update an address such that it becomes identical to another address that already exists will result in no change to the target address or custom form field values. The response will have an HTTP 200 return code, and the address will be absent from the response body.

Reference: https://docs.bigcommerce.com/developer/api-reference/rest/admin/management/customers/v3/addresses/update-customers-addresses

## Authentication

- `X-Auth-Token` header (required) — ### OAuth scopes | UI Name | Permission | Parameter | |:--------|:-----------|:----------| | Customers | modify | `store_v2_customers` | | Customers | read-only | `store_v2_customers_read_only` | | Stored Payment Instruments | modify | `store_stored_payment_instruments` | | Stored Payment Instruments | read-only | `store_stored_payment_instruments_read_only` | ### Authentication header | Header | Argument | Description | |:-------|:---------|:------------| | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). | ### Further reading For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests). For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes). For a list of API status codes, see [API Status Codes](/developer/api-reference/rest/overview#rest-http-status-codes).

## Request

### Path parameters

- `store_hash` (string, required) — Permanent ID of the BigCommerce store.

### Headers

- `Accept` (string, optional, default: application/json) — The MIME type of the response body that the client accepts. Typically `application/json`.

### Body (application/json)

This endpoint expects a list of address_Put.

- `list of address_Put`

## Response

### 200

The created or updated customer addresses.

- `Addresses_updateCustomersAddresses_Response_200`

## Errors

### 422 Unprocessable Entity Error

The `Address` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details.

- `status` (integer, optional) — The HTTP status code.
- `title` (string, optional) — The error title describing the particular error.
- `type` (string, optional) — A link to a list of BigCommerce API status codes.
- `instance` (string, optional)
- `errors` (ErrorResponseErrors, optional)

## Types

### address_Put

- `id` (integer, required) — The unique numeric ID of the address.
- `first_name` (string, optional) — The first name of the customer address.
- `last_name` (string, optional) — The last name of the customer address.
- `company` (string, optional) — The company of the customer address.
- `address1` (string, optional) — The address 1 line.
- `address2` (string, optional) — The address 2 line.
- `city` (string, optional) — The city of the customer address.
- `state_or_province` (string, optional) — The state or province name.
- `postal_code` (string, optional) — The postal code of the customer address.
- `country_code` (string, optional) — The country code of the customer address.
- `phone` (string, optional) — The phone number of the customer address.
- `address_type` (enum, optional) — The address type. Residential or Commercial.
  - Allowed values: `residential`, `commercial`
- `form_fields` (list of formFieldValue, optional) — Array of form fields. Controlled by formfields parameter.

### AddressCollectionResponse

Response payload for the BigCommerce API.

- `data` (list of CustomersAddressesPutResponsesContentApplicationJsonSchemaOneOf0DataItems, optional)
- `meta` (MetaOpen, optional) — Response metadata.

### ErrorResponseErrors

### formFieldValue

- `name` (string, required) — The form field name.
- `value` (FormFieldValueValue, required)

### CustomersAddressesPutResponsesContentApplicationJsonSchemaOneOf0DataItems

- `address1` (string, optional) — The address 1 line.
- `address2` (string, optional) — The address 2 line.
- `address_type` (enum, optional) — The address type. Residential or Commercial.
  - Allowed values: `residential`, `commercial`
- `city` (string, optional) — The city of the customer address.
- `company` (string, optional) — The company of the customer address.
- `country` (string, optional) — The country name of the customer address.
- `country_code` (string, optional) — The country code of the customer address.
- `customer_id` (integer, optional) — The customer ID.
- `first_name` (string, optional) — The first name of the customer address.
- `id` (integer, optional) — The unique numeric ID of the address.
- `last_name` (string, optional) — The last name of the customer address.
- `phone` (string, optional) — The phone number of the customer address.
- `postal_code` (string, optional) — The postal code of the customer address.
- `state_or_province` (string, optional) — The state or province name
- `form_fields` (list of formFieldValue_Full, optional) — Array of form fields. Controlled by `formfields` parameter.

### MetaOpen

Response metadata.

### FormFieldValueValue

### formFieldValue_Full

### formFieldValue_Customer

- `name` (string, required) — The form field name.
- `value` (FormFieldValueCustomerValue, required)
- `customer_id` (integer, required)

### formFieldValue_Address

- `name` (string, required) — The form field name.
- `value` (FormFieldValueAddressValue, required)
- `address_id` (integer, required) — The Customer Address ID.

### FormFieldValueCustomerValue

### FormFieldValueAddressValue

## Examples

### Customer addresses

**Request**

```json
[
  {
    "id": 11,
    "first_name": "John",
    "last_name": "Doe",
    "address1": "111 E West Street",
    "address2": "654",
    "city": "Akron",
    "state_or_province": "Ohio",
    "postal_code": "44325",
    "country_code": "US",
    "phone": "1234567890",
    "address_type": "residential",
    "form_fields": [
      {
        "name": "test",
        "value": "test"
      }
    ]
  }
]
```

**Response**

```json
{
  "address1": "123 Example Street",
  "address2": "Building 4",
  "address_type": "residential",
  "city": "Austin",
  "company": "BigCommerce",
  "country": "United States",
  "country_code": "US",
  "customer_id": 1,
  "first_name": "John",
  "id": 18,
  "last_name": "Doe",
  "meta": {},
  "phone": "15551234567",
  "postal_code": "78759",
  "state_or_province": "Texas"
}
```

**SDK Code**

```python Customer addresses
import requests

url = "https://api.bigcommerce.com/stores/store_hash/v3/customers/addresses"

payload = [
    {
        "id": 11,
        "first_name": "John",
        "last_name": "Doe",
        "address1": "111 E West Street",
        "address2": "654",
        "city": "Akron",
        "state_or_province": "Ohio",
        "postal_code": "44325",
        "country_code": "US",
        "phone": "1234567890",
        "address_type": "residential",
        "form_fields": [
            {
                "name": "test",
                "value": "test"
            }
        ]
    }
]
headers = {
    "X-Auth-Token": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.json())
```

```javascript Customer addresses
const url = 'https://api.bigcommerce.com/stores/store_hash/v3/customers/addresses';
const options = {
  method: 'PUT',
  headers: {'X-Auth-Token': '<apiKey>', 'Content-Type': 'application/json'},
  body: '[{"id":11,"first_name":"John","last_name":"Doe","address1":"111 E West Street","address2":"654","city":"Akron","state_or_province":"Ohio","postal_code":"44325","country_code":"US","phone":"1234567890","address_type":"residential","form_fields":[{"name":"test","value":"test"}]}]'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Customer addresses
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bigcommerce.com/stores/store_hash/v3/customers/addresses"

	payload := strings.NewReader("[\n  {\n    \"id\": 11,\n    \"first_name\": \"John\",\n    \"last_name\": \"Doe\",\n    \"address1\": \"111 E West Street\",\n    \"address2\": \"654\",\n    \"city\": \"Akron\",\n    \"state_or_province\": \"Ohio\",\n    \"postal_code\": \"44325\",\n    \"country_code\": \"US\",\n    \"phone\": \"1234567890\",\n    \"address_type\": \"residential\",\n    \"form_fields\": [\n      {\n        \"name\": \"test\",\n        \"value\": \"test\"\n      }\n    ]\n  }\n]")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("X-Auth-Token", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Customer addresses
require 'uri'
require 'net/http'

url = URI("https://api.bigcommerce.com/stores/store_hash/v3/customers/addresses")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["X-Auth-Token"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "[\n  {\n    \"id\": 11,\n    \"first_name\": \"John\",\n    \"last_name\": \"Doe\",\n    \"address1\": \"111 E West Street\",\n    \"address2\": \"654\",\n    \"city\": \"Akron\",\n    \"state_or_province\": \"Ohio\",\n    \"postal_code\": \"44325\",\n    \"country_code\": \"US\",\n    \"phone\": \"1234567890\",\n    \"address_type\": \"residential\",\n    \"form_fields\": [\n      {\n        \"name\": \"test\",\n        \"value\": \"test\"\n      }\n    ]\n  }\n]"

response = http.request(request)
puts response.read_body
```

```java Customer addresses
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.put("https://api.bigcommerce.com/stores/store_hash/v3/customers/addresses")
  .header("X-Auth-Token", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"id\": 11,\n    \"first_name\": \"John\",\n    \"last_name\": \"Doe\",\n    \"address1\": \"111 E West Street\",\n    \"address2\": \"654\",\n    \"city\": \"Akron\",\n    \"state_or_province\": \"Ohio\",\n    \"postal_code\": \"44325\",\n    \"country_code\": \"US\",\n    \"phone\": \"1234567890\",\n    \"address_type\": \"residential\",\n    \"form_fields\": [\n      {\n        \"name\": \"test\",\n        \"value\": \"test\"\n      }\n    ]\n  }\n]")
  .asString();
```

```php Customer addresses
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.bigcommerce.com/stores/store_hash/v3/customers/addresses', [
  'body' => '[
  {
    "id": 11,
    "first_name": "John",
    "last_name": "Doe",
    "address1": "111 E West Street",
    "address2": "654",
    "city": "Akron",
    "state_or_province": "Ohio",
    "postal_code": "44325",
    "country_code": "US",
    "phone": "1234567890",
    "address_type": "residential",
    "form_fields": [
      {
        "name": "test",
        "value": "test"
      }
    ]
  }
]',
  'headers' => [
    'Content-Type' => 'application/json',
    'X-Auth-Token' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp Customer addresses
using RestSharp;

var client = new RestClient("https://api.bigcommerce.com/stores/store_hash/v3/customers/addresses");
var request = new RestRequest(Method.PUT);
request.AddHeader("X-Auth-Token", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "[\n  {\n    \"id\": 11,\n    \"first_name\": \"John\",\n    \"last_name\": \"Doe\",\n    \"address1\": \"111 E West Street\",\n    \"address2\": \"654\",\n    \"city\": \"Akron\",\n    \"state_or_province\": \"Ohio\",\n    \"postal_code\": \"44325\",\n    \"country_code\": \"US\",\n    \"phone\": \"1234567890\",\n    \"address_type\": \"residential\",\n    \"form_fields\": [\n      {\n        \"name\": \"test\",\n        \"value\": \"test\"\n      }\n    ]\n  }\n]", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Customer addresses
import Foundation

let headers = [
  "X-Auth-Token": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  [
    "id": 11,
    "first_name": "John",
    "last_name": "Doe",
    "address1": "111 E West Street",
    "address2": "654",
    "city": "Akron",
    "state_or_province": "Ohio",
    "postal_code": "44325",
    "country_code": "US",
    "phone": "1234567890",
    "address_type": "residential",
    "form_fields": [
      [
        "name": "test",
        "value": "test"
      ]
    ]
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.bigcommerce.com/stores/store_hash/v3/customers/addresses")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Duplicate customer address

**Request**

```json
[
  {
    "id": 11,
    "form_fields": [
      {
        "name": "test",
        "value": "test"
      }
    ]
  }
]
```

**Response**

```json
{}
```

**SDK Code**

```python Duplicate customer address
import requests

url = "https://api.bigcommerce.com/stores/store_hash/v3/customers/addresses"

payload = [
    {
        "id": 11,
        "form_fields": [
            {
                "name": "test",
                "value": "test"
            }
        ]
    }
]
headers = {
    "X-Auth-Token": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.json())
```

```javascript Duplicate customer address
const url = 'https://api.bigcommerce.com/stores/store_hash/v3/customers/addresses';
const options = {
  method: 'PUT',
  headers: {'X-Auth-Token': '<apiKey>', 'Content-Type': 'application/json'},
  body: '[{"id":11,"form_fields":[{"name":"test","value":"test"}]}]'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Duplicate customer address
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bigcommerce.com/stores/store_hash/v3/customers/addresses"

	payload := strings.NewReader("[\n  {\n    \"id\": 11,\n    \"form_fields\": [\n      {\n        \"name\": \"test\",\n        \"value\": \"test\"\n      }\n    ]\n  }\n]")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("X-Auth-Token", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Duplicate customer address
require 'uri'
require 'net/http'

url = URI("https://api.bigcommerce.com/stores/store_hash/v3/customers/addresses")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["X-Auth-Token"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "[\n  {\n    \"id\": 11,\n    \"form_fields\": [\n      {\n        \"name\": \"test\",\n        \"value\": \"test\"\n      }\n    ]\n  }\n]"

response = http.request(request)
puts response.read_body
```

```java Duplicate customer address
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.put("https://api.bigcommerce.com/stores/store_hash/v3/customers/addresses")
  .header("X-Auth-Token", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"id\": 11,\n    \"form_fields\": [\n      {\n        \"name\": \"test\",\n        \"value\": \"test\"\n      }\n    ]\n  }\n]")
  .asString();
```

```php Duplicate customer address
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.bigcommerce.com/stores/store_hash/v3/customers/addresses', [
  'body' => '[
  {
    "id": 11,
    "form_fields": [
      {
        "name": "test",
        "value": "test"
      }
    ]
  }
]',
  'headers' => [
    'Content-Type' => 'application/json',
    'X-Auth-Token' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp Duplicate customer address
using RestSharp;

var client = new RestClient("https://api.bigcommerce.com/stores/store_hash/v3/customers/addresses");
var request = new RestRequest(Method.PUT);
request.AddHeader("X-Auth-Token", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "[\n  {\n    \"id\": 11,\n    \"form_fields\": [\n      {\n        \"name\": \"test\",\n        \"value\": \"test\"\n      }\n    ]\n  }\n]", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Duplicate customer address
import Foundation

let headers = [
  "X-Auth-Token": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  [
    "id": 11,
    "form_fields": [
      [
        "name": "test",
        "value": "test"
      ]
    ]
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.bigcommerce.com/stores/store_hash/v3/customers/addresses")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```