GraphQL Storefront API: Company Account Registration
Overview
In most scenarios, B2B Edition's GraphQL Storefront API powers access to Company account objects, including a Company's users and addresses. The default Buyer Portal uses these queries and mutations to handle the Company creation and management experience for buyers.
However, BigCommerce's GraphQL Storefront API includes the registerCompany mutation for requesting a Company account as a storefront user with an existing customer account. This allows you to build separate forms for registering customers (opens in a new tab) and Companies using a unified set of APIs and authentication models.
The registerCompany mutation accepts Company information like name, primary address, and custom fields configured in the B2B Edition control panel. If you've created extra fields for Company user records, it also allows current B2C customers to supply that information while requesting a B2B account. Upon success, this generates a new Company account in either the Pending or Active status, depending on your store's Company management configurations. See the "General Settings" section of B2B Edition Settings (opens in a new tab) in the Help Center for more information.
The mutation also passes the customer_id and channel_id of the current sesion in order to generate a Company user account for the customer and set the corresponding storefront as the user's origin channel.
Tokens
To authenticate calls to the GraphQL Storefront API, your application can generate a bearer token. This can be done by using 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.
For more information, see Storefront tokens in the Authenticating requests to the GraphQL Storefront API article and Dynamic tokens in the Strategies and Example Requests article.
Registering a Company Account
Required Fields
For successful Company registration, the request must include the following information:
- Company name (
name) - Primary Company email address (
email) - Primary Company phone number (
phone) - Company physical address object (
address) with the following fields:firstNamelastNameaddress1citycountryCodestateOrProvinceif required by the country (must be the full name and not the two-letter code)
You may also need to include extra fields for Company accounts, Company users, and addresses depending on how their configuration. See Considerations for more information.
Example Mutation
mutation {
company {
registerCompany(
input: {
name: "Great Buys Incorporated",
email: "info@greatbuysinc.com",
phone: "5121234567",
fileList:[
{fileId: "uniquefile.pdf"}
],
address: {
firstName: "Marie",
lastName: "Curie",
address1: "123 Main Street",
city: "Austin",
countryCode: "US",
stateOrProvince: "Texas",
phone: "5121234567",
postalCode: "78704"
# Address extra fields
extraFields: {
texts: [
{ name: "Text Field Name", text: "Text Value" }
],
multilineTexts: [
{ name: "Multiline Field Name", multilineText: "Multi-Line Text Value" }
],
multipleChoices: [
{ name: "Multiple Choice Field Name", fieldValue: "Choice Value" }
],
numbers: [
{ name: "Number Field Name", number: 1.0 }
]
}
},
# Company account extra fields
extraFields: {
texts: [
{ name: "Text Field Name", text: "Text Value" }
],
multilineTexts: [
{ name: "Multiline Field Name", multilineText: "Multi-Line Text Value" }
],
multipleChoices: [
{ name: "Multiple Choice Field Name", fieldValue: "Choice Value" }
],
numbers: [
{ name: "Number Field Name", number: 1.0 }
]
},
# Company user extra fields
companyUser: {
extraFields: {
texts: [
{ name: "Text Field Name", text: "Text Value" }
],
multilineTexts: [
{ name: "Multiline Field Name", multilineText: "Multi-Line Text Value" }
],
multipleChoices: [
{ name: "Multiple Choice Field Name", fieldValue: "Choice Value" }
],
numbers: [
{ name: "Number Field Name", number: 1.0 }
]
}
}
}
) {
entityId
status
errors {
... on ValidationError {
message
path
}
}
}
}
}Considerations
While using the registerCompany mutation, take note of the following information:
Required Extra Fields
When configuring extra fields in your B2B Edition control panel for Company accounts, users, and addresses, you can mark individual fields as required. Any required extra fields must be captured in the request. To learn more about extra fields, see the "Extra Fields Settings" section of B2B Edition Settings (opens in a new tab) in the Help Center.
Company Files
The fileList array contains fileId strings comprised of each file's name and extension. It is optional and only used if the customer has uploaded a file during registration. For more information on Company file attachments, such as file size and type requirements, see the "Managing Attached Files" section of Companies (opens in a new tab) in the Help Center.
Pending Company Accounts
After making a successful request, the newly-created Company is assigned the Pending status. In the Settings › General area of your B2B Edition control panel, you can further configure the Company registration experience by limiting product visibility and purchasing for pending Company users, or by automatically approving all applications. See the "General Settings" section of B2B Edition Settings (opens in a new tab) in the Help Center for more information on Company management settings.
Resources
Documentation
API Reference
- Create a storefront token
- Create a customer impersonation token
- REST Management API: Companies REST Storefront API: Companies