Users

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.

Example Query and Response:

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

• 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:

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 CheckUserEmail(
    $email: String!
) {
    userEmailCheck(
        email: $email
    ) {
        userType
    }
}

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.

Example Mutation:

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.

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.

Example Query and Response:

query GetUserRoles(
    $companyId: Int!
) {
    companyRoles(
        companyId: $companyId
    ) {
        edges {
            node {
                id
                name
            }
        }
    }
}

The typical pagination arguments are supported.

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

Example Request:

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

Example Mutation with Variables:

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

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.

Example Update Request:

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 DeleteUser(
    $companyId: Int!,
    $userId: Int!
) {
    userDelete(
        companyId: $companyId,
        userId: $userId
    ) {
        message
    }
}