Skip to main content

Update color settings with Checkout and Accounts Configuration API

Plus

Checkout styling customizations are available only to Shopify Plus merchants.

This guide shows how to manage colors through the Checkout and Accounts Configuration API. Instead of color schemes, the API uses a flat color palette in branding.designTokens.colors and direct color role assignments at the component and per-surface level.

For an introduction to the API, see About the Checkout and Accounts Configuration API. For the equivalent guide using checkoutBrandingUpsert, see Update color settings.

Anchor to RequirementsRequirements

Anchor to Set the color paletteSet the color palette

The palette accepts up to 20 named colors in designTokens.colors.palette:

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

GraphQL mutation

mutation UpdateColors($id: ID!, $configuration: CheckoutAndAccountsConfigurationInput!) {
checkoutAndAccountsConfigurationUpdate(id: $id, configuration: $configuration) {
configuration {
branding {
designTokens {
colors { palette { color1 color2 color3 color4 } }
}
}
}
userErrors { field message code }
}
}

Query variables

{
"id": "gid://shopify/CheckoutAndAccountsConfiguration/YOUR_CONFIG_ID_HERE",
"configuration": {
"branding": {
"designTokens": {
"colors": {
"palette": {
"color1": "#F7FAF5",
"color2": "#44691E",
"color3": "#456920",
"color4": "#DCE9D3"
}
}
}
}
}
}

Anchor to Set shared semantic colorsSet shared semantic colors

Instead of global brand or accent colors, use components.shared.colors for semantic color roles:

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

GraphQL mutation

mutation UpdateSharedColors($id: ID!, $configuration: CheckoutAndAccountsConfigurationInput!) {
checkoutAndAccountsConfigurationUpdate(id: $id, configuration: $configuration) {
configuration {
branding {
components {
shared {
colors { accent button control critical info success warning decorative }
}
}
}
}
userErrors { field message code }
}
}

Query variables

{
"id": "gid://shopify/CheckoutAndAccountsConfiguration/YOUR_CONFIG_ID_HERE",
"configuration": {
"branding": {
"components": {
"shared": {
"colors": {
"accent": "#456920",
"button": "#456920",
"control": "#44691E",
"critical": "#D72C0D",
"info": "#2C6ECB",
"success": "#008060",
"warning": "#FFC453",
"decorative": "#44691E"
}
}
}
}
}
}

Anchor to Apply colors to specific surfacesApply colors to specific surfaces

Set colors directly on each surface's components (for example, the checkout header, main section, order summary, and footer):

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

GraphQL mutation

mutation UpdateCheckoutColors($id: ID!, $configuration: CheckoutAndAccountsConfigurationInput!) {
checkoutAndAccountsConfigurationUpdate(id: $id, configuration: $configuration) {
configuration {
branding {
surfaces {
checkout {
components {
header { colors { base { background text accent border icon decorative } } }
main { colors { base { background text } } }
orderSummary { colors { base { background text } } }
footer { colors { base { background text } } }
}
}
}
}
}
userErrors { field message code }
}
}

Query variables

{
"id": "gid://shopify/CheckoutAndAccountsConfiguration/YOUR_CONFIG_ID_HERE",
"configuration": {
"branding": {
"surfaces": {
"checkout": {
"components": {
"header": {
"colors": {
"base": {
"background": "#F7FAF5",
"text": "#44691E",
"accent": "#44691E",
"border": "#DCE9D3",
"icon": "#44691E",
"decorative": "#44691E"
}
}
},
"main": {
"colors": {
"base": { "background": "#F7FAF5", "text": "#44691E" }
}
},
"orderSummary": {
"colors": {
"base": { "background": "#F7FAF5", "text": "#44691E" }
}
},
"footer": {
"colors": {
"base": { "background": "#F7FAF5", "text": "#44691E" }
}
}
}
}
}
}
}
}

Anchor to Set colors on Customer Accounts and Sign-In surfacesSet colors on Customer Accounts and Sign-In surfaces

The API enables independent color customization for customer accounts and sign-in, capabilities not available with the Checkout Branding API:

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

GraphQL mutation

mutation UpdateAccountsAndSignInColors($id: ID!, $configuration: CheckoutAndAccountsConfigurationInput!) {
checkoutAndAccountsConfigurationUpdate(id: $id, configuration: $configuration) {
configuration {
branding {
surfaces {
customerAccounts {
components {
header { colors { base { background text } } }
main { colors { base { background text } } }
}
}
signIn {
components {
main {
colors {
base { background text accent }
primaryButton { background text }
}
}
}
}
}
}
}
userErrors { field message code }
}
}

Query variables

{
"id": "gid://shopify/CheckoutAndAccountsConfiguration/YOUR_CONFIG_ID_HERE",
"configuration": {
"branding": {
"surfaces": {
"customerAccounts": {
"components": {
"header": {
"colors": {
"base": { "background": "#FFFFFF", "text": "#1A1A2E" }
}
},
"main": {
"colors": {
"base": { "background": "#F8F8F8", "text": "#1A1A2E" }
}
}
}
},
"signIn": {
"components": {
"main": {
"colors": {
"base": { "background": "#1A1A2E", "text": "#FFFFFF", "accent": "#E94560" },
"primaryButton": {
"background": "#E94560",
"text": "#FFFFFF"
}
}
}
}
}
}
}
}
}

Anchor to Differences from the Checkout Branding APIDifferences from the Checkout Branding API

Checkout Branding APICheckout and Accounts Configuration API
designSystem.colors.global (brand, accent)branding.components.shared.colors (accent, button, control, etc.)
designSystem.colors.schemes (scheme1–3)branding.surfaces.*.components.*.colors (direct per-surface color roles)
Color schemes applied via customizations.*.colorSchemeColors set directly on each surface's components
Same colors across all surfacesIndependent colors per surface (checkout, customer accounts, sign-in)
designSystem.colors.schemes.scheme1.base.backgroundbranding.surfaces.checkout.components.main.colors.base.background
N/Abranding.designTokens.colors.palette — a flat palette of up to 20 hex colors

Anchor to Next stepsNext steps

  • Explore the GraphQL Admin API to learn more about customizing colors across checkout, customer accounts, and sign-in.
Was this page helpful?