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
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.productholds 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.productholds data fetched from your e-commerce platform about the product.
datais only available when a content request is made with the
noTraverserequest option or query parameter set to
falsewhile 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.
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.
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
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,
Handle type names end with the word
Handle, such as
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
For more information on using e-commerce plugins, check out the following articles: