Business units types

The types the business units domain defines, with the fields other domains add to them.

Objects

`BusinessUnit`

Fields added by Invoice, Multiple carts, Order, Order approval, Quote, Return and Shopping lists

Field	Type	Description
`id`	`ID!`	Unique identifier for the business unit
`name`	`String!`	Name of the business unit
`cocNumber`	`String`	Chamber-of-commerce registration of the company. Null where the project does not record one.
`vatNumber`	`String`	VAT registration of the company. Null where the project does not record one.
`vatNumbers`	`[String!]!`	Every VAT registration of the company, vatNumber among them: one per member state it is registered in. A delivery to a member state the company is registered in, other than the seller's, is reverse-charged. Empty where the project records none.
`eoriNumber`	`String`	The company's EORI number, which customs need to clear its exports. Null where the project does not record one.
`credit`	`BusinessUnitCredit`	What the company may buy on account and how much of that it has used. Null where the project records no credit limit for the company.
`oneOffShippingAddressesAllowed`	`Boolean!`	Whether a checkout may ship to an address outside the company's address book, typed in for one order. True unless a company administrator turned one-off addresses off; a cart is then shipped to one of the book's addresses only, and any other is refused.
`paymentTerms`	`BusinessUnitPaymentTerms`	When the company pays for what it buys on account, for a checkout to state beside the price. Null where the project records no payment terms for the company.
`stores`	`[Store!]`	Stores assigned to the business unit
`address`	`Address`	Address of the business unitArguments: `id`
`billingAddress`	`Address`	Billing address of the business unit
`defaultShippingAddress`	`Address`	The address the unit ships to unless told otherwise. Null where nobody has chosen one. Never simply the first entry of a book that holds several: with dozens of addresses in no meaningful order, that is a guess a checkout would present as the company's decision.
`addresses`	`AddressResult!`	Addresses of the business unit. A search term narrows the book by name, company, street, postal code, city or region; every word must appear, in any order.Arguments: `page`, `pageSize`, `searchTerm`
`associate`	`BusinessUnitAssociate`	An associate of the business unitArguments: `id`
`currentAssociate`	`BusinessUnitAssociate`	The associate the signed-in caller is within this business unit. Null when the caller is not an associate of the unit. Answering this by reading the associate list is unreliable as well as slow: that collection is paginated and cannot be filtered to the caller, so beyond the first page the caller finds no capabilities and every gated control disappears without an error.
`associates`	`BusinessUnitAssociateResult!`	Associates of the business unit. A search term narrows the list by email address, given name or family name; every word must appear, in any order.Arguments: `page`, `pageSize`, `searchTerm`
`availableRoles`	`[BusinessUnitRole!]!`	Available roles that can be assigned to customers in this business unit
`pendingInvitations`	`BusinessUnitInvitationResult!`	Invitations whose invitee has not yet set up their account, the most recent first. An invitation to someone who already had an account is accepted at once and is never pending. Empty where the engine adds associates without an invitation step.Arguments: `page`, `pageSize`
`shoppingList`	`ShoppingList`	A shopping list of the business unitArguments: `id`
`shoppingLists`	`ShoppingListResult`	Shopping lists of the business unitArguments: `page`, `pageSize`
`invoice`	`Invoice`	One invoice of this company, by idArguments: `id`
`invoices`	`InvoiceResult!`	Invoices billed to this company, newest first. Visible to whoever may see the company's orders: a standalone invoice belongs to no order, so whether it is the caller's own cannot be asked of it.Arguments: `page`, `pageSize`, `searchTerm`, `status`, `invoiceDateFrom`, `invoiceDateUntil`
`carts`	`CartResult!`	Every cart in this business unit the caller is allowed to see, which includes colleagues' carts where their role permits it, most recently touched first. Active carts only unless status asks for archived ones too.Arguments: `page`, `pageSize`, `status`
`order`B2B	`Order`	One order, by the number a buyer quotes or by its id. Give exactly one -- giving both, or neither, is an error rather than a silent preference. The id is what a payment provider hands back on its return URL, so it is the key a buyer arrives with after paying. The order number is the one they read off a confirmation.Arguments: `orderNumber`, `id`
`orders`B2B	`OrderResult`	This business unit's orders, newest first. Cancelled ones are left out unless asked for by name: a cancelled order is not something that was bought, and reopening an unpaid order for editing cancels it, so the list would otherwise fill with twins. A search term matches the order number, the purchase-order reference, or the SKU of a line item. All three are matched in full rather than as a prefix: they are codes read off a confirmation, a purchase order or a packing slip and pasted in, not phrases to type part of. Product names are deliberately not searched. Free text over what an order contains needs a separate search index, and an order history that quietly stops finding anything the day that index is rebuilt is worse than one that never claimed to.Arguments: `page`, `pageSize`, `searchTerm`, `status`, `createdFrom`, `createdUntil`, `placedByMe`
`orderApprovals`	`OrderApprovalResult!`	Approval queue for the business unit, optionally filtered by statusArguments: `status`, `page`, `pageSize`
`orderApprovalRule`	`OrderApprovalRule`	One approval rule of the business unit, or null when it has none by that idArguments: `id`
`orderApprovalRules`	`OrderApprovalRuleResult!`	Approval rules configured for the business unit, optionally by statusArguments: `status`, `page`, `pageSize`
`quoteRequest`	`QuoteRequest`	Get a specific quote request by its IDArguments: `id`
`quoteRequests`	`QuoteRequestResult`	Get a paginated list of quote requestsArguments: `page`, `pageSize`
`quote`	`Quote`	Get a specific quote by its IDArguments: `id`
`quotes`	`QuoteResult`	Get a paginated list of quotesArguments: `page`, `pageSize`, `sort`, `status`
`returns`	`ReturnResult!`	Returns for the unit's orders the associate can see, newest firstArguments: `page`, `pageSize`, `status`
`return`	`Return`	One of the unit's returns the associate can see; null otherwiseArguments: `id`

`BusinessUnitAddressCreateResponse`

Field	Type	Description
`businessUnit`	`BusinessUnit`	Updated business unit information with new address
`businessUnitErrors`	`[BusinessUnitAddressCreateError!]`	Error details if address creation failed

`BusinessUnitAddressDeleteResponse`

Field	Type	Description
`businessUnit`	`BusinessUnit`	Updated business unit information after address deletion
`businessUnitErrors`	`[BusinessUnitAddressDeleteError!]`	Error details if address deletion failed

`BusinessUnitAddressUpdateResponse`

Field	Type	Description
`businessUnit`	`BusinessUnit`	Updated business unit information with modified address
`businessUnitErrors`	`[BusinessUnitAddressUpdateError!]`	Error details if address update failed

`BusinessUnitAssociate`

Customer associated with a business unit, including their assigned roles

Field	Type	Description
`id`	`ID!`	Unique identifier for the associate
`createdAt`	`DateTime!`	Date and time when the associate was created
`email`	`EmailAddress!`	Email address of the associate
`salutation`	`SalutationType`	Optional salutation for the associate
`givenName`	`String`	First name of the associate
`familyName`	`String`	Last name of the associate
`roles`	`[BusinessUnitRole!]!`	Roles assigned to the customer in the business unit
`status`	`BusinessUnitAssociateStatusType!`	Whether the associate is active or deactivated within this business unit
`isCurrentUser`	`Boolean!`	Whether this associate is the currently signed-in user

`BusinessUnitAssociateInviteResponse`

Field	Type	Description
`businessUnit`	`BusinessUnit`	Updated business unit information with new associate
`businessUnitErrors`	`[BusinessUnitAssociateInviteError!]`	Error details if associate invitation failed

`BusinessUnitAssociateRemoveResponse`

Field	Type	Description
`businessUnit`	`BusinessUnit`	Updated business unit information after associate removal
`businessUnitErrors`	`[BusinessUnitAssociateRemoveError!]`	Error details if associate removal failed

`BusinessUnitAssociateResult`

Paginated result containing business unit associates

Field	Type	Description
`items`	`[BusinessUnitAssociate!]!`	Associates in the current page
`pagination`	`Pagination!`	Where this page sits within the full result set

`BusinessUnitAssociateRolesUpdateResponse`

Field	Type	Description
`businessUnit`	`BusinessUnit`	Updated business unit information with modified associate roles
`businessUnitErrors`	`[BusinessUnitAssociateRolesUpdateError!]`	Error details if associate roles update failed

`BusinessUnitAssociateStatusUpdateResponse`

Field	Type	Description
`businessUnit`	`BusinessUnit`	Updated business unit information with the modified associate status
`businessUnitErrors`	`[BusinessUnitAssociateStatusUpdateError!]`	Error details if the associate status update failed

`BusinessUnitCredit`

A company's credit on account, in the currency of its limit. The back office keeps the figures; they are read as it last recorded them.

Field	Type	Description
`limit`	`Money!`	The most the company may owe on account
`outstanding`	`Money!`	What the company owes on account now
`available`	`Money!`	The limit minus what is outstanding, below zero once the limit is exceeded

`BusinessUnitDefaultAddressUpdateResponse`

Field	Type	Description
`businessUnit`	`BusinessUnit`	Updated business unit information with the modified default addresses
`businessUnitErrors`	`[BusinessUnitDefaultAddressUpdateError!]`	Error details if the default address update failed

`BusinessUnitError`

Implements Error

A change to a business unit the caller may not make.

Field	Type	Description
`message`	`String!`
`code`	`BusinessUnitErrorCodeType!`

`BusinessUnitInvitation`

An invitation to someone who has yet to set up their account. They are an associate already, holding the roles the invitation gave them, so they are also in the unit's associates; they have not yet set a password.

Field	Type	Description
`associate`	`BusinessUnitAssociate!`	The invited associate: their email address and the roles they were given
`invitedAt`	`DateTime!`	When the invitation was sent
`invitedBy`	`Customer`	Who sent it. Null where that customer no longer exists.

`BusinessUnitInvitationResult`

Paginated result containing a business unit's pending invitations

Field	Type	Description
`items`	`[BusinessUnitInvitation!]!`	Invitations in the current page, the most recent first
`pagination`	`Pagination!`	Where this page sits within the full result set

`BusinessUnitPaymentTerms`

When a company pays for what it buys on account.

Field	Type	Description
`days`	`Int!`	Days between an invoice and the date its payment is due, such as 30.

`BusinessUnitRole`

Roles that can be assigned to customers in a business unit

Field	Type	Description
`id`	`ID!`	Unique identifier for the role
`name`	`String!`	Name of the role
`capabilities`	`[BusinessUnitCapabilityType!]!`	Normalized framework capabilities granted by this role

Enums

`BusinessUnitAssociateStatusType`

Whether an associate is active or has been deactivated within a unit

`ACTIVE`	The associate can act within the business unit
`INACTIVE`	The associate has been deactivated and cannot act within the unit

`BusinessUnitCapabilityType`

Normalized, engine-agnostic capabilities a role grants within a business unit. The storefront's permission gating resolves against these rather than against a specific commerce engine's raw permission model.

`VIEW_MY_ORDERS`	View orders the associate placed themselves
`VIEW_OTHERS_ORDERS`	View orders placed by other associates in the unit
`VIEW_OTHERS_CARTS`	View carts belonging to other associates in the unit. There is no matching value for the associate's own carts: seeing your own work is not a restricted act, and view is granted separately only where seeing is itself a decision.
`MANAGE_MY_ORDERS`	Create and update the associate's own carts and orders
`MANAGE_OTHERS_ORDERS`	Create and update carts and orders belonging to other associates. Separate from managing your own: acting for a colleague is a different authority, and a role that has one need not have the other. Building a colleague's basket rides on this rather than earning a value of its own -- a basket you may not place is not a separation anyone asks for.
`MANAGE_USERS`	Manage the associates of the business unit
`MANAGE_COMPANY_DETAILS`	Change the business unit's own details: its name, its default and billing addresses, and the addresses already in its book, which colleagues may be shipping to. Adding an address is not among them: it rides on MANAGE_MY_ORDERS, since anyone who may check out may need to ship somewhere new.
`VIEW_INVOICES`	View invoices for orders the associate can see
`DECIDE_APPROVALS`	Decide an approval flow: release an order that is being held, or refuse it.
`MANAGE_APPROVAL_RULES`	Author the rules that decide which orders are held. Separate from deciding them: an associate may never approve their own order, and one who can rewrite the threshold reaches the same result by another route.
`REQUEST_QUOTES`	Ask the merchant for a quote on a basket, and withdraw that request
`CONVERT_QUOTES`	Turn a quote the merchant issued into an order. Separate from requesting one: an associate may be trusted to ask for a price without being trusted to commit the company to the answer. Converting is also the acceptance — there is no separate decision step to grant.
`REQUEST_RETURNS`	Request a return for orders the associate can see. Seeing the unit's returns follows from seeing its orders.

`BusinessUnitErrorCodeType`

Why a change to a business unit was refused.

PERMISSION_DENIED The caller's roles in the business unit do not allow this change.

Unions

Get started

Guides

Conventions

Reference

Architecture

Changelog