> 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 Company Role

PUT https://api-b2b.bigcommerce.com/api/v3/io/companies/roles/{roleId}
Content-Type: application/json

Updates the name and permissions of a custom Company user role. You cannot update predefined roles.

When formatting the request body, you must add all permissions that you wish to keep in the role, including its existing permissions. See [Permission Codes](/developer/api-reference/rest/b2b/management/company/companies#permission-codes) for a list of predefined permission `name` and `code` values.

Reference: https://docs.bigcommerce.com/developer/api-reference/rest/b2b/management/company/company-roles-and-permissions/put-stores-companies-roles-role-id

## Authentication

- `X-Auth-Token` header (required) — | 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). | 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).
- `X-Store-Hash` header (required) — | Header | Argument | Description | |:-------|:---------|:------------| | `X-Store-Hash` | `store_hash` | The unique store hash associated with a BigCommerce store that has B2B Edition enabled. |

## Request

### Path parameters

- `roleId` (integer, required) — The unique identifier for a Company user role.

### Body (application/json)

This endpoint expects a role_REQUEST.

- `name` (string, required) — The name of the Company user role. This name is visible to system users and Company users.
- `permissions` (list of RoleRequestPermissionsItems, required)

## Response

### 200

OK

- `code` (integer, optional)
- `data` (RoleDetailResponseData, optional)
- `meta` (RoleDetailResponseMeta, optional)

## Types

### RoleRequestPermissionsItems

- `code` (string, required) — The [code string](/developer/api-reference/rest/b2b/management/company/companies#permission-code) for the permission.
- `permissionLevel` (enum, required) — The scope level for permission.
  - Allowed values: `1`, `2`

### RoleDetailResponseData

- `id` (integer, optional) — The unique identifier for the Company user role.
- `name` (string, optional) — The name of the Company user role. This name is visible to system users and Company users.
- `roleType` (enum, optional) — Indicates whether a Company user role is predefined or custom. If this value is `1`, the role is predefined. If this value is `2`, the role is custom.
  - Allowed values: `1`, `2`
- `roleLevel` (enum, optional) — Indicates how many Company accounts can view and assign the role to users. Currently, all Company roles are available at the store level, which has a value of `1`.
  - Allowed values: `1`
- `permissions` (list of RoleDetailResponseDataPermissionsItems, optional)

### RoleDetailResponseMeta

- `message` (string, optional)

### RoleDetailResponseDataPermissionsItems

- `id` (integer, optional) — The unique identifier for the Company user role.
- `code` (string, optional) — The [code string](/developer/api-reference/rest/b2b/management/company/companies#permission-code) for the permission.
- `permissionLevel` (enum, optional) — The scope level for permission.
  - Allowed values: `1`, `2`

## Examples

**Request**

```json
{
  "name": "io test",
  "permissions": [
    {
      "code": "get_addresses",
      "permissionLevel": 2
    }
  ]
}
```

**Response**

```json
{
  "code": 200,
  "data": {
    "id": 1,
    "name": "Procurement Manager",
    "roleType": 2,
    "roleLevel": 1,
    "permissions": [
      {
        "id": 1,
        "code": "get_addresses",
        "permissionLevel": 2
      }
    ]
  },
  "meta": {
    "message": "SUCCESS"
  }
}
```

**SDK Code**

```python Example 1
import requests

url = "https://api-b2b.bigcommerce.com/api/v3/io/companies/roles/123456"

payload = {
    "name": "io test",
    "permissions": [
        {
            "code": "get_addresses",
            "permissionLevel": 2
        }
    ]
}
headers = {
    "X-Auth-Token": "<apiKey>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

```javascript Example 1
const url = 'https://api-b2b.bigcommerce.com/api/v3/io/companies/roles/123456';
const options = {
  method: 'PUT',
  headers: {'X-Auth-Token': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"name":"io test","permissions":[{"code":"get_addresses","permissionLevel":2}]}'
};

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

```go Example 1
package main

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

func main() {

	url := "https://api-b2b.bigcommerce.com/api/v3/io/companies/roles/123456"

	payload := strings.NewReader("{\n  \"name\": \"io test\",\n  \"permissions\": [\n    {\n      \"code\": \"get_addresses\",\n      \"permissionLevel\": 2\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 Example 1
require 'uri'
require 'net/http'

url = URI("https://api-b2b.bigcommerce.com/api/v3/io/companies/roles/123456")

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  \"name\": \"io test\",\n  \"permissions\": [\n    {\n      \"code\": \"get_addresses\",\n      \"permissionLevel\": 2\n    }\n  ]\n}"

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

```java Example 1
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.put("https://api-b2b.bigcommerce.com/api/v3/io/companies/roles/123456")
  .header("X-Auth-Token", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"io test\",\n  \"permissions\": [\n    {\n      \"code\": \"get_addresses\",\n      \"permissionLevel\": 2\n    }\n  ]\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api-b2b.bigcommerce.com/api/v3/io/companies/roles/123456', [
  'body' => '{
  "name": "io test",
  "permissions": [
    {
      "code": "get_addresses",
      "permissionLevel": 2
    }
  ]
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'X-Auth-Token' => '<apiKey>',
  ],
]);

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

```csharp Example 1
using RestSharp;

var client = new RestClient("https://api-b2b.bigcommerce.com/api/v3/io/companies/roles/123456");
var request = new RestRequest(Method.PUT);
request.AddHeader("X-Auth-Token", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"name\": \"io test\",\n  \"permissions\": [\n    {\n      \"code\": \"get_addresses\",\n      \"permissionLevel\": 2\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Example 1
import Foundation

let headers = [
  "X-Auth-Token": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "name": "io test",
  "permissions": [
    [
      "code": "get_addresses",
      "permissionLevel": 2
    ]
  ]
] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api-b2b.bigcommerce.com/api/v3/io/companies/roles/123456")! 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()
```