ai.commercestudio.b2b.account

Draft, version 2026-10-19. Extends dev.ucp.shopping.checkout and dev.ucp.shopping.cart (UCP 2026-08-25). Schema: https://b2b.commercestudio.ai/ucp/schemas/account.json.

In B2B, the buyer isn't a person shopping for themselves. They're a user of a company account. The company decides where goods can ship, and who can place orders and up to what amount.

This extension tells the agent which account it's buying for, so it can confirm the right company and ship-to with the buyer. It also lets the agent explain, before checkout, whether the order will need approval.

Principles

The account comes from identity linking. The agent never names a company or user. The business resolves them from the signed-in user (UCP identity linking), so an agent can't buy on an account it wasn't granted.
Read-only, except the ship-to. The agent may choose among the account's ship-to locations. Company, role and limits are the business's to set.
Agents that don't negotiate the extension never see it. Their carts and checkouts are standard UCP, at the same prices.

Response field: `b2b_account`

Present on every cart and checkout when the extension is negotiated.

Field	Meaning
`company`	`{ id, name }`: the company account the buyer belongs to
`buyer`	`{ id, name, role, can_purchase }`: the signed-in company user
`buyer.role`	The user's company role, e.g. `admin`, `senior_buyer`, `junior_buyer`, `purchasing_manager`. Platform-defined custom roles appear by name
`buyer.can_purchase`	`false` means this user can't place orders. Complete Checkout submits the order for approval, and an approver places it (see `ai.commercestudio.b2b.approval`)
`ship_to`	`{ id, name }`: the selected ship-to location. On a cart, it's the account's default
`ship_tos[]`	`{ id, name }`: every ship-to location the buyer may use
`spend_limit`	Per-order spend limit for this buyer, in minor units. Absent means no personal limit. Orders above it need approval

Addresses are deliberately not exposed: name is what people use ("Main Clubhouse", "Pro Shop"). The order carries the full address in fulfillment.expectations[].destination.

Choosing the ship-to

On Create Checkout and Update Checkout, the agent may send:

{ "b2b_account": { "ship_to": { "id": "<one of ship_tos[].id>" } } }

Shipping is re-quoted for the chosen ship-to, and totals change to match.
An id that isn't in ship_tos is refused with invalid_ship_to (error, recoverable, path $.b2b_account.ship_to.id). The checkout keeps its previous ship-to and becomes incomplete.

Messages

Code	Type	When
`invalid_ship_to`	error (recoverable)	The requested ship-to isn't one of the buyer's
`approval_required`	info	Before Complete Checkout: this order will need approval, because the buyer can't purchase or the total is over their `spend_limit` (see the approval extension)

Callisto on BigCommerce B2B Edition