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

# Users

Plan: B2B Developer

Lesson 6 of 18 · 30 min

## Introduction

All companies start with a single user with the "Admin" role. This user can then create and manage other users with varying roles. The storefront actions available to a user depend on their role.

All company users are associated with a BigCommerce customer account. Unlike with the initial admin user, new company users can be created whether a customer account already exists or not.

## Fetching a Company's Users

The `users` query can be used to fetch the details of all users assigned to the current user's company.

> **Info**
>
> The `users` and `user` queries are available only when the user associated with the Bearer token has the Senior Buyer role or higher, or a custom role with the "User management - View" permission.

### Example Query and Response:

#### Query

```graphql showLineNumbers={false}
query GetUsers(
    $companyId: Int!
) {
    users(
        companyId: $companyId
    ) {
        pageInfo {
            hasNextPage
            hasPreviousPage
            startCursor
            endCursor
        }
        totalCount
        edges {
            node {
                id
                bcId
                firstName
                lastName
                email
                phone
                role
                companyRoleId
                companyRoleName
            }
        }
    }
}
```

#### Response

```json showLineNumbers={false}
{
    "data": {
        "users": {
            "pageInfo": {
                "hasNextPage": true,
                "hasPreviousPage": false,
                "startCursor": "YXJy...",
                "endCursor": "YXJy..."
            },
            "totalCount": 11,
            "edges": [
                {
                    "node": {
                        "id": "99988877",
                        "bcId": 27,
                        "firstName": "John",
                        "lastName": "Doe",
                        "email": "johndoe@example.com",
                        "phone": "111-222-3333",
                        "role": 2,
                        "companyRoleId": 11223,
                        "companyRoleName": "Junior Buyer"
                    }
                },
                ...
            ]
        }
    }
}
```

* The `companyId` argument is required and must match the ID of the company associated with the Bearer token.
* Standard pagination arguments are also available.
* The fetched users can also be filtered with `firstName` and `lastName` arguments, as well as by specific roles using the `role` or `companyRoleId` arguments.
* See Creating New Users below for the distinction between `role` and `companyRoleId`.

The `user` query, which also requires the `userId` argument, returns the same GraphQL type as each node in `users`, so the same fields can be queried.

### Example Request:

```graphql showLineNumbers={false}
query GetUser(
    $companyId: Int!,
    $userId: Int!
) {
    user(
        companyId: $companyId,
        userId: $userId
    ) {
        id
        bcId
        firstName
        lastName
        email
        phone
        role
        companyRoleId
        companyRoleName
    }
}
```

## Creating New Users

### Checking the Email Address

Before attempting to create a new user, it's useful to check for the status of the user's email address using the `userEmailCheck` query.

While a new company user can be created whether a customer account associated with the email exists or not, an existing customer cannot already be associated with a company, either as a standard user or a Super Admin. The `userEmailCheck` query will report the necessary information about whether an account exists and what its status is.

#### Example Query and Response:

#### Query

```graphql showLineNumbers={false}
query CheckUserEmail(
    $email: String!
) {
    userEmailCheck(
        email: $email
    ) {
        userType
    }
}
```

#### Response

```json showLineNumbers={false}
{
    "data": {
        "userEmailCheck": {
            "userType": 2
        }
    }
}
```

The `userType` field will have a value of:

* `1` - If no associated customer account exists
* `2` - If a customer account exists and is not associated with any company

If the `userType` has any other value, creating a user with the email address in question will fail.

### Creating the User

Once an email address has been verified as a valid for user creation, use the `userCreate` mutation to do so.

> **Info**
>
> The `userCreate` mutation is available only when the user associated with the Bearer token has the Admin role or a custom role with the "User management - Create, edit, delete" permission.

#### Example Mutation:

```graphql showLineNumbers={false}
mutation CreateUser(
    $companyId: Int!,
    $email: String!,
    $firstName: String!,
    $lastName: String!,
    $role: Int
) {
    userCreate(
        userData: {
            companyId: $companyId,
            email: $email,
            firstName: $firstName,
            lastName: $lastName,
            role: $role
        }
    ) {
        user {
            id
            firstName
            lastName
            email
            role
            companyRoleId
            companyRoleName
        }
    }
}
```

The value passed for the `role` argument is an integer value corresponding with one of the three built-in user roles:

* **Admin (value 0):** Admins have all storefront permissions, including management of company addresses and users as well as invoice payment.
* **Senior Buyer (value 1):** Senior Buyers can view/query company users and addresses, can create and manage shopping lists and quotes, and have permission to place orders and view invoices.
* **Junior Buyer (value 2):** Junior Buyers can view/query company addresses and have permission to create shopping lists and quotes, but they cannot place orders.

Once a user is created and has set a password if necessary (see below), a token fetched for that user with the `login` mutation will reflect the permissions assigned to their role.

Other important notes about `userCreate`:

* If no customer account exists for the email address, one will be automatically created.
* If a customer account already exists and the values for `firstName` and `lastName` differ from the values on that account, the customer name will be updated with the new values.

### Customer Welcome and Password Reset

Once a new B2B user is created, the corresponding email address will receive a welcome email.

Observe in the `userCreate` mutation example that no field exists for setting the password of the new user. If a customer account already exists for the user, the customer should already have a password set, and no further action is required.

If a new customer account was created, the customer will need to use the "password reset" functionality on the storefront to initially set their password. The standard welcome email includes a link to the password reset page.

> **Info**
>
> Note that password reset is accomplished with the standard BigCommerce APIs and does not utilize the B2B GraphQL API.

## Custom User Roles

The user creation example above makes use of the built-in user roles, via the `role` field. However, store owners also have the capability to create custom roles, assigning specific permissions to these roles according to the common use cases of their customers. (See *Settings > Company users and roles* in the B2B control panel.)

While the `role` field utilizes static integer values, the `companyRoleId` field supports all possible roles, expecting an ID value corresponding to a role.

The built-in Admin, Senior Buyer, and Junior Buyer roles also have IDs compatible with `companyRoleId` as well, so it's possible to use this field instead of `role` to manage built-in roles.

### Fetching Roles

Use the `companyRoles` query to fetch the details of available user roles.

> **Info**
>
> The `companyRoles` query simply requires a valid Bearer token.

#### Example Query and Response:

#### Query

```graphql showLineNumbers={false}
query GetUserRoles(
    $companyId: Int!
) {
    companyRoles(
        companyId: $companyId
    ) {
        edges {
            node {
                id
                name
            }
        }
    }
}
```

#### Response

```json showLineNumbers={false}
{
    "data": {
        "companyRoles": {
            "edges": [
                {
                    "node": {
                        "id": "10009",
                        "name": "Admin"
                    }
                },
                {
                    "node": {
                        "id": "10010",
                        "name": "Senior Buyer"
                    }
                },
                {
                    "node": {
                        "id": "10011",
                        "name": "Junior Buyer"
                    }
                },
                {
                    "node": {
                        "id": "11223",
                        "name": "Custom Shopper Role"
                    }
                }
            ]
        }
    }
}
```

> **Info**
>
> While the `companyId` argument is required (and must match the Bearer token), roles are currently managed at the store admin level, and the query results will be identical no matter what `companyId` is used.

The typical pagination arguments are supported.

The `search` argument can also be used to query for a specific role by name.

#### Example Request:

```graphql showLineNumbers={false}
query GetUserRoles(
    $companyId: Int!
) {
    companyRoles(
        companyId: $companyId,
        search: "Junior Buyer"
    ) {
        edges {
            node {
                id
                name
            }
        }
    }
}
```

### Creating a User with Company Role ID

Once you've fetched role details and obtained the ID of the role you wish to assign to a customer, you can use the `companyRoleId` argument, rather than `role`, with the `userCreate`mutation.

#### Example Mutation with Variables:

#### Mutation

```graphql showLineNumbers={false}
mutation CreateUser(
    $companyId: Int!,
    $email: String!,
    $firstName: String!,
    $lastName: String!,
    $companyRoleId: Int
) {
    userCreate(
        userData: {
            companyId: $companyId,
            email: $email,
            firstName: $firstName,
            lastName: $lastName,
            companyRoleId: $companyRoleId
        }
    ) {
        user {
            ...
        }
    }
}
```

#### Variables

```json showLineNumbers={false}
{
    "companyId": 1112233,
    "email": "johndoe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "companyRoleId": 10011
}
```

Note that if `companyRoleId` is set to the value of a custom role, the `role` field will automatically be set to 2. While this is normally the value associated with Junior Buyer, the user's permissions will reflect the assigned custom role, not the Junior Buyer role.

## Updating and Deleting Users

The `userUpdate` and `userDelete` mutations are also available for user management.

> **Info**
>
> The `userUpdate` and `userDelete` mutations are available only when the user associated with the Bearer token has the Admin role or a custom role with the "User management - Create, edit, delete" permission.

### Example Update Request:

```graphql showLineNumbers={false}
mutation UpdateUser(
    $companyId: Int!,
    $userId: Int!,
    $firstName: String,
    $lastName: String,
    $phone: String,
    $companyRoleId: Int
) {
    userUpdate(
        userData: {
            companyId: $companyId,
            userId: $userId,
            firstName: $firstName,
            lastName: $lastName,
            phone: $phone,
            companyRoleId: $companyRoleId
        }
    ) {
        user {
            id
            firstName
            lastName
            email
            role
            companyRoleId
            companyRoleName
        }
    }
}
```

* The `companyId` and `userId` fields are required in order to identify the user and cannot be changed to new values.
* The `role` field can be passed instead of the `companyRoleId` field.

### Example Delete Mutation and Response:

#### Mutation

```graphql showLineNumbers={false}
mutation DeleteUser(
    $companyId: Int!,
    $userId: Int!
) {
    userDelete(
        companyId: $companyId,
        userId: $userId
    ) {
        message
    }
}
```

#### Response

```json showLineNumbers={false}
{
    "data": {
        "userDelete": {
            "message": "Success"
        }
    }
}
```