> 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.

# Create Customer Address

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

Creates a Customer Address. Multiple customer addresses can be created in one call.

**Required Fields**
* **customer_id**
* **first_name**
* **last_name**
* **city**
* **country_code**
* **address1**
* **state_or_province**
* **postal_code**

**Notes**
* A unique customer address is a combination of the following core address fields:
  * **customer_id**
  * **first_name**
  * **last_name**
  * **company**
  * **phone**
  * **address_type**
  * **address1**
  * **address2**
  * **city**
  * **country_code**
  * **state_or_province**
  * **postal_code**
* An attempt to create an address that already exists will result in no change to the address or custom form field values, an HTTP 200 return code, and the address will be absent from the response body.
* The default rate limit for this endpoint is 10 concurrent requests.

Reference: https://docs.bigcommerce.com/developer/api-reference/rest/admin/management/customers/v3/addresses/create-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_Post.

- `list of address_Post`

## Response

### 200

The created or updated customer addresses.

- `Addresses_createCustomersAddresses_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_Post

- `first_name` (string, required) — The first name of the customer address.
- `last_name` (string, required) — The last name of the customer address.
- `address1` (string, required) — The address 1 line.
- `city` (string, required) — The city of the customer address.
- `state_or_province` (string, required) — The state or province name spelled out in full. It is required for countries that need a state/province to complete an address. State or province codes not accepted.
- `postal_code` (string, required) — The postal code of the customer address. It is required for countries that need postal codes to complete an address.
- `country_code` (string, required) — The country code of the customer address.
- `customer_id` (integer, required) — The customer ID.
- `company` (string, optional) — The company of the customer address.
- `address2` (string, optional) — The address 2 line.
- `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) — The address custom form field values

### AddressCollectionResponse

Response payload for the BigCommerce API.

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

### ErrorResponseErrors

### formFieldValue

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

### CustomersAddressesPostResponsesContentApplicationJsonSchemaOneOf0DataItems

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

response = requests.post(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: 'POST',
  headers: {'X-Auth-Token': '<apiKey>', 'Content-Type': 'application/json'},
  body: '[{"first_name":"John","last_name":"Doe","address1":"111 E West Street","city":"Akron","state_or_province":"Ohio","postal_code":"44325","country_code":"US","customer_id":11,"address2":"654","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    \"first_name\": \"John\",\n    \"last_name\": \"Doe\",\n    \"address1\": \"111 E West Street\",\n    \"city\": \"Akron\",\n    \"state_or_province\": \"Ohio\",\n    \"postal_code\": \"44325\",\n    \"country_code\": \"US\",\n    \"customer_id\": 11,\n    \"address2\": \"654\",\n    \"phone\": \"1234567890\",\n    \"address_type\": \"residential\",\n    \"form_fields\": [\n      {\n        \"name\": \"test\",\n        \"value\": \"test\"\n      }\n    ]\n  }\n]")

	req, _ := http.NewRequest("POST", 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::Post.new(url)
request["X-Auth-Token"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "[\n  {\n    \"first_name\": \"John\",\n    \"last_name\": \"Doe\",\n    \"address1\": \"111 E West Street\",\n    \"city\": \"Akron\",\n    \"state_or_province\": \"Ohio\",\n    \"postal_code\": \"44325\",\n    \"country_code\": \"US\",\n    \"customer_id\": 11,\n    \"address2\": \"654\",\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.post("https://api.bigcommerce.com/stores/store_hash/v3/customers/addresses")
  .header("X-Auth-Token", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"first_name\": \"John\",\n    \"last_name\": \"Doe\",\n    \"address1\": \"111 E West Street\",\n    \"city\": \"Akron\",\n    \"state_or_province\": \"Ohio\",\n    \"postal_code\": \"44325\",\n    \"country_code\": \"US\",\n    \"customer_id\": 11,\n    \"address2\": \"654\",\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('POST', 'https://api.bigcommerce.com/stores/store_hash/v3/customers/addresses', [
  'body' => '[
  {
    "first_name": "John",
    "last_name": "Doe",
    "address1": "111 E West Street",
    "city": "Akron",
    "state_or_province": "Ohio",
    "postal_code": "44325",
    "country_code": "US",
    "customer_id": 11,
    "address2": "654",
    "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.POST);
request.AddHeader("X-Auth-Token", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "[\n  {\n    \"first_name\": \"John\",\n    \"last_name\": \"Doe\",\n    \"address1\": \"111 E West Street\",\n    \"city\": \"Akron\",\n    \"state_or_province\": \"Ohio\",\n    \"postal_code\": \"44325\",\n    \"country_code\": \"US\",\n    \"customer_id\": 11,\n    \"address2\": \"654\",\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 = [
  [
    "first_name": "John",
    "last_name": "Doe",
    "address1": "111 E West Street",
    "city": "Akron",
    "state_or_province": "Ohio",
    "postal_code": "44325",
    "country_code": "US",
    "customer_id": 11,
    "address2": "654",
    "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 = "POST"
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
[
  {
    "first_name": "John",
    "last_name": "Doe",
    "address1": "111 E West Street",
    "city": "Akron",
    "state_or_province": "Ohio",
    "postal_code": "44325",
    "country_code": "US",
    "customer_id": 11,
    "address2": "654",
    "phone": "1234567890",
    "address_type": "residential"
  }
]
```

**Response**

```json
{}
```

**SDK Code**

```python Duplicate customer address
import requests

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

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

response = requests.post(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: 'POST',
  headers: {'X-Auth-Token': '<apiKey>', 'Content-Type': 'application/json'},
  body: '[{"first_name":"John","last_name":"Doe","address1":"111 E West Street","city":"Akron","state_or_province":"Ohio","postal_code":"44325","country_code":"US","customer_id":11,"address2":"654","phone":"1234567890","address_type":"residential"}]'
};

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    \"first_name\": \"John\",\n    \"last_name\": \"Doe\",\n    \"address1\": \"111 E West Street\",\n    \"city\": \"Akron\",\n    \"state_or_province\": \"Ohio\",\n    \"postal_code\": \"44325\",\n    \"country_code\": \"US\",\n    \"customer_id\": 11,\n    \"address2\": \"654\",\n    \"phone\": \"1234567890\",\n    \"address_type\": \"residential\"\n  }\n]")

	req, _ := http.NewRequest("POST", 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::Post.new(url)
request["X-Auth-Token"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "[\n  {\n    \"first_name\": \"John\",\n    \"last_name\": \"Doe\",\n    \"address1\": \"111 E West Street\",\n    \"city\": \"Akron\",\n    \"state_or_province\": \"Ohio\",\n    \"postal_code\": \"44325\",\n    \"country_code\": \"US\",\n    \"customer_id\": 11,\n    \"address2\": \"654\",\n    \"phone\": \"1234567890\",\n    \"address_type\": \"residential\"\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.post("https://api.bigcommerce.com/stores/store_hash/v3/customers/addresses")
  .header("X-Auth-Token", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"first_name\": \"John\",\n    \"last_name\": \"Doe\",\n    \"address1\": \"111 E West Street\",\n    \"city\": \"Akron\",\n    \"state_or_province\": \"Ohio\",\n    \"postal_code\": \"44325\",\n    \"country_code\": \"US\",\n    \"customer_id\": 11,\n    \"address2\": \"654\",\n    \"phone\": \"1234567890\",\n    \"address_type\": \"residential\"\n  }\n]")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.bigcommerce.com/stores/store_hash/v3/customers/addresses', [
  'body' => '[
  {
    "first_name": "John",
    "last_name": "Doe",
    "address1": "111 E West Street",
    "city": "Akron",
    "state_or_province": "Ohio",
    "postal_code": "44325",
    "country_code": "US",
    "customer_id": 11,
    "address2": "654",
    "phone": "1234567890",
    "address_type": "residential"
  }
]',
  '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.POST);
request.AddHeader("X-Auth-Token", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "[\n  {\n    \"first_name\": \"John\",\n    \"last_name\": \"Doe\",\n    \"address1\": \"111 E West Street\",\n    \"city\": \"Akron\",\n    \"state_or_province\": \"Ohio\",\n    \"postal_code\": \"44325\",\n    \"country_code\": \"US\",\n    \"customer_id\": 11,\n    \"address2\": \"654\",\n    \"phone\": \"1234567890\",\n    \"address_type\": \"residential\"\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 = [
  [
    "first_name": "John",
    "last_name": "Doe",
    "address1": "111 E West Street",
    "city": "Akron",
    "state_or_province": "Ohio",
    "postal_code": "44325",
    "country_code": "US",
    "customer_id": 11,
    "address2": "654",
    "phone": "1234567890",
    "address_type": "residential"
  ]
] 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 = "POST"
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()
```