Salesforce Commerce API Plugin

Quickly connect your SalesForce B2C Commerce API to your Builder content.

Prerequisites

To get the most out of this document, make sure:

Setup Salesforce Commerce API Access: visit the Salesforce guide, Setup API Access, to make sure you already have your Shopper Login and API Access Service (SLAS) client setup.

Installation

On any Builder Space:

Go to Plugins.
On the Salesforce B2C Commerce API integration, toggle the switch to the On position.
The browser should refresh the page; however, you might have to do it manually. Once refreshed, the toggle is set to on and you should get a prompt to configure the plugin. Click Configure button.
In the modal that opens, you'll be prompted to enter the Client ID and password, library name, API path, preview library name (optional), and the preview path (optional).
Click the Connect button.

The screenshot below shows the SFCC plugin modal:

Salesforce configuration modal with a form where you put in your salesforce info.

Tip: If you're using Salesforce's Composable Storefront kit, refer to the configuration in your config/default.js file.

Custom targeting in Builder.io allow users to target content by a multitude of attributes, and in this plugin you'll be able to add specific content from SFCC products, for this you'll need first to set the target attributes on the host site, either by setting the userAttributes if you're rendering client side:

With custom targeting in Builder, you can direct content according to a wide array of attributes. With the Salesforce Commerce API plugin, you can seamlessly integrate SFCC product details into your targeting criteria. Here’s how to set up:

Client-side rendering: To fetch content specifically for a product on its detail page, utilize the builder.get function with userAttributes set to the product ID:

// example for fetching content specific for a product in a product details page
const productFooterContent = await builder.get('product-footer', {
  userAttributes: {
    product: product.productId,
  }
})

Server-side Rendering or API Requests: Pass the targeting attributes as a query parameter to your content API call or include them in your GraphQL query, as demonstrated in frameworks like Gatsby or Next.js.

For more details, visit the Content API documentation.

Custom components and input types

When you install the plugin, you can use specific SFCC data types as inputs for your custom components. These types enhance the interactivity and specificity of your components within the Visual Editor:

SFCommerceProduct: this input type allows the selection of an individual product, enabling the component to access and display product-specific information.
SFCommerceCategory: select a specific category to tailor content or retrieve an array of products within that category directly in your component.
SFCommerceProductsList: enables the selection of multiple products, ideal for creating product grids or list displays within your component.
SFCommerceCategoriesList: allows multiple category selections, useful for broader content targeting and display.

Example: Custom Component Configuration

Consider a custom component named ProductBox which integrates an SFCommerceProduct. Here’s how you might register it within Builder.io:

import React from 'react';
import { Builder } from '@builder.io/react';
import ProductBox from './ProductBox'; // Your custom component

Builder.registerComponent(ProductBox, {
  name: 'ProductBox',
  image: 'https://unpkg.com/css.gg@2.0.0/icons/svg/box.svg',
  inputs: [
    {
      name: 'productRef',
      friendlyName: 'Product',
      type: 'SFCommerceProduct',
      required: true
    }
  ]
});

For more details, visit Builder's SFCC Composable Storefront example on GitHub.

Fetch content and references

When fetching content from Builder, the includeRefs=true option fetches detailed data linked to specific references, such as an SFCommerceProduct, facilitating server-side rendering:

const page = await builder.get('page', {
  url: '...',
  options: {
    includeRefs: true
  }
});

Ensure this option is also enabled during the editing phase to automatically resolve data for your components:

<BuilderComponent model="page" options={{ includeRefs: true}} content={page} />

For more information on the available options, visit the Content API documentation.

What's next

With the SFCC plugin installed, you can create custom models, components, and symbols using any of the SFCC field types and edit as needed.

Was this article helpful?