GraphQL Storefront API: Company user account settings

BigCommerce’s GraphQL Storefront API lets a signed-in user read the Company they are currently representing and, for Company users, maintain their own Company user record. Use it to show the active Company, the Company role a user holds, and the values of the Company user extra fields the store has configured, and to let Company users update their own extra field values from an account settings page.

The active Company is the Company the signed-in user is currently representing, and customer.activeCompany returns its information. How a user gets an active Company depends on the type of user:

• Company users belong to a Company, which is their active Company by default. A Company user in a parent Company within an Account Hierarchy can switch to a subsidiary Company if their role’s permissions allow it, and the subsidiary then becomes the active Company.
• Super Admins don’t belong to a Company. They are assigned to one or more Companies and have no active Company until they masquerade as one of them, which then becomes the active Company.

Switching or masquerading only changes which Company the user is representing. It doesn’t change who the signed-in user is.

These operations are self-service. Each one reads or writes only the signed-in user’s own information, and every Company user can call them regardless of their Company role. The API resolves the active Company and the signed-in user from the session, so none of them accepts a Company ID or a user ID, and a caller can’t use them to view or change another user. Managing the other users of a Company (listing, creating, updating, and deleting them) is a separate, role-restricted set of operations under customer.activeCompany.users and company.createUser, company.updateUser, and company.deleteUser, and isn’t covered on this page.

A Company user’s name, email, phone number, and password belong to the underlying BigCommerce customer account rather than to the Company user record. Read them from the customer node and change them with the updateCustomer and changePassword mutations described in Customers. The default Buyer Portal combines both sets of operations to power its Account settings 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.

Read the current Company and user

Query customer.activeCompany to read the signed-in user’s Company context:

• companyName is the name of the active Company, which is the Company the signed-in user is currently representing.
• currentUser.companyRole is the name of the signed-in user’s Company role, such as Admin, Senior Buyer, Junior Buyer, or the name of a custom role. For a masquerading Super Admin it’s an empty string, because Super Admins don’t hold a Company role.
• currentUser.extraFields lists the values of the Company user extra fields the store has configured.

Each extra field value implements the ExtraFieldValue interface, which carries the field’s name and the numeric fieldEntityId of its definition. Use inline fragments on the concrete types to read each value:

Name, email, and phone number belong to the underlying BigCommerce customer account rather than to the Company user, so read them from the customer node directly.

query {
  customer {
    firstName
    lastName
    email
    phone
    activeCompany {
      companyName
      currentUser {
        companyRole
        extraFields {
          name
          fieldEntityId
          ... on TextExtraFieldValue {
            text
          }
          ... on MultilineTextExtraFieldValue {
            multilineText
          }
          ... on NumberExtraFieldValue {
            number
          }
          ... on MultipleChoiceExtraFieldValue {
            value
          }
        }
      }
    }
  }
}

Update your own extra fields

The updateCurrentUser mutation on company sets the signed-in user’s Company user extra field values. Its extraFields input has one list per extra field type. Put each value in the list that matches the field’s type, and identify the field by its name:

Only the fields you send are changed. The mutation returns an errors list, which is empty on success. Each error carries the input field it relates to, a human-readable message, and an optional code.

Name, email, phone number, password, and customer form fields belong to the customer account. Manage them with the updateCustomer and changePassword mutations described in Customers.

mutation {
  company {
    updateCurrentUser(
      input: {
        extraFields: {
          texts: [{ name: "Cost Center", text: "CC-4022" }]
          numbers: [{ name: "Seat Count", number: 15 }]
          multipleChoices: [{ name: "Region", fieldValue: "APAC" }]
        }
      }
    ) {
      errors {
        field
        message
        code
      }
    }
  }
}

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 or a user ID. The API resolves the active Company and the Company user from the signed-in customer, so a caller can read and update only their own record and cannot target another user or another Company. A Super Admin who is masquerading as a Company has the same permissions as the predefined Admin role in that Company. companyName returns the masqueraded Company, and currentUser is returned with an empty companyRole and no extraFields, because a Super Admin holds no Company role or Company user extra fields. The Buyer Portal’s Account settings page leaves the Role field blank in that case. A Super Admin who isn’t masquerading has no active Company, so companyName and currentUser both return null.

When the fields return null

customer.activeCompany returns null when the request has no customer context. companyName and currentUser return null when the signed-in customer is neither a Company user nor a Super Admin, when B2B Edition isn’t enabled for the store, or when there is no active Company, such as when a Super Admin isn’t masquerading.

Extra field values are keyed by name

When you write extra fields, each value’s name must match the field name configured in the B2B Edition control panel, and the value must go in the input list that matches the field’s type. Values you read back carry both name and the numeric fieldEntityId of the definition. To learn more about configuring extra fields, see the “Extra Fields Settings” section of B2B Edition Settings in the Help Center.

Required extra fields

Store owners can mark extra fields as required. updateCurrentUser only validates the fields you send, so a signed-in user can update one field without resending the others.

Caching

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

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