Companies
Get All Companies
GET https://api-b2b.bigcommerce.com/api/v3/io/companiesRequest
companyId
from highest to lowest by default. Pass optional parameters to modify the results.Authentication
- authToken in header
Parameters
- limit in query with default of 10 - integerDetermines the number of records to return per page. If left blank, this defaults to
10
. - offset in query0 - integerThe number of results to skip before returning the first result. If left blank, this defaults to
0
. - minModified in query - numberThe earliest Unix timestamp that can be returned for a modified Company account.
- maxModified in query - numberThe latest Unix timestamp that can be returned for a modified Company account.
- minCreated in query - numberThe earliest Unix timestamp that can be returned for a modified Company account.
- maxCreated in query - numberThe latest Unix timestamp that can be returned for a modified Company account.
- sortBy in query with default of updatedAt - stringSorts results by Company name or last updated date, defaulting to the last updated date if no parameter is provided.Example: updatedAt
Allowed: companyName | updatedAt
- orderBy in query with default of DESC - stringEstablish a descending or ascending order of results. The order defaults to descending if the parameter is not included.Example: DESC
Allowed: ASC | DESC
- isIncludeExtraFields in query with default of 0 - string
Indicates whether or not the response will include Company extra fields. If the parameter is not included, the response will exclude extra fields by default.
A value of
0
will exclude extra fields, while a value of1
will include them.Allowed: 0 | 1
- companyStatus in query - integerThe Company’s activity status. See Company Status Codes to learn about their corresponding statuses.Example: 1
Allowed: 0 | 1 | 2 | 3
- q in query - stringEnter a Company name to return partial and exact matches.
- extraFields in query - array
Use this array to filter results by an extra field name-value pair.
Exact usage is formatted as
?extraFields=name:value
. Including this filter returns any Company account where the extra fieldname
containsvalue
. To search on more than one extra field, the parameter may be repeated to capture more specific instances such as?extraFields=name1:value1&extraFields=name2,value2
, which will return all Companies where the extra fieldsname1
andname2
containvalue1
andvalue2
, respectively.Type: array[string] - bcOrderId in query - integerThe ID of a BigCommerce order placed by a particular Company account.Example: 102
- orderId in query - stringThe ID of a BigCommerce order placed by a particular Company account.
- bcGroupId in query - stringThe ID of the BigCommerce customer group assigned to the Company account.
- customerId in query - integerThe ID of a BigCommerce customer account with a corresponding Company user account.
- extraFieldFilterType in query with default of search - string
Establishes how results are filtered when using the
extraFields
parameter. Thesearch
filter type allows for partial matches, while theexact-match
filter type only returns results that exactly match the specified criteria.The filter type defaults to
search
when no parameter is provided.Allowed: search | exact-match
example
Response
Body
codenumber
dataarray[object]
example
Create a Company
POST https://api-b2b.bigcommerce.com/api/v3/io/companiesRequest
Creates a new Company account. This endpoint also creates a Company user account for the administrator of the business.
If you have configured required information fields in your store’s Extra Fields settings for Company accounts or Company users, you must include the field’s name and value in the extraFields
array of the request body. For more information on extra fields, see B2B Edition Settings in the Help Center.
After you have created a new Company account, you can configure all of its features and settings by using the Update a Company endpoint.
Independent vs Dependent Companies Behavior
When Independent Company behavior is enabled on your store, 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 included in the request body, the Company account will be assigned to your configured default customer group.
If you have not configured a default customer group or set the value of customerGroupId
to 0
, the Company account will not be associated with any customer group, and its users will use your storefront’s default catalog visibility and pricing.
If your store is using legacy Dependent Company behavior, 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
extraFieldsarray[object]
userExtraFieldsarray[object]
companyNamestring
requiredThe name of the business associated with the Company account.>= 1 characters<= 200 charactersExample: Great Buys Inc.companyEmailstring
requiredThe primary email address for the Company account.>= 1 characters<= 200 charactersExample: admin@greatbuys.comcompanyPhonestring
requiredThe primary phone number for the Company account.<= 50 charactersExample: 8001234567customerGroupIdinteger
The ID of the BigCommerce customer group assigned to the Company account. This field can be static or configurable depending on whether or not your store uses Independent Companies behavior. See Independent Companies Behavior for more information.Example: 123addressLine1string
The first line of the primary address for the Company account.<= 200 charactersExample: 123 Main StreetaddressLine2string
The second line of the primary address for the Company account.<= 200 charactersExample: Building 100citystring
The city of the primary address for the Company account.>= 1 characters<= 100 charactersExample: Austinstatestring
The state of the primary address for the Company account, if applicable. This must be the full name and not an abbreviation.>= 1 characters<= 50 charactersExample: Texascountrystring
requiredThe country of the primary address for the Company account. This must be either the full name or the ISO2 country code.>= 1 characters<= 200 charactersExample: `United States` or `US`zipCodestring
The postal code of the primary address for the Company account.<= 50 charactersExample: 78726adminFirstNamestring
requiredThe first name of the Company account administrator.>= 1 characters<= 100 charactersExample: MarieadminLastNamestring
requiredThe last name of the Company account administrator.>= 1 characters<= 100 charactersExample: CurieadminEmailstring
requiredThe email address of the Company account administrator. If an existing BigCommerce customer account uses this email address, it is automatically linked to the administrator’s Company user account.>= 1 characters<= 100 charactersExample: m.curie@greatbuys.comadminPhoneNumberstring
The phone number of the Company account administrator.>= 1 characters<= 100 charactersExample: 8001234567originChannelIdinteger
The storefront channel ID designated as the origin for the Company administrator. Use1
for your store’s default storefront channel.Example: 1channelIdsarray[integer]
The storefront channel IDs in which buyers can access their Company’s Buyer Portal. Use1
for your store’s default storefront channel.Type: array[integer]Example: [1,10001234]catalogIdinteger
The ID of the price list assigned to the Company account. This field is read-only for stores using Independent Companies Behavior.
If your store uses legacy Dependent Companies behavior and it does not have Multi-Storefront enabled, this field is required for creating new Company accounts. If your store has Multi-Storefront enabled, use the
priceListAssign
array instead.Example: 123456acceptCreationEmailboolean
Indicates whether or not the administrator receives a welcome email when the Company account is created.
true
: Sends the welcome email to the admin userfalse
: Does not send the emailExample: trueDefault: false
Create a Company
Response
Body
codeinteger
dataobject
200 - Created
Get Company Details
GET https://api-b2b.bigcommerce.com/api/v3/io/companies/{companyId}Request
Authentication
- authToken in header
Parameters
- companyId in path - integerrequiredUnique numeric ID of the Company account.
example
Response
Body
codenumber
dataobject
example
Update a Company
PUT https://api-b2b.bigcommerce.com/api/v3/io/companies/{companyId}Request
Updates a Company’s attributes.
If you have configured required information fields in your store’s Extra Fields settings for Company accounts or Company users, you must include the field’s name and value in the extraFields
array of the request body. For more information on extra fields, see B2B Edition Settings in the Help Center.
Independent vs. Dependent Companies Behavior
This endpoint applies the same rules to the customerGroupId
field as Create a Company, based on the Company behavior used in your store. Additionally, the priceListAssign
field is not compatible with Independent Companies behavior because a Company’s price list is configured from its assigned customer group.
If your store is using Dependent Companies behavior, use the priceListAssign
field to assign a price list to the Company account.
Authentication
- authToken in header
Parameters
- companyId in path - integerrequiredUnique numeric ID of the Company account.
Body
companyNamestring
The name of the business associated with the Company account.>= 1 characters<= 200 charactersExample: Great Buys Inc.companyEmailstring
The primary email address for the Company account.>= 1 characters<= 200 charactersExample: admin@greatbuys.comcompanyPhonestring
The primary phone number for the Company account.<= 50 charactersExample: 8001234567customerGroupIdinteger
The ID of the BigCommerce customer group assigned to the Company account. This field can be static or configurable depending on whether or not your store uses Independent Companies behavior. See Independent Companies Behavior for more information.Example: 123addressLine1string
The first line of the primary address for the Company account.<= 200 charactersExample: 123 Main StreetaddressLine2string
The second line of the primary address for the Company account.<= 200 charactersExample: Building 100citystring
The city of the primary address for the Company account.>= 1 characters<= 100 charactersExample: Austinstatestring
The state of the primary address for the Company account, if applicable. This must be the full name and not an abbreviation.>= 1 characters<= 50 charactersExample: Texascountrystring
The country of the primary address for the Company account. This must be either the full name or the ISO2 country code.>= 1 characters<= 200 charactersExample: `United States` or `US`zipCodestring
The postal code of the primary address for the Company account.<= 50 charactersExample: 78726uuidstring
An external ID assigned to the Company account in a third-party system, such as an ERP. Leave this field blank if you do not have an external system.Example: 497f6eca-6276-4993-bfeb-53cbbbba6f08priceListAssignarray[object]
Use this array to assign a price list to a Company account if your store uses legacy Dependent Companies behavior and it has Multi-Storefront enabled. Use catalogId to assign price lists if you have not enabled Multi-Storefront.
This field is read-only for stores using Independent Companies behavior. See Independent Companies Behavior for more information.
extraFieldsarray[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.
example
Response
Body
codenumber
dataobject
200 - UPDATED
Delete a Company
DELETE https://api-b2b.bigcommerce.com/api/v3/io/companies/{companyId}Request
Deletes a Company account.
Independent vs. Dependent Companies Behavior
If your store is using Independent Companies behavior, deleting a Company account has no effect on its assigned customer group.
With Dependent Companies behavior, Company accounts and BigCommerce customer groups have a one-to-one relationship. Deleting a Company will also delete the corresponding customer group.
Authentication
- authToken in header
Parameters
- companyId in path - integerrequiredUnique numeric ID of the Company account.
example
Response
Body
codeinteger
dataobject
200 - SUCCESS
Convert a BigCommerce Customer Group into a Company
POST https://api-b2b.bigcommerce.com/api/v3/io/customer-groups/{customerGroupId}/companiesRequest
Creates a Company account that is automatically assigned to a BigCommerce customer group. You cannot create a Company from a customer group that already has an assigned Company account.
Note that this endpoint is not supported if your store:
- Has Multi-Storefront enabled
- Is using Independent Companies behavior
If you have configured required information fields in your store’s Extra Fields settings for Company accounts or Company users, you must include the field’s name and value in the extraFields array of the request body. For more information on extra fields, see B2B Edition Settings in the Help Center.
Authentication
- authToken in header
Parameters
- customerGroupId in path - stringrequiredThe BigCommerce customer group ID associated with the Company account.
Body
companyNamestring
requiredThe name of the business associated with the Company account.<= 200 charactersExample: Great Buys Inc.companyPhonestring
requiredThe primary phone number for the Company account.<= 50 charactersExample: 8001234567companyEmailstring
requiredThe primary email address for the Company account.<= 200 charactersExample: admin@greatbuys.comcatalogIdstring
The ID of the price list assigned to the Company account. This field is read-only for stores using Independent Companies Behavior.
If your store uses legacy Dependent Companies behavior and it does not have Multi-Storefront enabled, this field is required for creating new Company accounts. If your store has Multi-Storefront enabled, use the
priceListAssign
array instead.Example: 123456acceptCreationEmailboolean
Indicates whether or not the administrator receives a welcome email when the Company account is created.
true
: Sends the welcome email to the admin userfalse
: Does not send the emailExample: trueDefault: false
addressLine1string
The first line of the primary address for the Company account.<= 200 charactersExample: 123 Main StreetaddressLine2string
The second line of the primary address for the Company account.<= 200 charactersExample: Building 100citystring
The city of the primary address for the Company account.>= 1 characters<= 100 charactersExample: Austinstatestring
The state of the primary address for the Company account, if applicable. This must be the full name and not an abbreviation.>= 1 characters<= 50 charactersExample: Texascountrystring
requiredThe country of the primary address for the Company account. This must be either the full name or the ISO2 country code.>= 1 characters<= 200 charactersExample: `United States` or `US`zipCodestring
The postal code of the primary address for the Company account.<= 50 charactersExample: 78726adminFirstNamestring
The first name of the Company account administrator.>= 1 characters<= 100 charactersExample: MarieadminLastNamestring
The last name of the Company account administrator.>= 1 characters<= 100 charactersExample: CurieadminEmailstring
requiredThe email address of the Company account administrator. If an existing BigCommerce customer account uses this email address, it is automatically linked to the administrator’s Company user account.>= 1 characters<= 100 charactersExample: m.curie@greatbuys.comadminPhoneNumberstring
requiredThe phone number of the Company account administrator.>= 1 characters<= 100 charactersExample: 8001234567extraFieldsarray[object]
userExtraFieldsarray[object]
CONVERT GROUP
Response
Body
codeinteger
dataobject
200 - CREATED
Bulk Create Companies
POST https://api-b2b.bigcommerce.com/api/v3/io/companies/bulkRequest
Creates multiple Company accounts at once. You can create up to 10
Companies in a single request.
See Create a Company for recommendations on formatting individual Companies in the array.
Authentication
- authToken in header
Body
companyNamestring
requiredName of this company>= 1 characters<= 200 charactersExample: TeslaaddressLine1string
Address line 1 of ths company.<= 200 charactersExample: 1600 Pennsylvania Avenue NWaddressLine2string
Address line 2 of ths company.<= 200 charactersExample: Washington, DC 22202citystring
City name of the company.<= 100 charactersExample: Detroitstatestring
State of the company.<= 50 charactersExample: State of TexaszipCodestring
Zip code of the company.<= 50 charactersExample: 100000countrystring
requiredCountry of the company.<= 200 charactersExample: UScompanyEmailstring
requiredContact email of this company.<= 200 charactersExample: dev.b2b@test.netcompanyPhonestring
requiredPhone number of the company.<= 50 charactersExample: 9090980catalogNamestring
Name of this company's catalog.Example: catalogadminFirstNamestring
requiredFirst name of the company's administrator.>= 1 characters<= 100 charactersExample: TomadminLastNamestring
requiredLast name of the company's administrator.>= 1 characters<= 100 charactersExample: CatadminEmailstring
requiredEmail address of the company's administrator.>= 1 characters<= 100 charactersExample: dev.b2b@test.netadminPhoneNumberstring
Phone number of the company's administrator.>= 1 characters<= 100 charactersExample: 1223312userExtraFieldsarray[object]
acceptWelcomeEmailboolean
If user accepts, the system sends a welcome email.extraFieldsobject
Extra fields you want to add to the company fields.channelIdsarray[integer]
The storefront channel IDs in which buyers can access their Company’s Buyer Portal. Use1
for your store’s default storefront channel.Type: array[integer]Example: [1,10001234]originChannelIdinteger
The storefront channel ID designated as the origin for the Company administrator. Use 1 for your store’s default storefront channel.Example: 1customerGroupIdinteger
The ID of the BigCommerce customer group assigned to the Company account. This field can be static or configurable depending on whether or not your store uses Independent Companies behavior. See Independent Companies Behavior for more information.Example: 123
example
Response
Body
codeinteger
dataobject
200 - SUCCESS
Update Companies (Batch)
PUT https://api-b2b.bigcommerce.com/api/v3/io/companies/bulkRequest
10
Company accounts at once. See Update a Company for recommendations on formatting individual Companies in the array.Authentication
- authToken in header
Body
companyIdinteger
requiredUnique numeric ID of the Company account. This is a read-only field; do not set or modify its value in aPOST
orPUT
request.Example: 123456companyNamestring
The name of the business associated with the Company account.>= 1 characters<= 200 charactersExample: Great Buys Inc.companyEmailstring
The primary email address for the Company account.>= 1 characters<= 200 charactersExample: admin@greatbuys.comcompanyPhonestring
The primary phone number for the Company account.<= 50 charactersExample: 8001234567customerGroupIdinteger
The ID of the BigCommerce customer group assigned to the Company account. This field can be static or configurable depending on whether or not your store uses Independent Companies behavior. See Independent Companies Behavior for more information.Example: 123addressLine1string
The first line of the primary address for the Company account.<= 200 charactersExample: 123 Main StreetaddressLine2string
The second line of the primary address for the Company account.<= 200 charactersExample: Building 100citystring
The city of the primary address for the Company account.>= 1 characters<= 100 charactersExample: Austinstatestring
The state of the primary address for the Company account, if applicable. This must be the full name and not an abbreviation.>= 1 characters<= 50 charactersExample: Texascountrystring
The country of the primary address for the Company account. This must be either the full name or the ISO2 country code.>= 1 characters<= 200 charactersExample: `United States` or `US`zipCodestring
The postal code of the primary address for the Company account.<= 50 charactersExample: 78726priceListAssignarray[object]
Use this array to assign a price list to a Company account if your store uses legacy Dependent Companies behavior and it has Multi-Storefront enabled. Use catalogId to assign price lists if you have not enabled Multi-Storefront.
This field is read-only for stores using Independent Companies behavior. See Independent Companies Behavior for more information.
extraFieldsarray[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.
example
Response
Body
codenumber
dataobject
200 - UPDATED
Update a Company's Catalog
PUT https://api-b2b.bigcommerce.com/api/v3/io/companies/{companyId}/catalogsRequest
Authentication
- authToken in header
Parameters
- companyId in path - integerrequiredUnique numeric ID of the Company account.
Body
catalogIdstring
requiredThe ID of the price list assigned to the Company account. This field is read-only for stores using Independent Companies Behavior.
If your store uses legacy Dependent Companies behavior and it does not have Multi-Storefront enabled, this field is required for creating new Company accounts. If your store has Multi-Storefront enabled, use the
priceListAssign
array instead.Example: 123456
example
Response
Body
codenumber
dataobject
200 - UPDATED
Update a Company's Status
PUT https://api-b2b.bigcommerce.com/api/v3/io/companies/{companyId}/statusRequest
Authentication
- authToken in header
Parameters
- companyId in path - integerrequiredUnique numeric ID of the Company account.
Body
companyStatusinteger
requiredSee Company Status Codes to learn about their corresponding statuses.Allowed: 0 | 1 | 2 | 3
Example: 1
example-1
Response
Body
codenumber
dataobject
200 - UPDATED
Get Company Extra Field Configs
GET https://api-b2b.bigcommerce.com/api/v3/io/companies/extra-fieldsRequest
Authentication
- authToken in header
Parameters
- limit in query with default of 10 - integerDetermines the number of records to return per page. If left blank, this defaults to
10
. - offset in query0 - integerThe number of results to skip before returning the first result. If left blank, this defaults to
0
.
example
Response
Body
codeinteger
Response code of success request.Example: 200dataarray[object]
example
Get Company Attachments
GET https://api-b2b.bigcommerce.com/api/v3/io/companies/{companyId}/attachmentsRequest
Authentication
- authToken in header
Parameters
- companyId in path - integerrequiredUnique numeric ID of the Company account.
example
Response
Body
codenumber
Default: 200
dataobject
Example 1
Add a Company Attachment
POST https://api-b2b.bigcommerce.com/api/v3/io/companies/{companyId}/attachmentsRequest
Attaches a file to a Company account.
The default rate limit for this endpoint is 15
calls/min per store.
Each Company can have a maximum of 10
attachments. The following file types are supported:
- Image files (BMP, GIF, ICO, JPG/JPEG, PNG, SVG, TIF, TIFF, WEBP, WBMP, XBM)
- PDF
- DOC, DOCX
- XLS, XLSX
- CSV
Authentication
- authToken in header
Parameters
- companyId in path - integerrequiredUnique numeric ID of the Company account.
Body
Response
Body
codenumber
Default: 200
dataobject
Example 1
Delete a Company Attachment
DELETE https://api-b2b.bigcommerce.com/api/v3/io/companies/{companyId}/attachments/{attachmentId}Request
Authentication
- authToken in header
Parameters
- companyId in path - integerrequiredUnique numeric ID of the Company account.
- attachmentId in path - stringrequiredThe ID of a file attached to a Company account.
example
Response
Body
codeinteger
dataobject