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 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 in the Help Center for more information.

The mutation also passes the customer_id and channel_id of the current session 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:
  • firstName
  • lastName
  • address1
  • city
  • countryCode
  • stateOrProvince if 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 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 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 in the Help Center for more information on Company management settings.

Resources

Documentation

• GraphQL Storefront API Overview
• Guide to API Accounts
• Customers: Register a customer

API Reference

• Create a storefront token
• Create a customer impersonation token
• REST Management API: Companies REST Storefront API: Companies

Tools

• GraphQL Storefront API reference
• GraphQL Storefront Playground

Community

• Developer community