Getting started with advanced checkout branding
You’re ready to customize the look and feel of checkout. In this tutorial, you’ll use the GraphQL Admin API to customize various elements beyond the capabilities of the checkout editor and save changes to a draft or live checkout. You can preview draft checkouts in the checkout editor and production checkouts on the live site.
This tutorial is for a sample checkout, but you can use it as a basis for expanding into other available checkout branding and properties or property values, similar to the following variations:
What you'll learnAnchor link to section titled "What you'll learn"
In this tutorial, you’ll learn how to do the following tasks:
- Identify the two main structures within the checkout branding API object:
- Query the GraphQL Admin API for a list of your shop's checkout profile IDs.
- Apply design system changes which impact the entire experience design language.
- Apply customizations which impact components or a specific part of the UI.
RequirementsAnchor link to section titled "Requirements"
- The shop that you're modifying must be on a Shopify Plus plan.
- You've created a new development store with the checkout extensibility preview enabled.
- You've completed the GraphQL and REST Admin API getting started guide.
- Your app is using the unstable version of the Admin API.
Step 1: Explore the Anchor link to section titled "Step 1: Explore the designSystem and customizations objects"
Before diving in to the inner workings of the checkout branding API, let's first take a look at the organization of the API's data object in order to better understand its structure. The branding API is split into two main objects:
The following example JSON object represents the response of a successful GraphQL Admin API query for checkout branding properties. Notice the separate objects and their inner contents:
designSystemobject impacts the design language for the entire experience. Its values are set to establish your design system, which encompasses various design components such as spacing, color palette, typography, and other visual elements that are used throughout the branding process. The
designSystemobject represents the standardized design principles for the brand.
customizationsobject impacts specific parts of the UI, individual components, or groups of components. With some customizations, you can pull from design system values. Other customizations retrieve their values from a pre-defined array of tokens or a float range. These customizations can be made to adjust the interface to better align with a brand's identity or specific requirements.
Step 2: Query a checkout profileAnchor link to section titled "Step 2: Query a checkout profile"
Checkout branding properties apply to a checkout profile ID. This can be useful to test branding against a draft profile before publishing any changes.
checkoutProfilesquery to retrieve a list of available checkout profile IDs.
Make note of your corresponding ID from the list. You'll supply the ID in your checkout branding mutations in the following steps.
Step 3: Apply design system changesAnchor link to section titled "Step 3: Apply design system changes"
3A: Apply colors and fontsAnchor link to section titled "3A: Apply colors and fonts"
You can apply changes to the entire checkout experience and define the design language by updating specific property values.
In this step, you'll recreate the look of the following checkout:
checkoutBrandingUpsert mutation and replace
YOUR_CHECKOUT_PROFILE_ID_HERE with the profile ID of your preferred draft or live checkout.
The values of the colour palette indicate the corresponding hex to apply across the whole experience. You can adjust the values according to your needs.
The response returns a JSON data object containing all the
designSystem properties that are highlighted in the following mutation structure. If the response includes any messages under
userErrors, then review the errors, check that your mutation and
profileID are correct, and try the request again.
3B: Apply custom fonts (optional)Anchor link to section titled "3B: Apply custom fonts (optional)"
Custom fonts allow merchants to showcase their brand’s personality and style, and help to create a cohesive experience across the storefront and checkout.
In this optional step, you'll modify the secondary typography in the checkout:
RequirementsAnchor link to section titled "Requirements"
- The font must be in WOFF or WOFF2 file format
- The store must have a webfont license to legally use the font
Add a custom fontAnchor link to section titled "Add a custom font"
- Upload the custom font using one of the following methods:
- Using the Asset API resource
- Through the Files section of the Shopify admin.
- Retrieve the ID of the generic file using the files query:
- Update the branding mutation query with the typography data using the
YOUR_FILE_ID_HEREwith the ID of your uploaded font file.
Step 4: Make customization changesAnchor link to section titled "Step 4: Make customization changes"
After you've made changes to the design system, you can make custom changes. These changes apply to a certain part of the UI, such as a component, a group of components, or globally.
In this step, the heading typography settings, form control corners, button corners, and logo position are being modified to create a checkout similar to the following checkout:
In this step, you'll update the heading typography settings, form control corners, button corners, and logo position.
The following example shows how to use the
checkoutBrandingUpsert mutation to replicate the look of this checkout:
- Explore the GraphQL Admin API to learn more about customizing the branding of a checkout.