Skip to main content

About checkout styling

Plus

Checkout styling customizations are available only to Shopify Plus merchants.

Anchor to How it worksHow it works

The GraphQL Admin API includes types and their associated fields for applying styling to checkout, checkout queue, checkout UI extensions, and customer account pages.

Styles are applied across these surfaces.

You can save styling changes to a draft checkout, which you can preview in the checkout editor, or to a production checkout on a live site. Review the following sections to familiarize yourself with API data structures and the role of checkout profiles in styling.

Anchor to Data structuresData structures

The branding API consists of the following objects:

  • designSystem: Sets the design language for the entire experience. Its values are set to establish your design system, which encompasses design components such as spacing, colors, typography, and other visual elements that are used throughout the branding process. The designSystem object represents the standardized design principles for the brand. designSystem provides foundational tokens that are consumed in the customizations object.

  • customizations: Styles 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.

    The following example JSON object shows the separate objects and their inner contents:

Advanced checkout branding object

{
"data": {
"checkoutBrandingUpsert": {
"checkoutBranding": {
"designSystem": {
"colors": {
"global": {
"accent": "#d10088"
},
"schemes": {
"scheme1": {
"base": {
"background": "#fffafd",
"text": "#d10088"
},
"primaryButton": {
"background": "#ff9cdd",
"text": "#2e001e",
"accent": "#1773b0"
}
},
"scheme2": {
"base": {
"background": "#fff5fb",
"text": "#2e001e"
}
}
}
},
"typography": {
"size": {
"base": 16,
"ratio": 1.4
},
"primary": {
"base": {
"sources": null,
"weight": 400
}
},
"secondary": {
"base": {
"sources": "local('Oswald Regular'), local('Oswald-Regular'), url(https://fonts.shopifycdn.com/oswald/oswald_n4.a5ee385bde39969d807f7f1297bf51d73fbf3c1e.woff2?valid_until=MTY3NTEyMDcxMg&hmac=a4977887b7fe80efb9c9aa29c88d4abfd7fe0a627e24ca55ea23cb2bf8474c92) format('woff2'),url(https://fonts.shopifycdn.com/oswald/oswald_n4.8f3e284746fbc2d29e34993609c51fdc432b0b24.woff?valid_until=MTY3NTEyMDcxMg&hmac=2f43504b8a6cb1c6eac0037d16ff032aab1063a05d704f7b391ee84273936643) format('woff')",
"weight": 400
}
}
}
},
"customizations": {
"global": {
"cornerRadius": "NONE",
"typography": {
"letterCase": "NONE"
}
},
"header": {
"alignment": "CENTER",
"position": "START"
},
"headingLevel1": {
"typography": {
"weight": "BOLD",
"font": "SECONDARY",
"letterCase": "UPPER",
"size": "LARGE"
}
},
"headingLevel2": {
"typography": {
"weight": "BOLD",
"font": "SECONDARY",
"letterCase": "UPPER"
}
},
"primaryButton": {
"cornerRadius": "LARGE",
"typography": {
"letterCase": "UPPER",
"weight": "BASE",
"font": "SECONDARY",
"size": "MEDIUM"
},
"blockPadding": "TIGHT",
"inlinePadding": "BASE"
}
}
},
"userErrors": []
}
}
}

Anchor to Checkout profileCheckout profile

Checkout branding properties apply to a checkout profile ID. Profiles are useful to test branding against a draft profile before publishing any changes.

The following example uses the checkoutProfiles query to retrieve a list of available checkout profile IDs. The is_published parameter highlights which checkout profile applies to your store's current live checkout. You supply the id in checkout branding mutations to customize your checkout's branding properties.

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"
}
}
]
}
}
}

Anchor to Resetting stylesResetting styles

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.

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 LimitationsLimitations

  • You can't currently customize styling for individual pages.

    Styles are applied across checkout, checkout queue, checkout UI extensions, and customer account pages.

  • SVG is not a supported image type for styling checkout.

Anchor to Developer tools and resourcesDeveloper tools and resources

Checkout UI extensions API reference

Consult the API reference for checkout UI targets and their respective types.

Components for checkout UI extensions

Learn about the components that are available in checkout UI extensions.

Checkout extension configuration

Learn about the properties that you can configure in your checkout UI extension.

GraphQL Admin API branding resources

Consult the API reference for checkout branding and view examples of common requests.

Anchor to Get startedGet started

Follow these tutorials and learn how to apply custom styles.

Customize typography

Learn how to apply different font types and other typographical customizations to checkout.

Add the favicon

Learn how to add the favicon to display at checkout.

Customize form controls

Learn how to use the GraphQL Admin API to customize form controls such as borders and label positions, button styles, and corner radii.

Update color settings

Learn how to design and apply a colour system using the GraphQL Admin API.

Customize sections

Learn how to style the sections on checkout pages with the GraphQL Admin API's checkout branding types.

Was this page helpful?