Made in Builder

×

Developers

Product

Use Cases

Pricing

Developers

Resources

Company

Get StartedLogin

Product

Features

Integrations

Talk to an Expert

Pricing

Blog

Home

Resources

Blog

Forum

Github

Login

Signup

×

Visual CMS

Drag-and-drop visual editor and headless CMS for any tech stack

Theme Studio for Shopify

Build and optimize your Shopify-hosted storefront, no coding required

Resources

Blog

Get StartedLogin

E-commerce Custom Types

Each e-commerce plugin provides custom types that you can use to add functionality to the Visual Editor:

  • Request object types
  • Preview types
  • Handle types
  • List types

Request object types

A request object type field stores an object representing an asynchronous request for resource data from your e-commerce platform, similar to a JavaScript (JS) promise.

The object has three top-level properties:

  • options: an object with a single property, the name of which corresponds to the resource type and the value of which corresponds to the resource's ID. For example, options.product holds your product's ID.
  • data (optional): an object with a single property, the name of which corresponds to the resource type and the value of which corresponds to the resource's data. For example, data.product holds data fetched from your e-commerce platform about the product. data is only available when a content request is made with the noTraverse request option or query parameter set to false while using the JS SDK or content/GraphQL APIs, respectively.
  • request: an object with metadata about the asynchronous resource data request.

You can use request object types wherever you need to refer to a single resource by its ID, for example while setting up e-commerce resource-based content targeting or creating custom component inputs.

You can select a resource for the field using a searchable list, which at a minimum exposes the resource's ID through the request object's options property. Using that ID, you can fetch resource data from your e-commerce platform and expose it to your components through state and data bindings.

With the noTraverse request option set to false, you can also use request object types to fetch resource data without a separate request, saving you a roundtrip. Builder fetches the data from your e-commerce platform using the resource's ID for you, adding the response to the data property on the request object.

Request object type names, such as ShopifyProduct, have no suffix.

Preview types

A preview type is essentially a request object type with an additional side effect: adding a preview type field to your model will trigger a searchable list to appear when opening that model's content in the Visual Editor if the field is empty.

Once you select a resource from the list, the plugin automatically fetches it from your e-commerce platform and exposes its data in the model's editing URL through string templating.

You can use preview types to enable creators to preview content for specific resources while editing, for instance in a product detail page (PDP).

Preview type names end with the word Preview, such as ShopifyProductPreview.

Handle types

A handle type stores a reference to a resource in your e-commerce platform such as a product or a product collection. The reference is a string that corresponds to the resource's handle.

The handle is a human-readable, machine-parseable unique identifier assigned by a user or auto-generated by the e-commerce platform. A product called "Short sleeve t-shirt" may have the handle short-sleeve-t-shirt, for example.

You can use handle types for custom component input fields, which allows you to select a resource for the field from a searchable list. The handle for the selected resource is passed to your component as a prop with the same name as your field. The prop's value is a string or, if the field is empty, undefined.

Handle type names end with the word Handle, such as ShopifyProductHandle.

List types

A list type stores references to one or more resources in your e-commerce platform. Each reference is a string that corresponds to the resource's ID in your platform.

While handle types also store references to resources, the references stored by list types are primary IDs. For example, a product called "Short sleeve t-shirt" may have the handle short-sleeve-t-shirt and a randomized ID such as 9f870b34-7397-4dc0-b2e7-9d93cdcba0fe. You can call different e-commerce APIs to fetch resource data depending on whether your reference is a handle or a primary ID.

Similar to handle types, list types are used to provide a searchable list interface for custom component input fields. The IDs for the selected resources are passed to your component as a prop with the same name as your field. The prop's value is an array of zero or more strings.

List type names end with the word List, such as ShopifyProductList.

Next steps

For more information on using e-commerce plugins, check out the following articles:

Was this article helpful?