Integrating Umbraco CMS with Shopify

Written by: Adrian Cojocariu

Our excitement for new integrations continues 🔧🤩 This time, we've integrated Umbraco CMS with Shopify!

With this Shopify package, we provide a product(s) picker and a property value converter that uses a strongly typed model for rendering, for products within a Shopify/ShopifyPlus store or through different custom apps from associates in the partners' program. Dive right in 👇

Background

An Umbraco initiative that started in the second half of 2021 and took the DXP team through various different tech ecosystems, presents today another installment by showcasing an integration with Shopify.

You can follow up with past integrations through the following blog posts:

If you want to see it in action, you can reference and use the integration in your own project, as the project is available both on NuGet and on Our Umbraco.

The full source code is open-sourced on GitHub, and you are more than welcome to submit PRs or respond to issues.

Shopify Overview

Shopify is an e-commerce platform, a subscription-based software, that you can use to build your store both online and offline. It provides the foundation to run an e-commerce business and offers all the tools you need to manage store-related activities. It is basically a facilitator working to ease the process of selling products over the web, and a comprehensive e-commerce platform that enables you to grow a business in many ways, with a lot of flexibility and control.

Shopify offers full storefront customization to help you deliver exactly what your client is looking for. More than 1 000 000 merchants around the world are powered by Shopify and many of them are looking for help building and customizing their stores.

Umbraco and Shopify working together are the perfect pair for commerce-related businesses, helping them reach their full potential.

Your store is hosted on a cloud network, instead of a server, making the downtime of your site very low and allowing your business to run with ease.

The Shopify ecosystem consists of two main areas:

Shopify - built for starters, entrepreneurs, or small and medium businesses.
Shopify Plus - built for enterprises, high-volume merchants, and large businesses.

In addition to the regular features of Shopify, Shopify Plus is an enterprise e-commerce platform for larger businesses or businesses looking to scale. It offers advanced reporting features, higher priority customer support, the capacity to handle higher order volumes, and more.

On top of each business area resides a specific Shopify Partner Program, consisting of a diverse group of designers, developers, marketers, and affiliates who use the Shopify platform to build e-commerce websites, themes, and apps.

With our new Umbraco package, we reach out to all of them by providing support and integration whether you are a small or enterprise business owner, or a custom apps developer.

Shopify Admin API

Our integration targets the Admin API of Shopify and specifically querying the products from your shop.

A couple of key aspects to take into account:

We are interacting with the REST Admin API (GraphQL is also supported),
Their API is versioned - a new API version is released every 3 months at the beginning of the quarter. Version names are date-based to be meaningful and semantically unambiguous (our use cases are using version 2022-01).
Apps must use access scopes during installations against stores (in our case we are using the read_products access scope).

You can check the Shopify Developers Platform for more information.

After the authentication setup is successfully set, we can draw our attention to the single endpoint we are going to use for requesting the store resources, as Admin REST API endpoints are organized by resource type.

In general, all Admin REST API endpoints follow this pattern:

https://{store_name}.myshopify.com/admin/api/{api_version}/{resource}.json

As a result, a specific set of app settings need to be added in `Web.config` or `appsettings.json` - as detailed in the Setup and Configuration section below, and use the products resource type.

A sample request endpoint to retrieve the list of products would look like this: https://my-umbraco.myshopify.com/admin/api/2022-01/products.json

Authentication

All REST Admin API queries require a valid Shopify access token. Public and custom apps created in the Partner Dashboard generate tokens using OAuth, and custom apps made in the Shopify admin are authenticated in the Shopify admin.

A Shopify app extends the existing functionality of Shopify. Umbraco has an application registered within the Shopify marketplace and it is used for handling OAuth accessibility.

The token is sent with the X-Shopify-Access-Token header on all API requests.

Shopify access tokens have two access modes: offline and online. Offline ones are meant for long-term access to a store and expire only when an app is uninstalled, while online ones are linked to an individual user on a store, and have a lifespan equal to the lifespan of the user's web session. Our integration uses the offline access mode.

Different types of authentication and authorization are explained here and through the diagram below:

OAuth Proxy for Umbraco Integrations

Proxy Interface is a communication protocol common across integrations that support OAuth, and more details can be reviewed in the past blog post covering HubSpot Forms integration.

In addition, to support OAuth requests to Shopify given the fact that their API is using the shop’s name in the endpoint URL, we need to send to the proxy an additional header named service_address_shop-replace having as value the shop’s name.

The proxy interface will extract the shop’s name and use it for OAuth requests against Shopify.

Multi-targeting

With the release of Umbraco 9 on .NET 5 and to support package developers migrating their own packages to the new version, the Umbraco team has released a step-by-step guide showcasing the migration of the UI Examples package to version 9.

The Shopify package follows those guidelines and provides the necessary support for Umbraco 9 also.

Setup and Configuration

As highlighted above, the integration supports two types of authentication, using:

Access Token
OAuth

In order to validate the authentication workflow, the following protocols are reviewed:

1. Check the settings file (Web.config or appsettings.json) for an Access Token record. The token will be added to all requests made to the Shopify Admin API and used to authenticate access.

2. If no API key is present, the OAuth flow will be used using the parameters specified in the SettingsService.

Data Type & Content Description

Once the package is installed, either through NuGet or from the backoffice, you can go on and register a new data type based on the Shopify Product Picker :

Immediately after the property editor is selected, the authentication configuration will be validated, and a message displayed to the user in the Settings area. If no access token is found, the Settings area will be slightly different, offering the options to authorize against Shopify.

You can also set a min/max number of products you are able to select from the content editor overlay.

Connect

button will load up the Shopify OAuth authorization window where you will be asked for login credentials and pick an account attached to your profile. After the authorization is completed successfully, a notification gets prompted and the access token is saved into the database of the Umbraco web application.

Revoke action will remove the access token from the database and the authorization process will need to be restarted.

After the data type is registered, you can start referencing it across your document type as it will be available in the Pickers section.

Then in your content management area, depending on whether or not you have a valid configuration, you will be prompted with a warning or you will be able to access the product of your store.

The property value converter will generate a strongly typed model which alongside the HTML helper will help you easily render the form on the front-end.

https://gist.github.com/acoumb/7329ee5f9ecf7ca6a49fe4707b3804e1

You just need to ensure that your template has a reference to the following using statement:

@using Umbraco.Cms.Integrations.Commerce.Shopify.Helpers;

And then use the available HTML extension:

https://gist.github.com/acoumb/2ef84234a2695906e8e39295cf43187e

Conclusions

On a final note, the integration is open-sourced and the current release targets Umbraco versions 8 and 9.

A minimum set of requirements for the CMS would be:

Umbraco CMS version 8.5.4 and
Umbraco CMS version 9.0.1

Feel free to review the custom integrations we are working on in this repository: https://github.com/umbraco/Umbraco.Cms.Integrations, as well as the proxy web application https://github.com/umbraco/Umbraco.Forms.Integrations. At any point, you can clone those repos on your local development machine and work with them as you please.