How to build a Custom Editor plugin for my ecommerce backend with

Integrating your e-commerce backend with 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, 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
# start from a preconfigured plugin code by copying its content to another folder
cp -r plugins/swell plugins/[my-backend]
npm install
  1. Delete content of src/plugin.tsx, so we replace it with the new backend operation, then start by
import { registerCommercePlugin } from '';

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',
  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
      getRequestObject: id => ({
        '@type': '',
        request: {
          // tell builder how to load this object
          url: `${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 new field types 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: plugin source code for a more concrete example.

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


I’m trying to get this working for our custom backend, but the components aren’t showing up in then editor.

I’ve edited the swell plugin to use our way of getting data, renamed everything that’s needed and added it as a plugin as described. When I open the editor, the mentioned components do not show up. I’ve enabled the Shopify components (as those are used in the demo GIF) for my space, but those always do a request to the Shopify API.
The custom fields do show up on the type selector for custom fields.

Where do I go from here? I can’t find a tutorial or documentation page that explains what to do after you connect your plugin to your space.

Hope someone can guide me to trough the next steps.

Hello @gijsbotje thanks for the question! When you say “components” you are trying to pull some sort of custom component from your backend into Builder through the plugin you wrote? Unfortunately that may not be supported with our current plugin tools.

Builder’s e-commerce plugins create custom field types corresponding to your external platform’s resources, which you can use when targeting content, previewing content, and using your content as a symbol inside of our Visual Editor.. They don’t necessarily allow you to register custom components.

We are actually in the middle of overhauling our plugin/integrations documentation, and I will be sure to link it here when it is done (hopefully sometime next week). Hopefully this, and our soon to be updated docs will help further clarify any confusion !

Hi @TimG thanks for the reply. In the OP it says Now you should see multiple content blocks for products. It also contains a GIF that displays how to add a collection block. I assumed it would show up like the Shopify blocks but nothing came up and using the Shopify blocks didn’t work either.
I’ve scoured almost all ecommerce plugins and the Shopify starter too and found what I needed to know. I also noticed that the GIF in the OP is being reused in every ecommerce plugins readme, which also led me to believe the plugins triggered those components.

Anyway, the Swell plugin is a good starting point, eventually I got there and can now select the products in the editor. Also found the components I needed to copy code from.

Looking forward to the updated documentation!

1 Like

Thanks so much for pointing that out, updated the wording to match the docs ( field types )

1 Like