Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Get started with the Storefront API.
The Storefront API delivers headless capabilities built directly into Umbraco Commerce. It allows you to retrieve and manage orders and other store-related entities in a JSON format. It lets you connect with them in different channels, using your preferred technology stack. This feature preserves the friendly editing experience of Umbraco, while also ensuring performant cart management facilities in a headless fashion. With its different extension points, you can tailor this API to fit a broad range of requirements.
As the Storefront API works alongside the Content Delivery API you must first have the Content Delivery API setup and enabled.
When the Content Delivery API is enabled, you will need to explicitly opt-in to the Storefront API. Below you will find the steps you need to take in order to configure it for your Umbraco project.
Open your project's Program.cs file.
Register the API dependencies by adding .AddStorefrontApi() inside a .AddUmbracoCommerce() call:
Open your project's appsettings.json.
Insert the StorefrontApi configuration section under Umbraco:Commerce.
Add the Enabled key and set its value to true:
In order to work with the Storefront API many of the endpoints require authorization. The authorization is implemented by means of an API Key that must be passed in the header of these requests. The API Key is defined as an additional app setting and can be any value you decide:
Before exploring the API endpoints detailed below, there are a few concepts to keep in mind.
The Storefront API is broken down into a number of endpoints grouped by resource type. Select a resource type below to review the available endpoints.
You can access a Swagger document for the Storefront API at {yourdomain}/umbraco/swagger, selecting Umbraco Commerce Storefront API from the definitions dropdown in the top right. From here you can see a full list of supported APIs, the parameters they accept and the expected payloads and responses.
As Umbraco Commerce uses content nodes as products, the Storefront API comes with some replacement value converters that automatically extend the default value converter functionality to return Storefront entities when accessed through the Content Delivery API. You don't need to do anything to enable these.
Store Picker - Returns a Store "Reference" by default, or a complete Store response object if the store picker property is being expanded.
Store Entity Picker - Returns an entity "Reference" by default, or a complete entity response object if the store entity picker property is being expanded.
Price - Returns a price for the product based on session information passed through in headers. See the "Session" concept detailed above.
Stock - Returns the stock level of the given product.
Variants - See notes on the variants value converter below.
To help with common scenarios when working with variants, the Variants value converter will return a series of data items used when building a relevant UI.
attributes will contain a list of "in use" attributes which means there is at least one variant content item that makes use of that attribute. These should be used to build the attribute options UI.
items returns a list of variant items. By default, this will return the attribute combinations, and whether it is the default combination but its content value will be empty. The content value can be populated by expanding the variants property through the Delivery API, however, it's important to know this could return a lot of data and be intensive. Instead, it is preferred to return the non-expanded value and use the variantContentUrl to fetch individual content items as they are requested. The items collection should also be used to check if a combination exists as whilst the root level attributes collection contains all in-use attributes, it doesn't mean every possible combination of those attributes exists so you can use the items collection to validate a combination.
variantContentUrl as the URL to a specialized Delivery API route that can return a single variant item content based on a passed-in attribute combination.
The Order endpoints are where you will manage your carts/orders and perform cart management functionality. Some examples are adding items to the cart, or setting up billing and shipping details.
The checkout endpoints provide ways of performing a checkout process against an Order. The Storefront API supports two ways of checking out an order, one using hosted checkout pages, and a more advanced option for inline payment processing.
With the hosted checkout flow it is required that before redirecting to the payment gateway a checkout token should be generated. This token is passed to the pay endpoint to ensure that only the given order can be processed in response to the checkout request. The pay endpoint should be launched in a WebView/iframe with this token which will redirect to the given Orders payment gateway for payment capture. To determine the outcome of the payment developers should monitor the WebView/iframes URL. They will be redirected to the same pay endpoint URL with either a /completed, /canceled or /errored suffix.
With the inline checkout flow, it is left to the implementing developer to perform payment capture. Before a capture can begin, the order should be initialized using the initialize endpoint which prepares the Order for capture. The initialize endpoint will return the settings of the Orders selected payment method, along with details of expected metadata needed by the payment provider. Developers can use this data to perform an inline capture and call the confirm endpoint when the capture is successful, passing back any metadata captured.
The Product API endpoints allow fetching essential product related data such as pricing and stock levels.
The Customer API endpoints allow fetching all orders associated with a customer.
The Storefront API is broken down into a number endpoints of grouped by resource type. Select a resource type below to review the available endpoints.
The Shipping Method API endpoints allow fetching supported shipping methods from a store.
The Country API endpoints allow fetching supported countries and their allowed currencies, payment methods and shipping methods from a store.
The Payment Method API endpoints allow fetching supported payment methods from a store.
The Store API endpoints allow fetching supported store details.