Skip to main content

Update color settings

Plus

Checkout styling customizations are available only to Shopify Plus merchants.

This guide demonstrates how to design a color system that reflects your brand by using the GraphQL Admin API's checkout branding types and their associated fields.

You'll learn some sample customizations, but you can use what you've learned to make other color 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 RequirementsRequirements

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 color 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: Configure global colorsStep 2: Configure global colors

The GraphQL Admin API's CheckoutBrandingColorGlobalInput enables you to quickly update the global colors to match your brand.

In a subsequent step, you'll also learn how to make granular color changes.

The following code changes the global brand and accent colors to match a shop's visual identity:

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

GraphQL mutation

mutation ChangeGlobalColors($checkoutBrandingInput: CheckoutBrandingInput!, $checkoutProfileId: ID!) {
checkoutBrandingUpsert(checkoutBrandingInput: $checkoutBrandingInput, checkoutProfileId: $checkoutProfileId) {
checkoutBranding {
designSystem {
colors {
global {
brand
accent
}
}
}
}
userErrors {
field
message
}
}
}

Query variables

{
"checkoutProfileId": "gid://shopify/CheckoutProfile/YOUR_CHECKOUT_PROFILE_ID_HERE",
"checkoutBrandingInput": {
"designSystem": {
"colors": {
"global": {
"brand": "#456920",
"accent": "#456920"
}
}
}
}
}

JSON response

{
"data": {
"checkoutBrandingUpsert": {
"checkoutBranding": {
"designSystem": {
"colors": {
"global": {
"brand": "#456920",
"accent": "#456920"
}
}
}
},
"userErrors": []
}
},
"extensions": {
"cost": {
"requestedQueryCost": 13,
"actualQueryCost": 13
}
}
}
The brand and accent colors applied to the shop's checkout

Anchor to Step 3: Configure color schemesStep 3: Configure color schemes

Configuring color schemes gives you a lot of flexibility when the default colors specified in step 1 need to change for a particular context like drawing attention to different checkout sections, or emphasizing content in a particular location. You can apply color schemes to different parts of the UI in step 3.

Color schemes are made up of color groups, and all components utilize values specified within these groups. This means that all UI extensions also use these values and automatically inherit your colors.

Note

Some color groups have nested groups to configure state colors, such as a hover state of the primary button, or a selected state of the ChoiceList component.

Every color group has the same set of overridable values. Refer to an example.

Note

We automatically derive extra colors from these, for example, text subdued is generated from text.

The following code applies shades of green to scheme1 that match the store's visual identity. The code sets a light green background, text that matches the logo, darker border controls, a dark selected state and makes the primary button hover state more prominent.

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

GraphQL mutation

mutation ChangeColorScheme1($checkoutBrandingInput: CheckoutBrandingInput!, $checkoutProfileId: ID!) {
checkoutBrandingUpsert(checkoutBrandingInput: $checkoutBrandingInput, checkoutProfileId: $checkoutProfileId) {
checkoutBranding {
designSystem {
colors {
schemes {
scheme1 {
base {
background
text
}
control {
background
border
selected {
background
border
}
}
primaryButton {
hover {
background
}
}
}
}
}
}
}
userErrors {
field
message
}
}
}

Query variables

{
"checkoutProfileId": "gid://shopify/CheckoutProfile/YOUR_CHECKOUT_PROFILE_ID_HERE",
"checkoutBrandingInput": {
"designSystem": {
"colors": {
"schemes": {
"scheme1": {
"base": {
"background": "#F7FAF5",
"text": "#44691E"
},
"control": {
"background": "#F7FAF5",
"border": "#70815F",
"selected": {
"background": "#456920",
"border": "#44691E"
}
},
"primaryButton": {
"hover": {
"background": "#395719"
}
}
}
}
}
}
}
}

JSON response

{
"data": {
"checkoutBrandingUpsert": {
"checkoutBranding": {
"designSystem": {
"colors": {
"schemes": {
"scheme1": {
"base": {
"background": "#f7faf5",
"text": "#44691e"
},
"control": {
"background": "#f7faf5",
"border": "#70815f",
"selected": {
"background": "#456920",
"border": "#44691e"
}
},
"primaryButton": {
"hover": {
"background": "#395719"
}
}
}
}
}
}
},
"userErrors": []
}
},
"extensions": {
"cost": {
"requestedQueryCost": 19,
"actualQueryCost": 19
}
}
}
Screenshot that shows the application of color schemes

Anchor to Step 4: Apply color schemesStep 4: Apply color schemes

Configuring color schemes to apply to different parts of the UI overrides the default color schemes.

Scheme applications are customizable. The following code changes the default scheme structure so that scheme1 can be applied to the order summary.

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

GraphQL mutation

mutation ChangeOrderSummaryScheme($checkoutBrandingInput: CheckoutBrandingInput!, $checkoutProfileId: ID!) {
checkoutBrandingUpsert(checkoutBrandingInput: $checkoutBrandingInput, checkoutProfileId: $checkoutProfileId) {
checkoutBranding {
customizations {
orderSummary {
colorScheme
}
}
}
userErrors {
field
message
}
}
}

Query variables

{
"checkoutProfileId": "gid://shopify/CheckoutProfile/YOUR_CHECKOUT_PROFILE_ID_HERE",
"checkoutBrandingInput": {
"customizations": {
"orderSummary": {
"colorScheme": "COLOR_SCHEME1"
}
}
}
}

JSON response

{
"data": {
"checkoutBrandingUpsert": {
"checkoutBranding": {
"customizations": {
"orderSummary": {
"colorScheme": "COLOR_SCHEME1"
}
}
},
"userErrors": []
}
},
"extensions": {
"cost": {
"requestedQueryCost": 12,
"actualQueryCost": 12
}
}
}
Scheme 1 applied to the order summary page, which now matches the store's visual identity

Anchor to Next stepsNext steps

Was this page helpful?