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

# GraphQL Storefront API: Company user management

> Manage B2B Edition Company users with the GraphQL Storefront API — list users, look up roles, create, update, and delete users, and let users maintain their own extra fields.

BigCommerce's GraphQL Storefront API lets a signed-in user with the required permissions manage the other users of their active Company. Use it to list the Company's users, look up the roles you can assign, and create, update, or delete users. Every Company user can also read the user extra fields the store has configured and update their own extra field values.

All of these operations act on the active Company, which is the Company the signed-in user is currently representing. For how a user's active Company is determined, see [User account settings](/developer/docs/storefront/guides/graphql-storefront-api/b-2-b/company-user-account). The API resolves the active Company from the session, so no operation accepts a Company ID. The default Buyer Portal uses these operations to power its **User management** page, and you can call them directly when building a custom storefront.

## Tokens

To authenticate calls to the GraphQL Storefront API, your application can generate a bearer token. Use either the [Create a storefront token](/developer/api-reference/rest/admin/authentication-apis/storefront-api-tokens/create-token) or the [Create a customer impersonation token](/developer/api-reference/rest/admin/authentication-apis/storefront-api-tokens/customer-impersonation-token/create-token-with-customer-impersonation) REST endpoint. On a Stencil storefront, you can also [access a token](/developer/docs/storefront/guides/graphql-storefront-api) directly from the page context.

Every operation on this page requires [customer context](/developer/docs/storefront/guides/graphql-storefront-api/customer-context): the request must identify a signed-in customer who is a B2B Edition Company user or a Super Admin. Without it, `customer.activeCompany` returns `null`.

For more information, see [Storefront tokens](/developer/docs/storefront/guides/graphql-storefront-api/authentication#storefront-tokens) and [Dynamic tokens](/developer/docs/overview/api-fundamentals/api-accounts#bigcommerce-generated-jwts).

## Permissions

What a caller can do depends on the Company role of the signed-in user. B2B Edition ships three predefined roles, and store owners can create custom roles with any combination of permissions.

| Operation                            | Admin | Senior Buyer | Junior Buyer | Custom role                                             |
| ------------------------------------ | ----- | ------------ | ------------ | ------------------------------------------------------- |
| `activeCompany.users`                | Yes   | Yes          | No           | Requires **View** under User management                 |
| `activeCompany.companyRoles`         | Yes   | Yes          | Yes          | Yes                                                     |
| `activeCompany.currentUser`          | Yes   | Yes          | Yes          | Yes                                                     |
| `site.settings.b2b.extraFields.user` | Yes   | Yes          | Yes          | Yes                                                     |
| `company.createUser`                 | Yes   | No           | No           | Requires **Create, edit, delete** under User management |
| `company.updateUser`                 | Yes   | No           | No           | Requires **Create, edit, delete** under User management |
| `company.deleteUser`                 | Yes   | No           | No           | Requires **Create, edit, delete** under User management |
| `company.updateCurrentUser`          | Yes   | Yes          | Yes          | Yes                                                     |

In the control panel, **Create, edit, delete** requires **View**, so a custom role that can create, update, or delete users can always list them. The API doesn't re-check **View** on each mutation; the dependency is enforced when the role is saved.

A Super Admin who is masquerading as a Company has the same permissions as the predefined Admin role in that Company. A Super Admin who isn't masquerading has no active Company: `customer.activeCompany` is still returned, but `companyName` and `currentUser` are `null` and `users` is empty.

To learn more about Company roles, see [Company Roles and Permissions](/developer/api-reference/rest/b2b/management/company/company-roles-and-permissions) and the "Company Roles" section of [B2B Edition Settings](https://support.bigcommerce.com/s/article/B2B-Edition-Settings) in the Help Center.

## Get the user extra field definitions

Store owners can define extra fields for Company users in the B2B Edition control panel. Before you render a create or edit form, query `site.settings.b2b.extraFields.user` to learn which fields exist, which are required, and how to validate each value. The field returns `null` when B2B Edition isn't enabled for the store or the request has no signed-in customer.

Each definition implements the `B2BExtraFieldDefinition` interface. The concrete type tells you which kind of value the field holds and which input list to use when you write it:

| Definition type                        | Value type             | Type-specific fields        | Write with                    |
| -------------------------------------- | ---------------------- | --------------------------- | ----------------------------- |
| `B2BTextExtraFieldDefinition`          | Single-line text       | `maxLength`, `defaultText`  | `extraFields.texts`           |
| `B2BMultilineTextExtraFieldDefinition` | Multiline text         | `rows`, `defaultText`       | `extraFields.multilineTexts`  |
| `B2BNumberExtraFieldDefinition`        | Number                 | `maxValue`, `defaultNumber` | `extraFields.numbers`         |
| `B2BDropdownExtraFieldDefinition`      | One choice from a list | `options`, `defaultValue`   | `extraFields.multipleChoices` |

Use `fieldName` as the `name` when you read or write a value. `labelName` is the display label, and `visibleToEndUser` tells you whether the store owner wants shoppers to see the field at all.

#### Request

**`Example query: Get the user extra field definitions`**

```graphql title="Example query: Get the user extra field definitions" showLineNumbers={false}
query {
  site {
    settings {
      b2b {
        extraFields {
          user {
            fieldName
            labelName
            isRequired
            visibleToEndUser
            ... on B2BTextExtraFieldDefinition {
              maxLength
              defaultText
            }
            ... on B2BMultilineTextExtraFieldDefinition {
              rows
              defaultText
            }
            ... on B2BNumberExtraFieldDefinition {
              maxValue
              defaultNumber
            }
            ... on B2BDropdownExtraFieldDefinition {
              options
              defaultValue
            }
          }
        }
      }
    }
  }
}
```

#### Response

**`Example query response`**

```json title="Example query response" showLineNumbers={false}
{
  "data": {
    "site": {
      "settings": {
        "b2b": {
          "extraFields": {
            "user": [
              {
                "fieldName": "Cost Center",
                "labelName": "Cost center",
                "isRequired": true,
                "visibleToEndUser": true,
                "maxLength": 20,
                "defaultText": null
              },
              {
                "fieldName": "Seat Count",
                "labelName": "Seats",
                "isRequired": false,
                "visibleToEndUser": true,
                "maxValue": 500,
                "defaultNumber": 1
              },
              {
                "fieldName": "Region",
                "labelName": "Region",
                "isRequired": true,
                "visibleToEndUser": true,
                "options": ["North America", "EMEA", "APAC"],
                "defaultValue": "North America"
              }
            ]
          }
        }
      }
    }
  }
}
```

## List Company users

The `users` field on `customer.activeCompany` returns a paginated list of the users of the active Company the signed-in customer is currently representing. It supports [cursor-based pagination](/developer/docs/storefront/guides/graphql-storefront-api#pagination) with the standard `first`, `after`, `last`, and `before` arguments, and `collectionInfo.totalItems` reports the size of the full list.

Use `filters.companyRoleId` to return only the users assigned a given role. Role IDs come from the [`companyRoles`](#list-the-assignable-company-roles) query.

Each user's `extraFields` list holds the values of the Company user extra fields. Use inline fragments on the `ExtraFieldValue` implementations to read each value's typed field.

#### Request

**`Example query: List the first ten Admins of the active Company`**

```graphql title="Example query: List the first ten Admins of the active Company" showLineNumbers={false}
query {
  customer {
    activeCompany {
      users(first: 10, filters: { companyRoleId: 0 }) {
        collectionInfo {
          totalItems
        }
        pageInfo {
          hasNextPage
          endCursor
        }
        edges {
          node {
            entityId
            firstName
            lastName
            email
            phone
            companyRole
            companyRoleId
            extraFields {
              name
              fieldEntityId
              ... on TextExtraFieldValue {
                text
              }
              ... on MultilineTextExtraFieldValue {
                multilineText
              }
              ... on NumberExtraFieldValue {
                number
              }
              ... on MultipleChoiceExtraFieldValue {
                value
              }
            }
          }
        }
      }
    }
  }
}
```

#### Response

**`Example query response`**

```json title="Example query response" showLineNumbers={false}
{
  "data": {
    "customer": {
      "activeCompany": {
        "users": {
          "collectionInfo": {
            "totalItems": 2
          },
          "pageInfo": {
            "hasNextPage": false,
            "endCursor": "YXJyYXljb25uZWN0aW9uOjE="
          },
          "edges": [
            {
              "node": {
                "entityId": 48213,
                "firstName": "Marie",
                "lastName": "Curie",
                "email": "marie@greatbuysinc.com",
                "phone": "5121234567",
                "companyRole": "Admin",
                "companyRoleId": 0,
                "extraFields": [
                  { "name": "Cost Center", "fieldEntityId": 11, "text": "CC-4021" },
                  { "name": "Seat Count", "fieldEntityId": 12, "number": 12 },
                  { "name": "Region", "fieldEntityId": 13, "value": "North America" }
                ]
              }
            },
            {
              "node": {
                "entityId": 48377,
                "firstName": "Pierre",
                "lastName": "Curie",
                "email": "pierre@greatbuysinc.com",
                "phone": null,
                "companyRole": "Admin",
                "companyRoleId": 0,
                "extraFields": []
              }
            }
          ]
        }
      }
    }
  }
}
```

## List the assignable Company roles

The `companyRoles` field on `customer.activeCompany` returns the roles you can assign to a user of the active Company. It includes B2B Edition's predefined roles and any custom roles the store owner has created. The list is paginated, and `filters.search` narrows it to roles whose name matches a free-text term.

Use each role's `entityId` as the `companyRoleId` when you create or update a user. `roleType` is `1` for a predefined role and `2` for a custom role.

#### Request

**`Example query: List the Company roles`**

```graphql title="Example query: List the Company roles" showLineNumbers={false}
query {
  customer {
    activeCompany {
      companyRoles(first: 20) {
        collectionInfo {
          totalItems
        }
        edges {
          node {
            entityId
            name
            roleLevel
            roleType
          }
        }
      }
    }
  }
}
```

#### Response

**`Example query response`**

```json title="Example query response" showLineNumbers={false}
{
  "data": {
    "customer": {
      "activeCompany": {
        "companyRoles": {
          "collectionInfo": {
            "totalItems": 4
          },
          "edges": [
            { "node": { "entityId": 0, "name": "Admin", "roleLevel": 1, "roleType": 1 } },
            { "node": { "entityId": 1, "name": "Senior Buyer", "roleLevel": 1, "roleType": 1 } },
            { "node": { "entityId": 2, "name": "Junior Buyer", "roleLevel": 1, "roleType": 1 } },
            { "node": { "entityId": 1537, "name": "Procurement Lead", "roleLevel": 1, "roleType": 2 } }
          ]
        }
      }
    }
  }
}
```

## Create a Company user

The `createUser` mutation on `company` adds a user to the active Company. `email`, `firstName`, `lastName`, and `companyRoleId` are required. `phone` and `extraFields` are optional, but you must supply a value for every extra field the store has marked as required.

On success, `user` holds the new Company user and `errors` is empty.

#### Request

**`Example mutation: Create a Senior Buyer with extra fields`**

```graphql title="Example mutation: Create a Senior Buyer with extra fields" showLineNumbers={false}
mutation {
  company {
    createUser(
      input: {
        email: "irene@greatbuysinc.com"
        firstName: "Irène"
        lastName: "Joliot-Curie"
        phone: "5125550142"
        companyRoleId: 1
        extraFields: {
          texts: [{ name: "Cost Center", text: "CC-4021" }]
          numbers: [{ name: "Seat Count", number: 3 }]
          multipleChoices: [{ name: "Region", fieldValue: "EMEA" }]
        }
      }
    ) {
      user {
        entityId
        firstName
        lastName
        email
        companyRole
        companyRoleId
      }
      errors {
        ... on Error {
          message
        }
      }
    }
  }
}
```

#### Response

**`Example mutation response`**

```json title="Example mutation response" showLineNumbers={false}
{
  "data": {
    "company": {
      "createUser": {
        "user": {
          "entityId": 48902,
          "firstName": "Irène",
          "lastName": "Joliot-Curie",
          "email": "irene@greatbuysinc.com",
          "companyRole": "Senior Buyer",
          "companyRoleId": 1
        },
        "errors": []
      }
    }
  }
}
```

## Update a Company user

The `updateUser` mutation on `company` changes another user of the active Company. `entityId` identifies the user. Every other input field is optional, so send only the values you want to change. Pass `companyRoleId` to reassign the user's role.

On success, `entityId` echoes the updated user's ID and `errors` is empty.

#### Request

**`Example mutation: Promote a user to Admin and update their phone number`**

```graphql title="Example mutation: Promote a user to Admin and update their phone number" showLineNumbers={false}
mutation {
  company {
    updateUser(
      input: {
        entityId: 48902
        phone: "5125550199"
        companyRoleId: 0
        extraFields: {
          numbers: [{ name: "Seat Count", number: 5 }]
        }
      }
    ) {
      entityId
      errors {
        message
      }
    }
  }
}
```

#### Response

**`Example mutation response`**

```json title="Example mutation response" showLineNumbers={false}
{
  "data": {
    "company": {
      "updateUser": {
        "entityId": 48902,
        "errors": []
      }
    }
  }
}
```

> **Warning**
>
> `updateUser` can't change a user's email address. Email is the link between the Company user and its BigCommerce customer account, so it's managed through the customer account instead.

## Delete a Company user

The `deleteUser` mutation on `company` removes a user from the active Company. B2B Edition protects a Company from losing access to its own account: you can't delete yourself, the last user, or the last Admin.

On success, `entityId` echoes the deleted user's ID and `errors` is empty.

#### Request

**`Example mutation: Delete a Company user`**

```graphql title="Example mutation: Delete a Company user" showLineNumbers={false}
mutation {
  company {
    deleteUser(input: { entityId: 48902 }) {
      entityId
      errors {
        message
      }
    }
  }
}
```

#### Response

**`Example mutation response`**

```json title="Example mutation response" showLineNumbers={false}
{
  "data": {
    "company": {
      "deleteUser": {
        "entityId": 48902,
        "errors": []
      }
    }
  }
}
```

## Manage your own account

The operations above for managing *other* users require the permissions described in [Permissions](#permissions). Every Company user, whatever their role, can read and update their own Company-specific data:

* **`customer.activeCompany.currentUser`** returns the signed-in user's Company role name and extra field values.
* **`company.updateCurrentUser`** sets the signed-in user's extra field values. It takes the same `extraFields` input as `createUser` and `updateUser`.

A user's name, email, phone number, password, and customer form fields belong to the underlying BigCommerce customer account rather than to a Company. Manage them with the `customer` query and the `updateCustomer` and `changePassword` mutations described in [Customers](/developer/docs/storefront/guides/graphql-storefront-api/customers). For more on reading and updating your own information, see [User account settings](/developer/docs/storefront/guides/graphql-storefront-api/b-2-b/company-user-account).

#### Request

**`Example: Read and update your own Company user data`**

```graphql title="Example: Read and update your own Company user data" showLineNumbers={false}
query {
  customer {
    firstName
    lastName
    email
    activeCompany {
      currentUser {
        companyRole
        extraFields {
          name
          ... on TextExtraFieldValue {
            text
          }
          ... on NumberExtraFieldValue {
            number
          }
          ... on MultipleChoiceExtraFieldValue {
            value
          }
        }
      }
    }
  }
}

mutation {
  company {
    updateCurrentUser(
      input: {
        extraFields: {
          multipleChoices: [{ name: "Region", fieldValue: "APAC" }]
        }
      }
    ) {
      errors {
        message
      }
    }
  }
}
```

#### Response

**`Example responses`**

```json title="Example responses" showLineNumbers={false}
# Query

{
  "data": {
    "customer": {
      "firstName": "Marie",
      "lastName": "Curie",
      "email": "marie@greatbuysinc.com",
      "activeCompany": {
        "currentUser": {
          "companyRole": "Admin",
          "extraFields": [
            { "name": "Cost Center", "text": "CC-4021" },
            { "name": "Seat Count", "number": 12 },
            { "name": "Region", "value": "North America" }
          ]
        }
      }
    }
  }
}


# Mutation

{
  "data": {
    "company": {
      "updateCurrentUser": {
        "errors": []
      }
    }
  }
}
```

## Considerations

While using these operations, take note of the following information:

**Company scope is resolved from the session**

None of these operations accepts a Company ID. The API resolves the active Company from the signed-in customer, which prevents a caller from targeting another Company. A Super Admin manages a Company by masquerading as it first. A user of a parent Company within an [Account Hierarchy](https://support.bigcommerce.com/s/article/B2B-Edition-Account-Hierarchy) can only manage the users of their active Company. After switching to a subsidiary Company, that subsidiary is the active Company.

**Extra field values are keyed by name**

When you write extra fields, each value's `name` must match a definition's `fieldName` from `site.settings.b2b.extraFields.user`, and the value must go in the input list that matches the definition's type: `texts`, `multilineTexts`, `numbers`, or `multipleChoices`. Values you read back carry both `name` and the numeric `fieldEntityId` of the definition.

**Required extra fields**

Store owners can mark extra fields as required. `createUser` requires a value for every required field. `updateUser` and `updateCurrentUser` only validate the fields you send. To learn more, see the "Extra Fields Settings" section of [B2B Edition Settings](https://support.bigcommerce.com/s/article/B2B-Edition-Settings) in the Help Center.

**Company users and customer accounts**

Each Company user is backed by a BigCommerce customer account. `createUser` creates the customer account if the email is new, or links an existing customer who isn't yet a Company user. `deleteUser` removes the Company user and the customer account behind it. Email, password, and customer form fields live on the customer account; use the [Customers](/developer/docs/storefront/guides/graphql-storefront-api/customers) operations to manage them.

**Role IDs**

The predefined roles have fixed IDs: `0` is Admin, `1` is Senior Buyer, and `2` is Junior Buyer. Custom roles get their own IDs when the store owner creates them. Always read IDs from `companyRoles` rather than hard-coding them.

**Caching**

None of these fields is cached. Each request reflects the current state of the Company.

## Resources

### Documentation

* [GraphQL Storefront API Overview](/developer/docs/storefront/guides/graphql-storefront-api)
* [Customer context](/developer/docs/storefront/guides/graphql-storefront-api/customer-context)
* [Company Account Registration](/developer/docs/storefront/guides/graphql-storefront-api/b-2-b/company-account-registration)
* [Customers](/developer/docs/storefront/guides/graphql-storefront-api/customers)

### API Reference

* [Storefront GraphQL API reference](/developer/api-reference/graphql/storefront)
* [Create a storefront token](/developer/api-reference/rest/admin/authentication-apis/storefront-api-tokens/create-token)
* [Create a customer impersonation token](/developer/api-reference/rest/admin/authentication-apis/storefront-api-tokens/customer-impersonation-token/create-token-with-customer-impersonation)
* [Company Roles and Permissions](/developer/api-reference/rest/b2b/management/company/company-roles-and-permissions)
* [REST Management API: Users](/developer/api-reference/rest/b2b/management/users)

### Community

* [Developer community](https://support.bigcommerce.com/s/community)