Getting started with advanced checkout branding

In this tutorial, you’ll learn how to do the following tasks:

• Identify the two main structures within the checkout branding API object: designSystem and customizations.
• 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.

• 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.

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: designSystem and customizations.

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:

• The designSystem object 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 designSystem object represents the standardized design principles for the brand.

• The customizations object 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.

Checkout branding properties apply to a checkout profile ID. This can be useful to test branding against a draft profile before publishing any changes.

1. Use the checkoutProfiles query to retrieve a list of available checkout profile IDs.

2. Make note of your corresponding ID from the list. You'll supply the ID in your checkout branding mutations in the following steps.

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:

Use the 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.

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:

• The font must be in WOFF or WOFF2 file format
• The store must have a webfont license to legally use the font

1. Upload the custom font using one of the following methods:
   • Using the Asset API resource
   • Through the Files section of the Shopify admin.
2. Retrieve the ID of the generic file using the files query:

1. Update the branding mutation query with the typography data using the CheckoutBrandingTypographyInput object. Replace YOUR_FILE_ID_HERE with the ID of your uploaded font file.

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.