DEVDOCS-6473 - Unified Storefront GraphQL: Account registration workflows

docs/storefront/graphql/b2b/company-account-registration

@@ -0,0 +1,204 @@
+# 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 includdes 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](https://developer.bigcommerce.com/docs/storefront/graphql/customers#register-a-customer) 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](https://support.bigcommerce.com/s/article/B2B-Edition-Settings) 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](/docs/rest-authentication/tokens#create-a-token) or the [Create a customer impersonation token](/docs/rest-authentication/tokens/customer-impersonation-token#create-a-token) REST endpoint. On a Stencil storefront, you can also [access a token](/docs/storefront/graphql) directly from the page context.
+
+For more information, see [Storefront tokens](/docs/start/authentication/graphql-storefront#storefront-tokens) in the Authenticating requests to the GraphQL Storefront API article and [Dynamic tokens](/docs/start/authentication#bigcommerce-generated-jwts) 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](/b2b-edition/apis/rest-management/address/addresses#get-a-state)
+
+You may also need to include extra fields for Company accounts, Company users, and addresses depending on how their configuration. See [Considerations](#considerations) for more information.
+
+### Example Mutation
+
+<Tabs items={[`Request`, `Response`]}>
+  <Tab>
+    ```graphql filename="Example mutation: Register a Company account" showLineNumbers copy
+    mutation {
+        company {
+        registerCompany(
+            input: {
+                name: "Great Buys Incorporated",
+                email: "[email protected]",
+                phone: "5121234567",
+                taxExemptCategory: "G",
+                fileList:[
+                    {fileName: "uniquefile.pdf"}
+                ]
+                address: {
+                    firstName: "Marie",
+                    lastName: "Curie",
+                    address1: "123 Main Street",
+                    city: "Austin",
+                    countryCode: "US",
+                    stateOrProvince: "TX",
+                    phone: "5121234567",
+                    postalCode: "78704"
+                    # Address extra fields
+                    extraFields: { 
+                        texts: [
+                            { fieldEntityId: 123, text: "Text Value" }
+                        ],
+                        multilineTexts: [
+                            { fieldEntityId: 234, multilineText: "Multi-Line Text Value" }
+                        ],
+                        multipleChoices: [
+                            { fieldEntityId: 345, fieldValue: "Choice Value" }
+                        ],
+                        numbers: [
+                            { fieldEntityId: 456, number: 1.0 }
+                        ]
+                    }
+                },
+                # Company account extra fields
+                extraFields: { 
+                    texts: [
+                        { fieldEntityId: 123, text: "Text Value" }
+                    ],
+                    multilineTexts: [
+                        { fieldEntityId: 234, multilineText: "Multi-Line Text Value" }
+                    ],
+                    multipleChoices: [
+                        { fieldEntityId: 345, fieldValue: "Choice Value" }
+                    ],
+                    numbers: [
+                        { fieldEntityId: 456, number: 1.0 }
+                    ]
+                },
+                #Company user extra fields
+                companyUser: { 
+                    extraFields: {
+                        texts: [
+                            { fieldEntityId: 123, text: "Text Value" }
+                        ],
+                        multilineTexts: [
+                            { fieldEntityId: 234, multilineText: "Multi-Line Text Value" }
+                        ],
+                        multipleChoices: [
+                            { fieldEntityId: 345, fieldValue: "Choice Value" }
+                        ],
+                        numbers: [
+                            { fieldEntityId: 456, number: 1.0 }
+                        ]
+                    }
+                }
+            }
+        ) {
+            entityId
+            status
+            errors {
+            ... on ValidationError {
+                message
+                path
+            }
+            }
+        }
+        }
+    }
+    ```
+  </Tab>
+  <Tab>
+    ```json filename="Example mutation: Register a customer" showLineNumbers copy
+    # Success
+
+    {
+      "data": {
+        "company": {
+          "registerCompany": {
+            "company": {
+              "id": 123456,
+              "name": "Great Buys Incorporated",
+              "status": 0
+            },
+            "errors": []
+          }
+        }
+      }
+    }
+
+
+    # Error - Customer not authenticated
+
+    {
+      "data": {
+        "company": {
+          "registerCompany": {
+            "company": null,
+            "errors": [
+              {
+                "__typename": "ValidationError",
+                "message": "Customer not authenticated."
+              }
+            ]
+          }
+        }
+      }
+    }
+    ```
+  </Tab>
+</Tabs>
+
+### 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](https://support.bigcommerce.com/s/article/B2B-Edition-Settings) in the Help Center.
+
+**Tax Exempt Category**
+
+The `taxExemptCategory` field accepts a tax exemption code for an automatic tax provider like Avalara, which is saved to the Company account. The entered code automatically applies to the Company's users, as well as any Super Admins masquerading as the Company. This functionality is not available by default in B2B Edition stores, but you can request it by [contacting our support team](http://support.bigcommerce.com/s/#contact).
+
+**Company Files**
+
+The `fileList` array contains `fileName` strings comprised of a file's name and extension. It is optional, and only used if the customer has uploaded a file during registration. To learn more about Company file attachments and their limitation, see the "Managing Attached Files" section of [Companies](https://support.bigcommerce.com/s/article/B2B-Edition-User-Guide-Company-and-Customer-Functions) in the Help Center.
+
+**Pending Company Accounts**
+
+After making a successful request, the newly-created Company is assigned the Pending status, which is represented as a numeric ID of `0` in the response. In the **Settings** &rsaquo; **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](https://support.bigcommerce.com/s/article/B2B-Edition-Settings) in the Help Center for more information on Company management settings.
+
+## Resources
+
+### Documentation
+
+* [GraphQL Storefront API Overview](/docs/storefront/graphql)
+* [Guide to API Accounts](/docs/start/authentication/api-accounts)
+* [Customers: Register a customer](/docs/storefront/graphql/customers#register-a-customer)
+
+### API Reference
+
+* [Create a storefront token](/docs/rest-authentication/tokens#create-a-token)
+* [Create a customer impersonation token](/docs/rest-authentication/tokens/customer-impersonation-token#create-a-token)
+* [REST Management API: Companies](/b2b-edition/apis/rest-management/company)
+  [REST Storefront API: Companies](/b2b-edition/apis/rest-storefront/company)
+
+  ### Community
+
+  * [Developer community](/community)