GraphQL Storefront API: Company user management

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. 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 or the Create a customer impersonation token REST endpoint. On a Stencil storefront, you can also access a token directly from the page context.

Every operation on this page requires 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 and Dynamic tokens.

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.

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 and the “Company Roles” section of 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:

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.

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

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

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

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.

query {
  customer {
    activeCompany {
      companyRoles(first: 20) {
        collectionInfo {
          totalItems
        }
        edges {
          node {
            entityId
            name
            roleLevel
            roleType
          }
        }
      }
    }
  }
}

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.

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

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.

mutation {
  company {
    updateUser(
      input: {
        entityId: 48902
        phone: "5125550199"
        companyRoleId: 0
        extraFields: {
          numbers: [{ name: "Seat Count", number: 5 }]
        }
      }
    ) {
      entityId
      errors {
        message
      }
    }
  }
}

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.

mutation {
  company {
    deleteUser(input: { entityId: 48902 }) {
      entityId
      errors {
        message
      }
    }
  }
}

Manage your own account

The operations above for managing other users require the permissions described in 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. For more on reading and updating your own information, see User account settings.

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

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 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 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 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
• Customer context
• Company Account Registration
• Customers

API Reference

• Storefront GraphQL API reference
• Create a storefront token
• Create a customer impersonation token
• Company Roles and Permissions
• REST Management API: Users

Community

• Developer community