Server to Server Management APIs
Company

Company

A company in B2B Edition corresponds one-to-one with a customer group in BigCommerce. You can do the mapping through the bc_group_id field. Once established, you cannot change this corresponding relationship. You can only delete it. Note that you cannot merge BigCommerce customer groups or B2B Edition companies.

This diagram details the relation between customer groups and companies:

Company entity diagram

The best practice for using these Company APIs is to maintain unidirectional data flow, with B2B Edition endpoints as the primary touchpoint. By default B2B Edition's company operations handle modifying linked BigCommerce customer group data (add, update, and delete).

Get All Companies

GET /companies

Request

Get a list of all companies.

Authentication

  • authToken in header

Parameters

  • limit in query with default of 10 - integer
    Pagination limit
  • offset in query0 - integer
    Pagination offset
  • minModified in query - number
    Minimum modified timestamp
  • maxModified in query - number
    Maximum modified timestamp
  • minCreated in query - number
    Minimum created timestamp
  • maxCreated in query - number
    Maximum created timestamp
  • sortBy in query with default of updatedAt - string
    Sort the result by a specific company field.
    Example: updatedAt

    Allowed: companyName | updatedAt

  • orderBy in query with default of DESC - string
    Allow: 'DESC', 'ASC'
    Example: DESC

    Allowed: ASC | DESC

  • isIncludeExtraFields in query with default of 0 - string
    Whether the response will include extra fields.

    Allowed: 0 | 1

  • companyStatus in query - integer
    0: PENDING 1: APPROVED 2: REJECTED 3: INACTIVE

    Allowed: 0 | 1 | 2 | 3

  • q in query - string
    Company query string
  • extraFields in query - array
    Filter by extra fields.
    Type: array[string]
  • bcOrderId in query - integer
    A company purchases a BigCommerce order ID, which allows you to find the company by BigCommerce order ID.
    Example: 2
  • orderId in query - string
    Company purchase order ID
  • bcGroupId in query - string
    BigCommerce customer group ID
  • customerId in query - integer
    BigCommerce customer ID. This customer should be a B2B company user.
  • extraFieldFilterType in query with default of search - string
    Extra field filter type. The search filter type allows for partial matches, while the exact-match filter type only returns results that exactly match the specified criteria.

    Allowed: search | exact-match

example

curl --request GET \
--url https://api-b2b.bigcommerce.com/api/v3/io/companies \
--header 'Content-Type: application/json' \
--header 'authToken: {{token}}'

Response

OK

Body

object | application/json
  • code
    number
    required

  • data
    array[object]
    required

  • meta
    object
    required

    Used to response pagination information
    Example: {"pagination":{"limit":10,"offset":0,"totalCount":1}}

include extra fields

{
"code": 200,
"data": [
{
"companyId": "147340",
"companyName": "Glam Squad Hair and Makeup Artistry",
"bcGroupName": "Glam Squad Hair and Makeup Artistry",
"companyEmail": "support@bundleb2b.net",
"companyPhone": "123456789",
"companyStatus": "1",
"uuid": "",
"catalogId": "",
"catalogName": "",
"updatedAt": "1618794615",
"createdAt": "1618787774",
"extraFields": [
{
"dataType": "2",
"fieldType": 2,
"fieldName": "extraStr1",
"fieldValue": "extra_text",
"isRequired": "0",
"labelName": "Enter your license"

standard response

{
"code": 200,
"data": [
{
"companyId": "147340",
"companyName": "Glam Squad Hair and Makeup Artistry",
"bcGroupName": "Glam Squad Hair and Makeup Artistry",
"companyEmail": "support@bundleb2b.net",
"companyPhone": "123456789",
"companyStatus": "1",
"uuid": "",
"catalogId": "",
"catalogName": "",
"updatedAt": "1618794615",
"createdAt": "1618787774",
"bcGroupId": 0
}
],
"meta": {
"message": "SUCCESS",
"pagination": {
"limit": 10,
"offset": 1,
"totalCount": 989
}
}
}

Create a Company

POST /companies

Request

Create a company.

  • When the independent company behavior is enabled, the system will not automatically create a dedicated customer group for each new Company account. Instead, you can assign a customer group to a Company account as needed using the customerGroupId field. If the customerGroupId field is not provided, the B2B company will be associated with your configured default customer group. If you have not configured a default customer group or set the value of customerGroupId to 0, the B2B company will not be associated with any customer group, and the company users within the company will have their corresponding customer record assigned to "No Group" in BigCommerce.

  • When the independent company behavior is turned off, a new customer group will be automatically created and associated with each new Company account. In this case, you will not use the customerGroupId field.

Authentication

  • authToken in header

Body

object | application/json
Extra Field Values
  • extraFields
    array[object]

  • userExtraFields
    array[object]

  • companyName
    string
    required

    The company name, if you want to specify it.
    >= 1 characters
  • companyPhone
    string
    required

  • companyEmail
    string
    required

    >= 1 characters
  • addressLine1
    string

  • addressLine2
    string

  • city
    string

    >= 1 characters
  • state
    string

    >= 1 characters
  • country
    string
    required

    Country full name or ISO2 country code. For Example:

    A Country full name: Afghanistan

    ISO2 Country code: AF

    >= 1 characters
  • zipCode
    string

  • adminFirstName
    string
    required

    The company first admin user first name
    >= 1 characters
  • adminLastName
    string
    required

    The company first admin user's last name
    >= 1 characters
  • adminEmail
    string
    required

    The company first admin user email
    >= 1 characters
  • adminPhoneNumber
    string

    The company first admin user phone number
    >= 1 characters
  • catalogId
    integer

    BigCommerce price list ID that company related
    >= 1 characters
  • acceptCreationEmail
    boolean

    True: Sends an email notification about the company creation to the admin user; False: Does not send the notification.

    Default: false

  • channelIds
    array[integer]

    BigCommerce channel ID list
  • originChannelId
    integer

    BigCommerce channel ID, used for BigCommerce customer origin channel ID. This field takes effect only when you do not configure the store default B2B channel.
  • customerGroupId
    integer

    BigCommerce Customer Group ID. Used to associate a BigCommerce Customer Group to a B2B company when the independent company behavior is enabled.

example-1

{
"companyName": "string",
"companyPhone": "string",
"companyEmail": "user@example.com",
"addressLine1": "string",
"addressLine2": "string",
"city": "string",
"state": "string",
"country": "string",
"zipCode": "string",
"adminFirstName": "string",
"adminLastName": "string",
"adminEmail": "user@example.com",
"adminPhoneNumber": "string",
"catalogId": 0,
"acceptCreationEmail": false,
"extraFields": [
{
"fieldName": "string",
"fieldValue": "string"
}
],
"uuid": "string",
"channelIds": [
1,
2
],
"originChannelId": 1
}

Response

Created

Body

object | application/json
  • code
    integer
    required

  • data
    object
    required

  • meta
    object
    required

example-1

{
"code": 200,
"data": {
"companyId": 1,
"customerId": 1,
"customerGroupId": 1
},
"meta": {
"message": "SUCCESS"
}
}

Get a Company Detail

GET /companies/{companyId}

Request

Get details about a specific company.

Authentication

  • authToken in header

Parameters

  • companyId in path - string
    required

example

curl --request GET \
--url 'https://api-b2b.bigcommerce.com/api/v3/io/companies/[companyId]' \
--header 'Content-Type: application/json' \
--header 'authToken: {{token}}'

Response

OK

Body

object | application/json
  • code
    number
    required

  • data
    object
    required

  • meta
    object
    required

example-1

{
"code": 200,
"data": {
"companyId": "147340",
"companyName": "Glam Squad Hair and Makeup Artistry",
"companyEmail": "support@bundleb2b.net",
"companyPhone": "123456789",
"companyStatus": "1",
"uuid": "",
"catalogId": "",
"catalogName": "",
"updatedAt": "1618794615",
"createdAt": "1618787774",
"extraFields": [
{
"dataType": "2",
"fieldName": "extraStr1",
"fieldValue": "extra_text",
"isRequired": "0",
"labelName": "Enter your license"
}
],
"bcGroupId": "1",
"bcGroupName": "salons"
},
"meta": {
"message": "SUCCESS"
}

Update a Company

PUT /companies/{companyId}

Request

Update a company's attributes.

  • When you enable independent company behavior, you can assign a customer group to a Company using the customerGroupId field. Once assigned, the customer group will be associated with all users within that Company. If customerGroupId is set to 0, the customer group association will be removed from the Company, and all users within the Company will no longer have a group assigned. The priceListAssign field will not take effect; please configure the price list for the customer group directly in the BigCommerce control panel.

  • When you turn off independent company behavior, the customerGroupId field will not take effect. You cannot change the association between B2B companies and BigCommerce customer groups. You will use the priceListAssign field to configure the price list assigned to the Company.

Authentication

  • authToken in header

Parameters

  • companyId in path - string
    required

Body

object | application/json
  • companyName
    string

    >= 1 characters
  • companyPhone
    string

  • companyEmail
    string

    >= 1 characters
  • addressLine1
    string

  • addressLine2
    string

  • city
    string

    >= 1 characters
  • state
    string

    >= 1 characters
  • country
    string

    Country full name or ISO2 country code. For Example:

    A Country full name: Afghanistan

    ISO2 Country code: AF

    >= 1 characters
  • zipCode
    string

  • extraFields
    array[object]

    To use customized extra fields with field names you need to first add company extra fields in Settings > Extra fields inside B2B edition.

    e.g., If you want to create a new company with an extra integer field named licenseNO, you can use this structure [{'fieldName': 'LicenseNO', 'fieldValue': 10342340323}] in the request body.

  • uuid
    string

    Company UUID indicates external ID
  • priceListAssign
    array[object]

    This field is only enable for MSF store
  • customerGroupId
    integer

    BigCommerce Customer Group ID. Used to associate a BigCommerce Customer Group to a B2B company when the independent company behavior is enabled.

example

{
"companyName": "string",
"companyPhone": "string",
"companyEmail": "string",
"addressLine1": "string",
"addressLine2": "string",
"city": "string",
"state": "string",
"country": "string",
"zipCode": "string",
"extraFields": [
{
"fieldName": "string",
"fieldValue": "string"
}
],
"uuid": "string",
"priceListAssign": [
{
"channelId": 0,
"priceListId": 0
}
],
"customerGroupId": 0
}

Response

OK

Body

object | application/json
  • code
    number
    required

  • meta
    object
    required

  • data
    object
    required

    Return company ID.

example-1

{
"code": 200,
"data": {
"companyId": 12
},
"meta": {
"message": "SUCCESS"
}
}

Delete a Company

DELETE /companies/{companyId}

Request

Delete A Company.

  • When you turn off independent company behavior. Deleting a company will also delete the corresponding BigCommerce Customer Group.

  • When you enable independent company behavior. Deleting a company will not affect the customer group associated with the company.

Authentication

  • authToken in header

Parameters

  • companyId in path - string
    required

example

curl --request DELETE \
--url 'https://api-b2b.bigcommerce.com/api/v3/io/companies/[companyId]' \
--header 'Content-Type: application/json' \
--header 'authToken: {{token}}'

Response

OK

Body

object | application/json
  • code
    integer

  • data
    object

  • meta
    object

example-1

{
"code": 200,
"data": {},
"meta": {
"message": "SUCCESS"
}
}

Convert from BigCommerce CustomerGroup into Company

POST /customer-groups/{customerGroupId}/companies

Request

Create company from a BigCommerce customer group.

  • This API is turned off for the MSF store.
  • This API is turned off when the independent company feature is enabled.

Authentication

  • authToken in header

Parameters

  • customerGroupId in path - string
    required

Body

object | application/json
Extra Field Values
  • companyName
    string
    required

    Company name
    >= 1 characters
  • companyPhone
    string
    required

    Company phone number
    >= 1 characters
  • companyEmail
    string
    required

    Company email
    >= 1 characters
  • addressLine1
    string

    >= 1 characters
  • addressLine2
    string

    >= 1 characters
  • city
    string

    >= 1 characters
  • state
    string

    >= 1 characters
  • country
    string
    required

    >= 1 characters
  • zipCode
    string

    >= 1 characters
  • adminFirstName
    string

    >= 1 characters
  • adminLastName
    string

    >= 1 characters
  • adminEmail
    string
    required

    >= 1 characters
  • adminPhoneNumber
    string
    required

    >= 1 characters
  • catalogId
    integer

    The company catalog ID
  • acceptCreationEmail
    boolean

    If the company creation can accept email

    Default: false

  • extraFields
    array[object]

  • userExtraFields
    array[object]

example-1

{
"companyName": "string",
"companyPhone": "string",
"companyEmail": "string",
"addressLine1": "string",
"addressLine2": "string",
"city": "string",
"state": "string",
"country": "string",
"zipCode": "string",
"adminFirstName": "string",
"adminLastName": "string",
"adminEmail": "string",
"adminPhoneNumber": "string",
"catalogId": 0,
"acceptCreationEmail": false,
"description": "String",
"extraFields": [
{
"fieldName": "string",
"fieldValue": "string"
}
]
}

Response

OK

Body

object | application/json
  • code
    integer
    required

  • data
    object
    required

  • meta
    object
    required

example-1

{
"code": 200,
"data": {
"companyId": "12"
},
"meta": {
"message": "SUCCESS"
}
}

Bulk Create Companies

POST /companies/bulk

Request

Bulk create companies

  • When the independent company behavior is enabled, the system will not automatically create a dedicated customer group for each new Company account. Instead, you can assign a customer group to a Company account as needed using the customerGroupId field. If the customerGroupId field is not provided, the B2B company will be associated with the configured default customer group. If you have not configured a default customer group, the B2B company will not be associated with any customer group, and the company users within the company will have their corresponding customer record assigned to "No Group" in BigCommerce.
  • When the independent company behavior is turned off, a new customer group will be automatically created and associated with each new Company account. In this case, you will not use the customerGroupId field.

Authentication

  • authToken in header
Bulk create companies request body

Body

array | application/json
  • companyName
    string

    Name of this company
    >= 1 characters<= 200 characters
    Example: Tesla
  • addressLine1
    string

    Address line 1 of ths company.
    <= 200 characters
    Example: 1600 Pennsylvania Avenue NW
  • addressLine2
    string

    Address line 2 of ths company.
    <= 200 characters
    Example: Washington, DC 22202
  • city
    string

    City name of the company.
    <= 100 characters
    Example: Detroit
  • state
    string

    State of the company.
    <= 50 characters
    Example: State of Texas
  • zipCode
    string

    Zip code of the company.
    <= 50 characters
    Example: 100000
  • country
    string

    Country of the company.
    <= 200 characters
    Example: US
  • companyEmail
    string

    Contact email of this company.
    <= 200 characters
    Example: dev.b2b@test.net
  • companyPhone
    string

    Phone number of the company.
    <= 50 characters
    Example: 9090980
  • catalogName
    string

    Name of this company's catalog.
    Example: catalog
  • adminFirstName
    string

    First name of the company's administrator.
    >= 1 characters<= 100 characters
    Example: Tom
  • adminLastName
    string

    Last name of the company's administrator.
    >= 1 characters<= 100 characters
    Example: Cat
  • adminEmail
    string

    Email address of the company's administrator.
    >= 1 characters<= 100 characters
    Example: dev.b2b@test.net
  • adminPhoneNumber
    string

    Phone number of the company's administrator.
    >= 1 characters<= 100 characters
    Example: 1223312
  • acceptWelcomeEmail
    boolean

    If user accepts, the system sends a welcome email.
  • extraFields
    object

    Extra fields you want to add to the company fields.
  • channelIds
    array[integer]

    BigCommerce channel ID list
  • originChannelId
    integer

    BigCommerce channel ID, used for BigCommerce customer origin channel ID. This field takes effect only when you do not configure the store default B2B channel.
  • customerGroupId
    integer

    BigCommerce Customer Group ID. Used to associate a BigCommerce Customer Group to a B2B company when the independent company behavior is enabled.

  • userExtraFields
    array[object]

example-1

[
{
"companyName": "string",
"companyPhone": "string",
"companyEmail": "string@gmail.com",
"addressLine1": "string",
"addressLine2": "string",
"city": "string",
"state": "string",
"country": "string",
"zipCode": "string",
"adminFirstName": "string",
"adminLastName": "string",
"adminEmail": "string",
"adminPhoneNumber": "string",
"catalogId": "string",
"uuid": "string",
"acceptWelcomeEmail": false,
"channelIds": [
1,
2
],
"originChannelId": 1
}
]

Response

OK

Body

object | application/json
  • code
    integer
    required

    Example: 200
  • meta
    array[object]
    required

  • data
    object

example-1

{
"code": 200,
"meta": [
{
"companyId": 1
}
],
"data": {
"id": "string"
}
}

Update Companies (Batch)

PUT /companies/bulk

Request

Batch update companies.

  • When the independent company behavior is enabled, you can assign a customer group to a company using the customerGroupId field. Once assigned, the customer group will be associated with all users within that company. If customerGroupId is set to 0, the customer group association will be removed from the company, and all users within the company will no longer have a group assigned. The priceListAssign field will not take effect; please configure the price list for the customer group directly in the BigCommerce control panel.

  • When the independent company behavior is turned off, the customerGroupId field will not take effect. You cannot change the association between B2B companies and BigCommerce customer groups. You will use the priceListAssign field to configure the price list assigned to the company.

Authentication

  • authToken in header

Body

array | application/json
The bulk update companies list
  • companyId
    string
    required

    >= 1 characters
  • companyName
    string

    >= 1 characters
  • companyPhone
    string

  • companyEmail
    string

    >= 1 characters
  • addressLine1
    string

  • addressLine2
    string

  • city
    string

    >= 1 characters
  • state
    string

    >= 1 characters
  • country
    string

    >= 1 characters
  • zipCode
    string

  • extraFields
    array[object]

  • priceListAssign
    array[object]

  • customerGroupId
    integer

    BigCommerce Customer Group ID. Used to associate a BigCommerce Customer Group to a B2B company when the independent company behavior is enabled.

example-1

[
{
"companyId": "string",
"companyName": "string",
"companyPhone": "string",
"companyEmail": "string",
"addressLine1": "string",
"addressLine2": "string",
"city": "string",
"state": "string",
"country": "string",
"zipCode": "string",
"extraFields": [
{
"fieldName": "string",
"fieldValue": "string"
}
]
}
]

Response

Company Update Success

Body

object | application/json
  • code
    number
    required

  • data
    object
    required

  • meta
    object
    required

example-1

{
"code": 0,
"data": {
"companyId": "string"
},
"meta": {
"message": "string"
}
}

Update a Company Catalog

PUT /companies/{companyId}/catalogs

Request

Update a company catalog.

Authentication

  • authToken in header

Parameters

  • companyId in path - integer
    required
    Unique ID of company entity

Body

object | application/json
  • catalogId
    string
    required

    The catalog ID you want to update
    >= 1 characters

example-1

{
"catalogId": "string"
}

Response

OK

Body

object | application/json
  • code
    number
    required

  • data
    object
    required

  • meta
    object
    required

example-1

{
"code": 200,
"data": {
"companyId": "147340"
},
"meta": {
"message": "SUCCESS"
}
}

Update a Company Status

PUT /companies/{companyId}/status

Request

Update a company's status

Authentication

  • authToken in header

Parameters

  • companyId in path - integer
    required
    Unique ID of company entity

Body

object | application/json
  • companyStatus
    number
    required

    Company status you want to set 0: PENDING 1: APPROVED 2: REJECTED 3: INACTIVE 4: DELETED

example-1

{
"companyStatus": 1
}

Response

OK

Body

object | application/json
  • code
    number
    required

  • data
    object
    required

  • meta
    object
    required

example-1

{
"code": 200,
"data": {
"companyId": "147340"
},
"meta": {
"message": "SUCCESS"
}
}

Get Company Extra Field Configs

GET /companies/extra-fields

Request

Get company extra field configs

Authentication

  • authToken in header

Parameters

  • offset in query - number
    Pagination offset default: 0
  • limit in query - string
    Pagination limit default: 10

example

curl --request GET \
--url https://api-b2b.bigcommerce.com/api/v3/io/companies/extra-fields \
--header 'Content-Type: application/json' \
--header 'authToken: {{token}}'

Response

OK

Body

object | application/json
Response for successful request
  • code
    integer

    Response code of success request.
    Example: 200
  • meta
    object

    Used to response pagination information
    Example: {"pagination":{"limit":10,"offset":0,"totalCount":1}}
  • data
    array[object]

example

{
"code": 200,
"meta": {
"pagination": {
"limit": 10,
"offset": 0,
"totalCount": 1
}
},
"data": [
{
"id": 0,
"uuid": "string",
"fieldName": "string",
"fieldType": 0,
"isRequired": true,
"isUnique": true,
"visibleToEnduser": true,
"configType": 1,
"defaultValue": "string",
"maximumLength": "string",
"numberOfRows": "string",
"maximumValue": "string",
"listOfValue": [
"string"
]
}
]
}

Get Company Attachments

GET /companies/{companyId}/attachments

Request

Get company attachments

Authentication

  • authToken in header

Parameters

  • companyId in path - number
    required
    company Id

example

curl --request GET \
--url 'https://api-b2b.bigcommerce.com/api/v3/io/companies/[companyId]/attachments' \
--header 'Content-Type: application/json' \
--header 'authToken: {{token}}'

Response

OK

Body

object | application/json
  • code
    number

    Example: 200
  • data
    array[object]

  • meta
    object

Example 1

{
"code": 200,
"data": [
{
"id": "f593d7c8-078e-4bb6-af6b-688ef8df1a12",
"attachmentUrl": "https://xxx.com/xxx.csv"
}
],
"meta": {
"message": "SUCCESS"
}
}

Add Company Attachment

POST /companies/{companyId}/attachments

Request

Each company can upload a maximum of 10 attachments.

The API rate limit is 15/min per store.

The attachments support the following file types:

  • Images, including bmp, gif, ico, jpeg, jpg, png, svg, tif, tiff, webp, wbmp, xbm.
  • PDF
  • DOC, DOCX
  • XLS, XLSX
  • CSV

Authentication

  • authToken in header

Parameters

  • companyId in path - number
    required
    company Id

Body

object | multipart/form-data
  • attachmentFile
    string
    required

    The size of each attachment must not exceed 10MB.

Response

OK

Body

object | application/json
  • code
    number

    Default: 200

  • data
    object

  • meta
    object

Example 1

{
"code": 200,
"data": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"attachmentFile": "https://xxx.com/xxx.csv"
},
"meta": {
"message": "SUCCESS"
}
}

Delete Company Attachment

DELETE /companies/{companyId}/attachments/{attachmentId}

Request

Delete company attachment

Authentication

  • authToken in header

Parameters

  • companyId in path - number
    required
    company ID
  • attachmentId in path - string
    required
    attachment ID

example

curl --request DELETE \
--url 'https://api-b2b.bigcommerce.com/api/v3/io/companies/[companyId]/attachments/[attachmentId]' \
--header 'Content-Type: application/json' \
--header 'authToken: {{token}}'

Response

OK

Body

object | application/json
  • code
    number

    Default: 200

  • data
    object

  • meta
    object

Example 1

{
"code": 200,
"data": {},
"meta": {
"message": "SUCCESS"
}
}

See something you can improve? Edit this file on GitHub

Did you find what you were looking for?