Overview of Customize Options for commercetools

Introduction

commercetools is a dynamically extensible, cloud-native commerce solution. It allows retailers to sculpt a solution that fits their unique needs today, and is flexible to support their evolving business strategy tomorrow.

This post will:

Describe the various ways you can customize and extend functionality on the commercetools platform;
Provide a flowchart to help you decide which technique is best for your use case;
Share tutorial links to help you get started with each customization option.

Customizations versus Extensions

Before we get started, it’s important to understand the difference between customizations and extensions in the context of commercetools.

Customizations are achieved by leveraging features built into commercetools to enhance its functionality and customize it based on your unique needs. You can leverage commercetools’ Custom Fields and Custom Objects to perform this level of customization and we cover both in this post.

Extensions are achieved by integrating solutions that run externally from the commercetools platform. Extension solutions can come in many forms: custom microservices you build yourself, commercial solutions you’ve licensed, open source projects you want to leverage, and, of course, commercetools Marketplace solutions. I briefly touch on the Marketplace in this post but all sorts of extensions are possible because of the API-based design of commercetools: it allows for a rich ecosystem of loosely coupled solutions to co-exist and interoperate.

Finally there are options that blend the two approaches. I will call these Hybrid Extensions and the two techniques covered in this post are API Extensions and Subscriptions. In these cases, you can customize built-in commercetools features to be aware of and interoperate with extensions that run on systems outside the platform.

Customization Options

Let’s explore two customization options: Custom Fields and Custom Objects. Both of these options leverage features built into the commercetools platform and do not require you to create or use external services.

Custom Fields

Custom Fields allow you to add data to an existing commercetools resource.

For instance, it's pretty common for retailers to want to customize the attributes they maintain about their customers; for instance, gender, age, shoe size, etc. If the retailer has not integrated a customer experience (CX) platform or similar solution, commercetools offers Custom Fields as a powerful way to expand customer attributes to suit specific needs.

The list of commercetools resources that can be extended with Custom Fields is broad. It’s possible to augment the data model for Categories, Customers, Carts, Orders, Line Items, Shopping Lists, Reviews, and many more. See the complete list at Customizable Resources.

Before you can use a custom field on a resource, first you will need to define a new Type. This Type will extend the data model on that resource. Each resource you create in commercetools can use the default values or specify one Type with the fields desired.

Bottom line, you can leverage custom fields to enhance an existing commercetools resource -- like customer, order or shopping-list -- to add data that is unique to you.

For an example use case and detailed tutorial covering custom fields, see Customize commercetools using Custom Fields.

Custom Objects

Custom Objects allow you to create a new resource that you would like to store within commercetools and integrate with other aspects of the system.

Custom Objects allow you to persist data that does not fit the standard data model. This frees your application completely from any third-party persistence solution and means that all your data stays in one place. They are grouped into containers, which can be used like namespaces.

– Custom Objects, Composable Commerce Documentation, commercetools

For instance, you may have an entity that is specific to your business domain and does not correspond to an existing commercetools resource. In this case, you can define the entity within commercetools using a custom object.

You can also use Custom Objects in combination with Custom Fields. For example, you could extend the customer resource with a custom field that references a complex data type stored in a custom object.

Bottom line, Custom Objects provide a lot of power. In fact they’re so powerful that it’s tempting to build complex solutions leveraging the feature! However, we advise some caution because in more difficult use cases, it’s possible to introduce performance problems. Complex issues that require validation, richer data structures and additional business rules typically push you toward a more tailored solution using techniques like custom microservices . If you’re in doubt, contact FTG and we can help you find the best path.

For an example use case and tutorial covering custom objects in detail, see Customize commercetools using Custom Objects.

Extension Options

Let’s discuss two extension options next: the commercetools Integration Marketplace and Custom Services. Both of these options allow you to leverage solutions that run outside the commercetools platform. These solutions often do not require any configuration or customization of commercetools. Instead, they leverage commercetools’ rich set of APIs to allow for loosely coupled interoperability.

The commercetools Integration Marketplace

The commercetools Integration Marketplace is a library of supported third-party integrations and extensions that work with the platform. A wide variety of solutions exist that cover complex domains like front ends, machine learning, order management, promotions, search, and many more. There are also marketplace tools that can optimize an implementation in areas like release management, price optimization, localization, etc.

The Integration Marketplace makes it easy to discover solutions that can help you with detailed descriptions of each offering and links to their respective vendors and relevant demos. Check it out! If you go with any of these vendor solutions, you can be confident they work with commercetools and will allow you to use off-the-shelf features from commercetools with minimal or zero configuration of commercetools’ platform.

In addition to the commercetools Integration Marketplace, you should take a look at the MACH Alliance. The MACH Alliance presents and advocates for an open and best-of-breed enterprise technology ecosystem based on four principles that are: Microservices based, API-first, Cloud-native SaaS and Headless. The member companies have all adopted a point of view that is similar to and compatible with the strategic underpinnings of the commercetools platform.

Custom Services

If you have a complex use case and the Integration Marketplace lacks a solution that fits, you should consider extending commercetools with a Custom Service. The techniques and best practices for writing Custom Services is outside the scope of this paper but there are many commercetools partners, including FTG, who can help you get started.

Once you have a custom service implemented, it's possible to integrate it with commercetools in several ways. The commercetools platform provides integration hooks via API Extensions and Subscriptions which we will cover in the next section. You also have the option to integrate your service without using these hooks and instead leverage the standard commercetools API to compose a solution. API Composition is one pattern to follow for this type of integration. Again, there are many partners who can help you compose solutions by leveraging the power of the commercetools API.

Hybrid Extension Options

Next, let’s review two hybrid extension options: API Extensions and Subscriptions. Both of these approaches leverage hooks built into commercetools that allow external systems to participate in API call resolution and/or respond to events that occur on the platform. Hybrid extensions therefore require configuration on commercetools and a corresponding external solution.

API Extensions

API Extensions allow you to modify the response of an API call to customize commercetools behavior.

The commercetools Composable Commerce APIs provide default data structures and default behavior that is useful for many customers. However, each Project has its unique requirements. Similar to data structures that can be customized with Custom Types and Product Types, additional behavior can be added. For behavior that needs to be executed before the API call succeeds, API Extensions can be used.

– API Extensions, Composable Commerce Documentation, commercetools

You may have unique business rules that must be taken into account for cart validation, cart discounts, shipping cost calculations, etc. API Extensions provide a mechanism for these business rules to be applied within the context of a commercetools API’s execution. When commercetools receives an API call for an endpoint you’ve extended, it first performs standard commercetools behaviors on the resource and then calls your code for further business rule processing. Once it gets your updates back, the result is persisted.

To take advantage of this technique, you can expose your business logic via a restful interface and configure commercetools to use it. Alternatively you can configure commercetools to call a serverless function directly. This removes the need for an HTTPS endpoint. In this scenario the function simply returns the response.

You can make runtime changes on the fly - this is powerful stuff! As you might expect, this power comes with some risk: the commercetools API is now dependent on you. If your code fails, the entire API call fails. If your code is slow, the API call will be slow. There are guardrails in place for the latter as you can set a timeoutInMs when you configure the extension. If you need help to mitigate these risks, contact FTG.

For an example use case and detailed tutorial covering API Extensions, see Customize commercetools using API Extensions.

Subscriptions

Subscriptions allow you to trigger custom asynchronous background processing in response to an event on the commercetools platform.

Subscriptions allow you to be notified of new messages or changes via a Message Queue of your choice. Subscriptions are used to trigger an asynchronous background process in response to an event on commercetools Composable Commerce. Common use cases include sending an order confirmation email, charging a credit card after a delivery has been made, or synchronizing customer accounts to a Customer Relationship Management (CRM) system.

– Subscriptions, Composable Commerce Documentation, commercetools

Subscriptions have a lot of the same power as API Extensions but they do not suffer from the same runtime risks. Because Subscriptions execute asynchronously based on events emitted from the platform, they allow your custom solutions to be loosely coupled to commercetools. This greatly reduces the risk of your code impacting commercetools API execution and performance.

commercetools differentiates between messages and changes. A single subscription can listen to both depending on the resource. Changes are straight-forward: events are fired whenever the subscribed resource type is created, updated or deleted. Messages are more specific:

A Message represents a change or an action performed on a resource, for example an Order or a Product.

– Messages, Composable Commerce Documentation, commercetools

There are many use cases where the asynchronous processing of an event is the right approach; for instance, sending order status emails in response to order events. In this use case, commercetools will fire events you can listen for as the order moves from Open to Confirmed and finally to either Complete or Cancelled.

For an example use case and detailed tutorial covering Subscriptions, see Customize commercetools using Subscriptions.

Extensibility Decision Flow Chart

Remember that customizations are not always the best option to take and that extensions can be a better fit in many cases. For a reminder of the differences, refer to section Customizations versus Extensions above. Here is a high level general rule of thumb when choosing between the two:

Choose to extend when your use case involves the implementation of complex or detailed rules specific to your business; especially when those rules apply to resources undefined by commercetools. Choose to customize when you want to address less complex business rules while augmenting an existing commercetools resource.

Given the many customization and extension options available, it may be difficult to know where to start. The following decision flow chart may help you decide which option is most appropriate for any use case:

Customizing commercetools Decision Flowchart

Next Steps

If you’d like to learn more about commercetools, check out the commercetools Documentation. It’s a great resource for learning about the platform and it’s full of tutorials and examples.