Home App Docs Blog Github

How to build a plugin for my custom ecommerce backend with Builder.io

Integrating your e-commerce backend with Builder.io makes working with your product content and data so much easier, and unlocks use cases like:

  • Symbols or Custom components that can accept a resource identifier, giving the content creator a way to search and choose a specific resource. One example could be a custom component that takes a product collection as an input and renders all its products in a grid.

  • Targeting content by a resource, for example, an announcement bar where its content only targets visitors who have a specific product in their cart, or are identified by a specific persona.

The most straightforward way to integrate your backend is using a @builder.io/commerce-plugin-tools, and here are some steps to build your own custom backend plugin:

  1. clone Builder repository and then navigate to the plugin example folder here:
git clone https://github.com/BuilderIO/builder.git
# start from a preconfigured plugin code by copying its content to another folder
cp -r plugins/swell plugins/[my-backend]
npm install @builder.io/commerce-plugin-tools
  1. Delete content of src/plugin.tsx, so we replace it with the new backend operation, then start by
import { registerCommercePlugin } from '@builder.io/commerce-plugin-tools';

const pluginConfig = {
  // id should match the name in package.json
  id: `@foobar/plugin-builder`,
  // will be used to prefix generated types
  name: 'FooBar',
  // a list of input definition that you might need to communicate with custom backend API ( optional )
  settings: [
      type: 'text',
      name: 'storeApiKey',
      helperText: 'you can get your store Api Key from your account at https://foobar.io/account',
  ctaText: 'Connect your FooBar backend',

registerCommercePlugin(pluginConfig, (settings) => {
  const storeApiKey = settings.get('storeApiKey');
  const fooBarService = new FooBarService(storeApiKey);
  // return a mapping between each resource and it's API functions.
  return {
    // for example to add product types
    product: {
      findById: id => fooBarService.findProductById(id),
      search: text => fooBarService.searchProducts(text),
     // should return BuilderRequest interface
     // https://github.com/BuilderIO/builder/blob/master/plugins/shopify/src/interfaces/builder-request.ts
      getRequestObject: id => ({
        '@type': '@builder.io/core:Request',
        request: {
          // tell builder how to load this object
          url: `https://foobarservice.com/products/${id}.json`,
        options: {
          product: id,

Now that we connected our API, we can check to see if it’s working correctly by running locally

npm install
npm run start

Start a server at http://localhost:1268

Go to the Builder plugin settings and add your local plugin https://localhost:1268/plugin.system.js?pluginId=@foobar/plugin-builder`

Now you should see multiple content blocks for products, such as:

  • A single product picker with search
  • A product list picker with search
  • A custom field: product preview, that allows you to set the specific model editing url to be a computed value of the product in preview: for example ${space.siteUrl}/product/${previewProduct.handle} and allow the content editor to test their templates on multiple products.


Once you’re done testing your new integration, submit a pull request to Builder with the new code, we’ll help review it, and publish it to npm. Or, if you’d like it to be a private plugin, talk to us, and we can support private plugins as part of an enterprise plan.

See more:

Swell.is plugin source code for a more concrete example.

Extensibility docs for more ways on how Builder can be extended.