Skip to Content
B2b EditionB2B Edition APIsServer to Server Management APIsUserUsersUsers

Users

Get All B2B users

GET /users

Request

Returns a paginated list of B2B users with optional filters.

Authentication

  • X-Auth-Token in header

Parameters

  • X-Store-Hash in header - string
    required
    The unique store hash associated with a BigCommerce store that has B2B Edition enabled.
    Example: abc123
  • offset in query0 - integer
    The number of items to skip before starting to collect the result set.
  • limit in query with default of 10 - integer
    The maximum number of results to return.
  • companyId in query - integer
    If included, filters users in the response based on their Company ID as reported by the Server to Server Companies endpoints.
    Example: 42
  • roles in query - array

    Filters users according to their assigned role ID. This filter is limited to admin (0), senior buyer (1), and junior buyer (2).

    By default, custom roles are treated as junior buyer, but they can be differentiated in the response data by the companyRoleId and companyRoleName fields. For more information, see Company Roles and Permissions.

    Type: array[integer]

    Allowed: 0 | 1 | 2

  • minModified in query - string
    Filters results by the updatedAt field, returning only those with a Unix timestamp later than minModified.
    Example: 1751310365
  • maxModified in query - string
    Filters results by the updatedAt field, returning only those with a Unix timestamp earlier than maxModified.
    Example: 1751310365
  • minCreated in query - string
    Filters results by the createdAt field, returning only those with a Unix timestamp later than minCreated.
    Example: 1751310365
  • maxCreated in query - string
    Filters results by the createdAt field, returning only those with a Unix timestamp earlier than maxCreated.
    Example: 1751310365
  • email in query - string
    Filters users by email address. This field requires an exact match.
    Example: user@example.com
  • channelId in query - integer
    Filters users by their assigned BigCommerce channel ID.
    Example: 1
  • isIncludeExtraFields in query - string
    Indicates whether to include extra fields in the response. A value of 1 indicates they will be included, while a value of 0 indicates they will not.

    Allowed: 0 | 1

  • q in query - string
    Broader search term for filtering on supported fields. Currently this includes Company, email, and name fields.
    Example: Smith

example

Response

SUCCESS

Body

object | application/json

  • code    integer

    Operation status code.

    Default: 200

  • data    array[object]

  • meta    object

example

Create A Company User

POST /users

Request

Create a Company user within an existing Company.

With Independent Company behavior enabled, B2B Edition Company accounts are the source of truth for defining a Company user’s customer group assignment.

On stores without Independent Company behavior, each Company account has a one-to-one relationship with its customer group.

If no default customer group is configured, or the set value of customerGroupId is 0, the B2B Company will not be associated with any customer group. The Company users will have their corresponding customer records assigned to No Group in BigCommerce.

Authentication

  • X-Auth-Token in header

Parameters

  • X-Store-Hash in header - string
    required
    The unique store hash associated with a BigCommerce store that has B2B Edition enabled.
    Example: abc123

Body

object | application/json

  • firstName    string
    required

    User's first name.
    Example: Marie

  • lastName    string
    required

    User's last name.
    Example: Curie

  • phoneNumber    string

    User's phone number.
    Example: +1-555-123-4567

  • role    integer
    required

    Numeric code representing the user's role as admin (0), senior buyer (1), or junior buyer (2).

    Allowed: 0 | 1 | 2

    Example: 1

  • companyRoleId    integer

    Numeric code representing the user's Company-specific role. When present this field overrides the value of the role field.
    Example: 10

  • uuid    string

    External identifier for the user. This field may be used to represent any external user ID. Using the name uuid, B2B Edition does not require the field to be unique.
    Example: user-uuid-1

  • extraFields    array[object]

  • companyId    integer
    required

    The unique numeric ID associated with the user's B2B Edition Company account.
    Example: 42

  • acceptWelcomeEmail    boolean

    Indicates whether the user will receive a welcome email when the account is created.

  • originChannelId    integer

    The ID of the originating channel. A value of 0 will unset the user's origin channel, which may result in unexpected behavior. To avoid errors, ensure all necessary channels are included in channelIds.
    Example: 1

  • channelIds    array[integer]
    required

    List of numeric channel IDs the user is associated with. These represent the storefront channels the user can log in to and do business.

example

Response

SUCCESS

Body

object | application/json

  • code    integer

    Operation status code.

    Default: 200

  • data    object

  • meta    object

example

Bulk Create Users

POST /users/bulk

Request

Create up to 10 Company users at once.

With (Independent Company behavior)[/b2b-edition/apis/rest-management/company/companies#independent-vs-dependent-companies-behavior] enabled, B2B Edition Company accounts are the source of truth for defining a Company user’s customer group assignment. If no default customer group is configured or the set value of customerGroupId is 0, the B2B Company will not be associated with any customer group. The Company users will have their corresponding customer records assigned to No Group in BigCommerce.

Authentication

  • X-Auth-Token in header

Parameters

  • X-Store-Hash in header - string
    required
    The unique store hash associated with a BigCommerce store that has B2B Edition enabled.
    Example: abc123

Body

array | application/json

  • firstName    string
    required

    User's first name.
    Example: Marie

  • lastName    string
    required

    User's last name.
    Example: Curie

  • phoneNumber    string

    User's phone number.
    Example: +1-555-123-4567

  • role    integer
    required

    Numeric code representing the user's role as admin (0), senior buyer (1), or junior buyer (2).

    Allowed: 0 | 1 | 2

    Example: 1

  • companyRoleId    integer

    Numeric code representing the user's Company-specific role. When present this field overrides the value of the role field.
    Example: 10

  • uuid    string

    External identifier for the user. This field may be used to represent any external user ID. Using the name uuid, B2B Edition does not require the field to be unique.
    Example: user-uuid-1

  • extraFields    array[object]

  • companyId    integer
    required

    The unique numeric ID associated with the user's B2B Edition Company account.
    Example: 42

  • acceptWelcomeEmail    boolean

    Indicates whether the user will receive a welcome email when the account is created.

  • originChannelId    integer

    The ID of the originating channel. A value of 0 will unset the user's origin channel, which may result in unexpected behavior. To avoid errors, ensure all necessary channels are included in channelIds.
    Example: 1

  • channelIds    array[integer]
    required

    List of numeric channel IDs the user is associated with. These represent the storefront channels the user can log in to and do business.

example

Response

Creation successful

Body

object | application/json

  • code    integer

    Operation status code.

    Default: 200

  • data    array[object]

  • meta    object

example

Get User Details

GET /users/{userId}

Request

Returns detailed user information for the user specified by userId. Unlike Get All Users, this endpoint includes extra fields by default.

Authentication

  • X-Auth-Token in header

Parameters

  • X-Store-Hash in header - string
    required
    The unique store hash associated with a BigCommerce store that has B2B Edition enabled.
    Example: abc123
  • userId in path - integer
    required
    The unique identifier of the user as reported by Get All Users.
    Example: 123

example

Response

Success

Body

object | application/json

  • code    integer

    Operation status code.

    Default: 200

  • data    object

  • meta    object

example

Update User Details

PUT /users/{userId}

Request

Updates the B2B Edition user account associated with userId. All fields may be updated except companyId and originChannelId, which are read-only for a user account.

Authentication

  • X-Auth-Token in header

Parameters

  • X-Store-Hash in header - string
    required
    The unique store hash associated with a BigCommerce store that has B2B Edition enabled.
    Example: abc123
  • userId in path - integer
    required
    The unique identifier of the user as reported by Get All Users.
    Example: 123

Body

object | application/json

  • firstName    string

    User's first name.
    Example: Marie

  • lastName    string

    User's last name.
    Example: Curie

  • phoneNumber    string

    User's phone number.
    Example: +1-555-123-4567

  • role    integer

    Numeric code representing the user's role as admin (0), senior buyer (1), or junior buyer (2).

    Allowed: 0 | 1 | 2

    Example: 1

  • companyRoleId    integer

    Numeric code representing the user's Company-specific role. When present this field overrides the value of the role field.
    Example: 10

  • uuid    string

    External identifier for the user. This field may be used to represent any external user ID. Using the name uuid, B2B Edition does not require the field to be unique.
    Example: user-uuid-1

  • extraFields    array[object]

  • channelIds    array[integer]

    List of numeric channel IDs the user is associated with. These represent the storefront channels the user can log in to and do business.

example

Response

Success

Body

object | application/json

  • code    integer

    Operation status code.

    Default: 200

  • data    object

  • meta    object

example

Delete a User

DELETE /users/{userId}

Request

Deletes a B2B Edition user account. This endpoint does not delete the BigCommerce customer account. Attempting to delete the last user in a Company will fail, but deleting all admin users will not.

NOTE:
Deleting the only admin user in a Company may result in the Company being unable to do business on your storefront. When using this endpoint, care must be taken to avoid deleting the last admin user.

Authentication

  • X-Auth-Token in header

Parameters

  • X-Store-Hash in header - string
    required
    The unique store hash associated with a BigCommerce store that has B2B Edition enabled.
    Example: abc123
  • userId in path - integer
    required
    The unique identifier of the user as reported by Get All Users.
    Example: 123

example

Response

SUCCESS

Body

object | application/json

  • code    integer

    Operation status code.

    Default: 200

  • data    object

  • meta    object

example

Get User Details by BigCommerce Customer ID

GET /users/customer/{customerId}

Request

Returns detailed information for the user associated with customerId. Analogous to Get User Details. If the B2B Edition customer account associated with customerId has been deleted, this will return a 404 error.

Authentication

  • X-Auth-Token in header

Parameters

  • X-Store-Hash in header - string
    required
    The unique store hash associated with a BigCommerce store that has B2B Edition enabled.
    Example: abc123
  • customerId in path - integer
    required
    The unique numeric ID associated with the BigCommerce customer account. This does not match the userId assigned by B2B Edition.
    Example: 12345

example

Response

Success

Body

object | application/json

  • code    integer

    Operation status code.

    Default: 200

  • data    object

  • meta    object

example

List extra fields for users

GET /users/extra-fields

Request

Returns paginated list of extra field definitions for users.

Authentication

  • X-Auth-Token in header

Parameters

  • X-Store-Hash in header - string
    required
    The unique store hash associated with a BigCommerce store that has B2B Edition enabled.
    Example: abc123
  • offset in query0 - integer
    The number of items to skip before starting to collect the result set.
  • limit in query with default of 10 - integer
    The maximum number of results to return.

example

Response

Success

Body

object | application/json

  • code    integer

    Example: 200

  • data    array[object]

  • meta    object

example

Did you find what you were looking for?
User