> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Interacting with the Hosted Portal

Plan: B2B Developer

Lesson 4 of 25 · 15 min

## Introduction

In any front-end environment where the Buyer Portal is being loaded, the global `b2b` object exposes an API that can be used to interact with the Buyer Portal app and its data.

This library of JavaScript global objects allows you to interact with the Buyer Portal in various ways from outside the React app itself, giving you the flexibility to use your own client-side code to perform tasks like opening a specific Buyer Portal page, adding a product to the current draft quote, or get information about the currently logged-in user.

## Customization with the JavaScript API

The global JavaScript utilities make it possible to pursue a strategy for storefront customization without having to fork the Buyer Portal application code. This strategy is viable if your customization requirements are relatively simple and involve interacting with the B2B entities on typical storefront pages. Examples might include:

* Displaying B2B data on standard storefront pages (for example, a product detail page).
* Opening a Buyer Portal page from user actions on other pages.
* Adding a product configuration to the current draft quote based on a custom action.

The global utilities don't expose access to the Buyer Portal's own component structure, so it is not a viable choice for altering the UI of the Buyer Portal itself.

When building storefront customizations that interact with the Buyer Portal, the question arises: **Where should your custom JavaScript live?**

While it might be a natural choice to integrate your B2B-dependent code into the rest of your storefront theme, this presents a challenge in Stencil: Loading the Buyer Portal is not supported in a local dev environment using the Stencil CLI. This means JS that interacts with the Buyer Portal cannot be directly tested in the Stencil dev environment.

Instead, a good practice is to adopt the same strategy the Buyer Portal itself uses: **Inject your B2B-dependent code into the storefront using external scripts.** Following this model, development works the same way as with a forked Buyer Portal (as we'll see later): Run your custom JS application in its own local dev environment, and inject it into a sandbox storefront.

```mermaid
flowchart TB
    subgraph Client["Client (browser)"]
        BP["Buyer Portal"]
        Custom["Custom JS app"]
    end

    ScriptBP["External script<br />(Buyer Portal bundle)"]
    ScriptCustom["External script<br />(Custom app bundle)"]

    ScriptBP -.->|"injects"| BP
    ScriptCustom -.->|"injects"| Custom

    Custom -->|"Client-side calls<br />via window.b2b"| BP
```

This is the strategy we'll be using in the lab exercises for this section.

> **Info**
>
> **In Catalyst**
>
> You have more flexibility for your strategy with Buyer Portal dependent JavaScript in the available Catalyst integration. Due to Catalyst being a fully decoupled storefront application, the Buyer Portal will load in any environment, including a local development environment. You might choose to access the global Buyer Portal utilities directly in your Catalyst components or via separate app as described.

## *b2b.utils* Example

The Buyer Portal's JavaScript API is available as the `window.b2b.utils` object. (You must make sure the Buyer Portal has been initialized and the `b2b` object is available before invoking it!)

In a storefront with the Buyer Portal loaded, use `window.b2b.utils` in the console of your browser dev tools to inspect the available utilities.

As an initial example, the `openPage` function can be used to navigate to a specific Buyer Portal page or even close the Buyer Portal interface.

**Example Code:**

```js showLineNumbers={false}
window.b2b.utils.openPage('INVOICE');
```

The above will open the Invoice page of the Buyer Portal.

The entire Buyer Portal interface can be closed, returning the user to the page matching the current URL, with the following:

```js showLineNumbers={false}
window.b2b.utils.openPage('CLOSE');
```

See the [`HeadlessRoutes` constant](https://github.com/bigcommerce/b2b-buyer-portal/blob/main/apps/storefront/src/constants/index.ts#L26-L44) in the Buyer Portal source code for the full list of valid keys that can be passed to `openPage`.

## Resources

* [`HeadlessRoutes` constant](https://github.com/bigcommerce/b2b-buyer-portal/blob/main/apps/storefront/src/constants/index.ts#L26-L44)