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

# Upsert Customer Attribute Values

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

Upserts Customer Attribute Values. Updates the attribute values on the Customer. Multiple customer attribute values can be updated in one call.

Upsert checks for an existing record. If there is none, it creates the record, if there is a matching record, it updates that record.

**Limits**
* Limit of 10 customers per call.
* Limit of 3 concurrent requests.

Reference: https://docs.bigcommerce.com/developer/api-reference/rest/admin/management/customers/v3/attribute-values/upsert-customers-attribute-values

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

- `list of attributeValue_Base`

## Response

### 200

A list of customer attribute values.

- `data` (list of CustomersAttributeValuesPutResponsesContentApplicationJsonSchemaDataItems, optional)
- `meta` (CustomersAttributeValuesPutResponsesContentApplicationJsonSchemaMeta, optional) — Data about the response, including pagination and collection totals.

## Errors

### 422 Unprocessable Entity Error

The `CustomerAttributeValue` 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

### attributeValue_Base

- `attribute_id` (integer, required) — Attribute ID.
- `value` (string, required) — Attribute value. This will always be a string, regardless of the attributeʼs type. Corresponds to `attribute_value` used in customer attribute values `GET` requests.
- `customer_id` (integer, required) — Customer ID.
- `id` (integer, optional) — Attribute value ID.

### CustomersAttributeValuesPutResponsesContentApplicationJsonSchemaDataItems

- `attribute_id` (integer, required) — Attribute ID.
- `attribute_value` (string, required) — Attribute value. This will always be a string, regardless of the attributes type. Corresponds to `value` used in customer attribute values `PUT` requests.
- `customer_id` (integer, required) — Customer ID.
- `id` (integer, optional) — Attribute value ID.
- `date_modified` (datetime, optional) — The date on which the customer attribute value was modified.
- `date_created` (datetime, optional) — The date of which the customer attribute value was created.

### CustomersAttributeValuesPutResponsesContentApplicationJsonSchemaMeta

Data about the response, including pagination and collection totals.

- `pagination` (CustomersAttributeValuesPutResponsesContentApplicationJsonSchemaMetaPagination, optional) — Data about the response, including pagination and collection totals.

### ErrorResponseErrors

### CustomersAttributeValuesPutResponsesContentApplicationJsonSchemaMetaPagination

Data about the response, including pagination and collection totals.

- `total` (integer, optional) — Total number of items in the result set.
- `count` (integer, optional) — Total number of items in the collection response.
- `per_page` (integer, optional) — The amount of items returned in the collection per page, controlled by the limit parameter.
- `current_page` (integer, optional) — The page you are currently on within the collection.
- `total_pages` (integer, optional) — The total number of pages in the collection.
- `links` (CustomersAttributeValuesPutResponsesContentApplicationJsonSchemaMetaPaginationLinks, optional) — Pagination links for the previous and next parts of the whole collection.

### CustomersAttributeValuesPutResponsesContentApplicationJsonSchemaMetaPaginationLinks

Pagination links for the previous and next parts of the whole collection.

- `previous` (string, optional) — Link to the previous page returned in the response.
- `current` (string, optional) — Link to the current page returned in the response.
- `next` (string, optional) — Link to the next page returned in the response.

## Examples

**Request**

```json
[
  {
    "attribute_id": 1,
    "value": "No",
    "customer_id": 2
  }
]
```

**Response**

```json
{
  "data": [
    {
      "attribute_id": 1,
      "attribute_value": "string",
      "customer_id": 1,
      "id": 1,
      "date_modified": "2024-01-15T09:30:00Z",
      "date_created": "2024-01-15T09:30:00Z"
    }
  ],
  "meta": {
    "pagination": {
      "total": 1,
      "count": 1,
      "per_page": 1,
      "current_page": 1,
      "total_pages": 1,
      "links": {
        "previous": "string",
        "current": "string",
        "next": "string"
      }
    }
  }
}
```

**SDK Code**

```python Example
import requests

url = "https://api.bigcommerce.com/stores/store_hash/v3/customers/attribute-values"

payload = [
    {
        "attribute_id": 1,
        "value": "No",
        "customer_id": 2
    }
]
headers = {
    "X-Auth-Token": "<apiKey>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

```javascript Example
const url = 'https://api.bigcommerce.com/stores/store_hash/v3/customers/attribute-values';
const options = {
  method: 'PUT',
  headers: {'X-Auth-Token': '<apiKey>', 'Content-Type': 'application/json'},
  body: '[{"attribute_id":1,"value":"No","customer_id":2}]'
};

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

```go Example
package main

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

func main() {

	url := "https://api.bigcommerce.com/stores/store_hash/v3/customers/attribute-values"

	payload := strings.NewReader("[\n  {\n    \"attribute_id\": 1,\n    \"value\": \"No\",\n    \"customer_id\": 2\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 Example
require 'uri'
require 'net/http'

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

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    \"attribute_id\": 1,\n    \"value\": \"No\",\n    \"customer_id\": 2\n  }\n]"

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

```java Example
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/attribute-values")
  .header("X-Auth-Token", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"attribute_id\": 1,\n    \"value\": \"No\",\n    \"customer_id\": 2\n  }\n]")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.bigcommerce.com/stores/store_hash/v3/customers/attribute-values', [
  'body' => '[
  {
    "attribute_id": 1,
    "value": "No",
    "customer_id": 2
  }
]',
  'headers' => [
    'Content-Type' => 'application/json',
    'X-Auth-Token' => '<apiKey>',
  ],
]);

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

```csharp Example
using RestSharp;

var client = new RestClient("https://api.bigcommerce.com/stores/store_hash/v3/customers/attribute-values");
var request = new RestRequest(Method.PUT);
request.AddHeader("X-Auth-Token", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "[\n  {\n    \"attribute_id\": 1,\n    \"value\": \"No\",\n    \"customer_id\": 2\n  }\n]", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Example
import Foundation

let headers = [
  "X-Auth-Token": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  [
    "attribute_id": 1,
    "value": "No",
    "customer_id": 2
  ]
] 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/attribute-values")! 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()
```