Skip to main content

Typography customization

Unique typefaces and other typography customizations enable merchants to showcase their brand's personality and style, and help to create a cohesive experience across the storefront and checkout.

This guide explains how to modify checkout typography using the GraphQL Admin API's checkout branding types and their associated fields. You'll define and use typography tokens within the design system for various elements, and style other elements directly.

You'll learn some sample customizations, but you can use what you've learned to make other typography customizations.

Tip

You can reset styles to their defaults by writing parent fields to null with the GraphQL Admin API. Refer to examples of resetting some and all values to the defaults.

Anchor to What you'll learnWhat you'll learn

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

  • Retrieve a list of your store's checkout profile IDs.
  • Update the checkout design system typography's base and ratio.
  • Apply a Shopify font to checkout's text and buttons.
  • Upload a custom font and apply it to checkout headings.
  • Customize buttons with a font that's distinct from the text.
  • Customize checkout's level one headings with case, weight, and size.

Anchor to RequirementsRequirements

  • Custom fonts must be in either Web Open Font Format (WOFF) or WOFF2.
  • To use licensed fonts legally, stores must have a webfont license.

Anchor to Step 1: Retrieve the store's published checkout profile IDStep 1: Retrieve the store's published checkout profile ID

Checkout styling properties apply to a checkout profile ID. In this step, you'll retrieve the checkout profile to which you'll apply typography changes.

  1. Query checkoutProfiles to retrieve a list of checkout profile IDs.

    The is_published parameter indicates which checkout profile is currently applied to your store's live checkout.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

query checkoutProfiles {
checkoutProfiles(first: 1, query: "is_published:true") {
edges {
node {
id
name
}
}
}
}

JSON response

{
"data": {
"checkoutProfiles": {
"edges": [
{
"node": {
"id": "gid://shopify/CheckoutProfile/1",
"name": "Default checkout profile"
}
}
]
}
}
}
  1. Make note of your corresponding ID from the list. You'll supply the ID in subsequent mutations.

Anchor to Step 2: Update the base size and ratio for the design systemStep 2: Update the base size and ratio for the design system

Note

Modifying the base font size and ratio proportionally adjusts associated spacing values, such as margins and padding. This ensures that relative size and space are preserved.

In this step, you'll use the checkoutBrandingUpsert mutation to update the design system's base size. You'll also update the scale ratio that's used to define all font sizes, such as what represents SMALL and LARGE:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation checkoutBrandingUpsert($checkoutBrandingInput: CheckoutBrandingInput!, $checkoutProfileId: ID!) {
checkoutBrandingUpsert(checkoutBrandingInput: $checkoutBrandingInput, checkoutProfileId: $checkoutProfileId) {
checkoutBranding {
designSystem {
typography {
size {
base
ratio
}
}
}
}
userErrors {
field
message
}
}
}

Query variables

{
"checkoutProfileId": "gid://shopify/CheckoutProfile/YOUR_CHECKOUT_PROFILE_ID_HERE",
"checkoutBrandingInput": {
"designSystem": {
"typography": {
"size": {
"base": 16.0,
"ratio": 1.4
}
}
}
}
}

JSON response

{
"data": {
"checkoutBrandingUpsert": {
"checkoutBranding": {
"designSystem": {
"typography": {
"size": {
"base": 16,
"ratio": 1.4
}
}
}
},
"userErrors": []
}
}
}

Anchor to Step 3: Apply a Shopify font to primary surfacesStep 3: Apply a Shopify font to primary surfaces

Primary surfaces include text and buttons.

Set the base font for primary surfaces with the checkoutBrandingUpsert mutation. You'll use a selection from the Shopify font library:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation checkoutBrandingUpsert($checkoutBrandingInput: CheckoutBrandingInput!, $checkoutProfileId: ID!) {
checkoutBrandingUpsert(checkoutBrandingInput: $checkoutBrandingInput, checkoutProfileId: $checkoutProfileId) {
checkoutBranding {
designSystem {
typography {
primary {
base {
sources
}
}
}
}
}
userErrors {
field
message
}
}
}

Query variables

{
"checkoutProfileId": "gid://shopify/CheckoutProfile/YOUR_CHECKOUT_PROFILE_ID_HERE",
"checkoutBrandingInput": {
"designSystem": {
"typography": {
"primary": {
"shopifyFontGroup": {
"name": "Assistant"
}
}
}
}
}
}

JSON response

{
"data": {
"checkoutBrandingUpsert": {
"checkoutBranding": {
"designSystem": {
"typography": {
"primary": {
"base": {
"sources": "local('Assistant Regular'), local('Assistant-Regular'), url(https://fonts.shopifycdn.com/assistant/assistant_n4.bcd3d09dcb631dec5544b8fb7b154ff234a44630.woff2?valid_until=MTY5OTM4MjI4Mw&hmac=407320ad74949088a8cbb72b20ec57fb0db385f085d671613b87fa52d7b77e65) format('woff2'),url(https://fonts.shopifycdn.com/assistant/assistant_n4.a2d012304becc2a26f1ded1acc136fcab85c9afd.woff?valid_until=MTY5OTM4MjI4Mw&hmac=f25fd27b446cd50eee14c14a67253f2d4deedaee34eb21ed6569da87118c5335) format('woff')"
}
}
}
}
},
"userErrors": []
}
}
}

Anchor to Step 4: Apply a custom font to secondary surfacesStep 4: Apply a custom font to secondary surfaces

Secondary surfaces include headings.

In this step, you'll upload a custom font and set it as the base font for headings:

  1. Upload the custom font using one of the following methods:
  2. Retrieve the ID of the generic file using the files query. The following is an example:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

Query font files

query queryFiles {
files(first: 10, query: "media_type:GenericFile") {
edges {
node {
... on GenericFile {
id
url
fileStatus
}
}
}
}
}

JSON response

{
"data": {
"files": {
"edges": [
{
"node": {
"id": "gid://shopify/GenericFile/1",
"url": "https://cdn.shopify.com/s/files/1/0000/0001/files/font-file.woff2?v=1682440653",
"fileStatus": "READY"
}
}
]
}
}
}
  1. Update the checkoutBrandingUpsert mutation with the typography data using the CheckoutBrandingTypographyInput input object.

Replace YOUR_FILE_ID_HERE with the ID of your uploaded font file.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation checkoutBrandingUpsert($checkoutBrandingInput: CheckoutBrandingInput!, $checkoutProfileId: ID!) {
checkoutBrandingUpsert(checkoutBrandingInput: $checkoutBrandingInput, checkoutProfileId: $checkoutProfileId) {
checkoutBranding {
designSystem {
typography {
secondary {
base {
sources
weight
}
bold {
sources
weight
}
name
}
}
}
}
userErrors {
code
field
message
}
}
}

Query variables

{
"checkoutProfileId": "gid://shopify/CheckoutProfile/YOUR_CHECKOUT_PROFILE_ID_HERE",
"checkoutBrandingInput": {
"designSystem": {
"typography": {
"secondary": {
"customFontGroup": {
"base": {
"genericFileId": "gid://shopify/GenericFile/YOUR_FILE_ID_HERE",
"weight": 100
},
"bold": {
"genericFileId": "gid://shopify/GenericFile/YOUR_FILE_ID_HERE",
"weight": 500
}
}
}
}
}
}
}

JSON response

{
"data": {
"checkoutBrandingUpsert": {
"checkoutBranding": {
"designSystem": {
"typography": {
"secondary": {
"base": {
"sources": "local('font-name'), url(https://cdn.shopify.com/s/files/1/0000/0001/files/font-file.woff2?v=1681408640) format('woff2')",
"weight": 100
},
"bold": {
"sources": "local('font-name'), url(https://cdn.shopify.com/s/files/1/0000/0001/files/font-file.woff2?v=1681408636) format('woff2')",
"weight": 500
},
"name": "font-name"
}
}
}
},
"userErrors": []
}
}
}
Tip

Fonts are a separate resource that need to be downloaded by the browser before any text is rendered, which impacts the checkout's overall performance. To optimize the checkout for performance, consider using a system font or a font from the Shopify font library rather than a custom font. To avoid long font load times impacting the checkout experience, use the loadingStrategy property to set how a font face is displayed based on whether and when it's downloaded and ready to use. To learn more, refer to the MDN documentation of the font-display descriptor.

The checkout page headings styled in a custom font

Anchor to Step 5: Style buttons with the secondary fontStep 5: Style buttons with the secondary font

Now you'll update the primary button typography to match what you set for secondary surfaces, using the checkoutBrandingUpsert mutation's customizations object:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation checkoutBrandingUpsert($checkoutBrandingInput: CheckoutBrandingInput!, $checkoutProfileId: ID!) {
checkoutBrandingUpsert(checkoutBrandingInput: $checkoutBrandingInput, checkoutProfileId: $checkoutProfileId) {
checkoutBranding {
customizations {
primaryButton {
typography {
font
}
}
}
}
userErrors {
field
message
}
}
}

Query variables

{
"checkoutProfileId": "gid://shopify/CheckoutProfile/YOUR_CHECKOUT_PROFILE_ID_HERE",
"checkoutBrandingInput": {
"customizations": {
"primaryButton": {
"typography": {
"font": "SECONDARY"
}
}
}
}
}

JSON response

{
"data": {
"checkoutBrandingUpsert": {
"checkoutBranding": {
"customizations": {
"primaryButton": {
"typography": {
"font": "SECONDARY"
}
}
}
},
"userErrors": []
}
}
}
The checkout page buttons using the same font as the headings

Anchor to Step 6: Style level one headingsStep 6: Style level one headings

Now you'll use the checkoutBrandingUpsert mutation's customizations object to style the level one heading typography.

The following example sets the font to large, relative to the base size and ratio, in uppercase and bold:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation checkoutBrandingUpsert($checkoutBrandingInput: CheckoutBrandingInput!, $checkoutProfileId: ID!) {
checkoutBrandingUpsert(checkoutBrandingInput: $checkoutBrandingInput, checkoutProfileId: $checkoutProfileId) {
checkoutBranding {
customizations {
headingLevel1 {
typography {
size
letterCase
weight
}
}
}
}
userErrors {
field
message
}
}
}

Query variables

{
"checkoutProfileId": "gid://shopify/CheckoutProfile/YOUR_CHECKOUT_PROFILE_ID_HERE",
"checkoutBrandingInput": {
"customizations": {
"headingLevel1": {
"typography": {
"size": "LARGE",
"letterCase": "UPPER",
"weight": "BOLD"
}
}
}
}
}

JSON response

{
"data": {
"checkoutBrandingUpsert": {
"checkoutBranding": {
"customizations": {
"headingLevel1": {
"typography": {
"size": "LARGE",
"letterCase": "UPPER",
"weight": "BOLD"
}
}
}
},
"userErrors": []
}
}
}
The checkout page with the level one heading font styled in a larger size, in uppercase and bold

Anchor to Next stepsNext steps

  • Explore the GraphQL Admin API to learn more about customizing checkout's typography.
Was this page helpful?