One API.

By Filippo Conforti on May 14, 2024

When I started designing the Commerce Layer API, I wanted one API to expose all order management functions. This was instead of two separate APIs for order management and shopping carts. Truth be told, I wasn't entirely sure why. Most of the companies I was looking up to had some type of admin and delivery APIs. Contentful, for instance, had APIs for content management and content delivery. Shopify provided admin and storefront APIs. Basically, the leading companies were pretty much all following this approach. In spite of this, it didn't feel right for what I was building, and I opted to take a different route.

It has taken me some time to understand why I felt that way, but I'm glad I followed my intuition. Indeed, it does make sense to have two APIs for a headless CMS such as Contentful. The two-stack CMS approach allows them to optimize both parts of the architecture. Content management is a read/write process, which is handled by a few content editors. Content delivery is a read-only process, which means that many people read what editors publish. Rather, a platform like Shopify was born as a site builder with a monolithic frontend, and the storefront API was just added later to support headless setup.

It was a different commerce layer that I had in mind. Rather than a CMS or a site builder, it was a unified commerce API that would enable transactions to take place anywhere, no matter what the market, channel, or customer touchpoint was. This is why Massimo and I decided not to design shopping cart and order APIs. Instead, we designed just one single API that would make any transaction seamless in any distributed environment.

Pure omnichannel experiences don't care where the order is created or how it is placed. A customer can begin a cart online, then share it with a friend who completes the purchase. A customer can also ask support to build an order on their behalf, receive a link to the checkout and add their payment details before placing the order. The process can begin online and be completed in store, or vice versa. It can be created manually or programmatically, using a subscription model. It is possible to save the same order for later, edit it, place it, or return it online or in person. There is always the same stateless API. Same customer, same order.

Business and technology are probably more interconnected in ecommerce than anywhere else. Ecommerce is an area in which a developer's choice can have the greatest impact on business results. Consider the relationship between site speed and conversion rate, for instance. Or the flexibility a headless stack offers over a monolithic platform. Years later, I am proud of how our technical choice has benefited both our developers and customers. Often it is mentioned that unified commerce is the holy grail, and I think one unified API is a major step in that direction.

Enjoy the reading?

Subscribe to the newsletter and get a new article delivered to your inbox every week.