diff --git a/docs/b2b-edition/specs/storefront/storefront/company.yaml b/docs/b2b-edition/specs/storefront/storefront/company.yaml index b0c52bf5c..88886d945 100644 --- a/docs/b2b-edition/specs/storefront/storefront/company.yaml +++ b/docs/b2b-edition/specs/storefront/storefront/company.yaml @@ -18,7 +18,7 @@ info: A Company user is a buyer with a [BigCommerce customer account](https://developer.bigcommerce.com/docs/rest-management/customers-v2#get-all-customers) associated with a B2B Edition Company account. The Users Storefront API allows you to perform common user management tasks as a B2B buyer, such as viewing and updating user information, adding users to a Company account, and deleting them. - **NOTE:** When performing storefront user management tasks as a Company user, you must confirm that the user’s Company role has the necessary permissions for the task. See [Company Roles and Permissions](https://developer.bigcommerce.com/b2b-edition/apis/rest-management/company#company-roles-and-permissions) for a complete list of permissions and their scopes. + > **NOTE:** When performing storefront user management tasks as a Company user, you must confirm that the user’s Company role has the necessary permissions for the task. See [Company Roles and Permissions](https://developer.bigcommerce.com/b2b-edition/apis/rest-management/company#company-roles-and-permissions) for a complete list of permissions and their scopes. ### Company Users and Customer Accounts @@ -29,12 +29,12 @@ info: | BigCommerce customer account | B2B Edition Company user account | | --- | --- | | **Defines:** | **Defines:** | - | - Store credit | - Storefront channel access | - | - Abandoned cart saver and product review email consent | - Basic user information like name and email address | - | - Account password and password reset | - Assigned buyer role | - | - Tax exempt code | - Company user extra fields | - | - Account signup form fields | | - | - Data collection consent | | + | Store credit | Storefront channel access | + | Abandoned cart saver and product review email consent | Basic user information like name and email address | + | Account password and password reset | Assigned buyer role | + | Tax exempt code | Company user extra fields | + | Account signup form fields | | + | Data collection consent | | ### Specifying User Role The role field uses numeric values to assign a role to a Company user account. B2B Edition’s predefined Company roles correspond the following values: @@ -56,7 +56,7 @@ security: tags: - name: Companies - name: Addresses - - name: User + - name: Users paths: /frontend/companies: @@ -71,6 +71,8 @@ paths: Equivalent Storefront GraphQL API Mutation: `companyCreate`. For more information, see the [GraphQL Playground](https://api-b2b.bigcommerce.com/graphql/playground). + > The `registerCompany` mutation in the BigCommerce Storefront GraphQL API also allows you to create a new Company account as a storefront customer. See [Company Account Registration](/docs/storefront/graphql/b2b/company-account-registration) to learn more. + 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](https://support.bigcommerce.com/s/article/B2B-Edition-Settings) in the Help Center. parameters: [] requestBody: @@ -172,7 +174,7 @@ paths: get: tags: - Companies - - User + - Users summary: "Get a Company by User ID" operationId: getcompanybyuserid description: |- @@ -231,7 +233,7 @@ paths: get: tags: - Companies - - User + - Users summary: "Get a Company User List" operationId: get-companies-companyId-users description: |- @@ -466,7 +468,7 @@ paths: properties: addresses: type: object - description: "Addresses are returned as member objects within this object using the addressId as the member key." + description: "Addresses are returned as member objects within this object using the `addressId` as the member key." properties: addressId: allOf: @@ -513,7 +515,7 @@ paths: isShipping: 1 isBilling: 0 phoneNumber: "8001234567" - addressLine1: "11305 Four Points Drive" + addressLine1: "512 Bluebonnet Lane" addressLine2: "Building 2" city: "Austin" state: @@ -570,7 +572,7 @@ paths: isDefaultShipping: "0" isDefaultBilling: "0" phoneNumber: "8001234567" - addressLine1: "11305 Four Points Drive" + addressLine1: "512 Bluebonnet Lane" addressLine2: "Building 2" city: "Austin" state: @@ -610,7 +612,7 @@ paths: summary: "Search Company Addresses" operationId: get-companies-companyId-addresses-searches description: |- - Returns all addresses associated with a Company account that match the query string `q` + Returns all addresses associated with a Company account that match the query string `q`. Equivalent Storefront GraphQL API Query: `addresses`. For more information, see the [GraphQL Playground](https://api-b2b.bigcommerce.com/graphql/playground). parameters: @@ -742,7 +744,7 @@ paths: label: "Austin Warehouse" firstName: "Marie" LastName: "Curie" - addressLine1: "11305 Four Points Drive" + addressLine1: "512 Bluebonnet Lane" addressLine2: "Building 2" city: "Austin" state: @@ -779,7 +781,7 @@ paths: description: |- Returns a specific address based on the `companyId` and `addressId` in the path. - Equivalent Storefront GraphQL API Query: address. For more information, see the [GraphQL Playground](https://api-b2b.bigcommerce.com/graphql/playground). + Equivalent Storefront GraphQL API Query: `address`. For more information, see the [GraphQL Playground](https://api-b2b.bigcommerce.com/graphql/playground). parameters: [] responses: "200": @@ -823,7 +825,7 @@ paths: isDefaultShipping: "0" isDefaultBilling: "0" phoneNumber: "8001234567" - addressLine1: "11305 Four Points Drive" + addressLine1: "512 Bluebonnet Lane" addressLine2: "Building 2" city: "Austin" state: @@ -893,7 +895,7 @@ paths: isDefaultShipping: "0" isDefaultBilling: "0" phoneNumber: "8001234567" - addressLine1: "11305 Four Points Drive" + addressLine1: "512 Bluebonnet Lane" addressLine2: "Building 2" city: "Austin" state: @@ -965,7 +967,7 @@ paths: summary: "Get Company Default Addresses" operationId: get-companies-companyId-default-addresses description: |- - Returns a Company’s default shipping and billing addresses. Use Update Address Information to change which addresses are set as the defaults. + Returns a Company’s default shipping and billing addresses. Use [Update Address Information](#update-address-information) to change which addresses are set as the defaults. Equivalent Storefront GraphQL API Query: `defaultBillingAddress` for the billing address and `defaultShippingAddress` for the shipping address. For more information, see the [GraphQL Playground](https://api-b2b.bigcommerce.com/graphql/playground). parameters: [] @@ -1005,7 +1007,7 @@ paths: firstName: "Marie" lastName: "Curie" phoneNumber: "8001234567" - addressLine1: "11305 Four Points Drive" + addressLine1: "512 Bluebonnet Lane" addressLine2: "Building 2" city: "Austin" state: @@ -1024,7 +1026,7 @@ paths: firstName: "Marie" lastName: "Curie" phoneNumber: "8001234567" - addressLine1: "11305 Four Points Drive" + addressLine1: "512 Bluebonnet Lane" addressLine2: "Building 2" city: "Austin" state: @@ -1041,7 +1043,7 @@ paths: parameters: [] get: tags: - - User + - Users summary: "Check Existence of a Customer Email" operationId: get-users-validations-existence description: "This endpoint previously validated extra fields for a particular Company user by email address." @@ -1071,7 +1073,7 @@ paths: parameters: [] get: tags: - - User + - Users summary: "Get User List" operationId: get-users description: |- @@ -1109,7 +1111,7 @@ paths: $ref: "#/components/schemas/responsePagination" post: tags: - - User + - Users summary: "Create a User" operationId: post-users description: |- @@ -1180,7 +1182,7 @@ paths: - $ref: "#/components/parameters/userId" get: tags: - - User + - Users summary: "Get User Information" operationId: get-users-userId description: |- @@ -1223,7 +1225,7 @@ paths: $ref: "#/components/schemas/userEmail" put: tags: - - User + - Users summary: "Update User Information" operationId: put-users-userId description: |- @@ -1254,7 +1256,7 @@ paths: $ref: "#/components/responses/genericResponse" delete: tags: - - User + - Users summary: "Delete a User" operationId: delete-users-userId description: |- @@ -1274,7 +1276,7 @@ components: addressLine1: type: string description: "The first line of the address" - example: "11305 Four Points Drive" + example: "512 Bluebonnet Lane" addressLine2: type: string description: "The second line of the address" @@ -1388,7 +1390,7 @@ components: companyAddress: type: string description: "The local address information for the address." - example: "11305 Four Points Drive, Building 2" + example: "512 Bluebonnet Lane, Building 2" companyCity: $ref: "#/components/schemas/companyCity" companyState: diff --git a/docs/storefront/graphql/b2b/company-account-registration.mdx b/docs/storefront/graphql/b2b/company-account-registration.mdx new file mode 100644 index 000000000..8f870227f --- /dev/null +++ b/docs/storefront/graphql/b2b/company-account-registration.mdx @@ -0,0 +1,207 @@ +# 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](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) (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](#considerations) for more information. + +### Example Mutation + + + + + ```graphql filename="Example mutation: Register a Company account" showLineNumbers copy + 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 + } + } + } + } + } + ``` + + + + ```json filename="Example mutation: Register a customer" showLineNumbers copy + # Success + + { + "data": { + "company": { + "registerCompany": { + "entityId": 123456, + "status": "PENDING", + "errors": [] + } + } + } + } + + + # Error - Customer not authenticated + + { + "data": { + "company": { + "registerCompany": { + "entityId": null, + "status": null, + "errors": [ + { + "__typename": "ValidationError", + "message": "Customer not authenticated", + "path": [ + "input" + ] + } + ] + } + } + } + } + ``` + + + +### 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. + +**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](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. 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](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) + +### Tools + +* [GraphQL Storefront API reference](/graphql-storefront/reference) +* [GraphQL Storefront Playground](/graphql-storefront/playground) + +### Community + + * [Developer community](/community)