Skip to main content

About the Checkout and Accounts Configuration API

Plus

Checkout styling customizations are available only to Shopify Plus merchants.

The checkoutAndAccountsConfigurationUpdate mutation styles checkout, customer accounts, and sign-in through a single, unified API. This guide introduces the API's data structures, queries, and mutations, and maps them to their counterparts in the Checkout Branding API.

When to use which API

The Checkout Branding API (using checkoutBrandingUpsert) remains supported for checkout-only styling tied to a checkout profile. Use the Checkout and Accounts Configuration API when you want a single configuration to drive checkout, customer accounts, and sign-in.

Anchor to Data structuresData structures

The Checkout and Accounts Configuration API's branding object is structured around three pillars:

  • designTokens: Sets global brand values including a color palette (up to 20 hex colors), typography (primary and secondary font groups, base size and ratio), and corner radius variables (small, base, large pixel values). Equivalent to designSystem in the Checkout Branding API.

  • components: Styles shared UI elements that apply across all surfaces: buttons, text fields, selects, checkboxes, form controls, header, footer, main area, heading levels, merchandise thumbnails, dividers, favicon, and shared overrides (semantic colors, global corner radius, typography). Equivalent to customizations in the Checkout Branding API.

  • surfaces: A new concept with no equivalent in the Checkout Branding API. Provides surface-specific component overrides for three distinct surfaces:

    • Checkout: the richest surface, with header (including cart link, sticky positioning), footer, main, buyer journey breadcrumbs, express checkout, order summary, and content container.
    • Customer Accounts: header (with logo), footer, and main with section styling.
    • Sign-In: the most minimal surface, with header (logo and padding only) and main (with background image support and full color role control).

The following example shows the API structure:

Branding configuration structure

{
"configuration": {
"branding": {
"designTokens": {
"colors": {
"palette": { "color1": "#1A1A2E", "color2": "#0F3460" }
},
"cornerRadius": { "small": 3, "base": 5, "large": 10 },
"typography": {
"primary": { "shopifyFontGroup": { "baseFontHandle": "assistant_n4", "boldFontHandle": "assistant_n7" } },
"secondary": { "shopifyFontGroup": { "baseFontHandle": "playfair_display_n4", "boldFontHandle": "playfair_display_n7" } },
"size": { "base": 14, "ratio": 1.2 }
}
},
"components": {
"primaryButton": { "cornerRadius": "BASE" },
"header": { "alignment": "CENTER" },
"shared": {
"colors": { "accent": "#0F3460", "button": "#E94560" }
}
},
"surfaces": {
"checkout": {
"components": {
"header": { "position": "START", "divided": true },
"orderSummary": { "section": { "cornerRadius": "BASE" } }
}
},
"customerAccounts": {
"components": {
"header": { "alignment": "CENTER" }
}
},
"signIn": {
"components": {
"main": { "section": { "cornerRadius": "LARGE", "shadow": "BASE" } }
}
}
}
}
}
}

Anchor to Retrieving a configurationRetrieving a configuration

Instead of checkout profiles, the Checkout and Accounts Configuration API uses configuration IDs. Use the checkoutAndAccountsConfigurations query to retrieve available configurations:

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

GraphQL query

query {
checkoutAndAccountsConfigurations(first: 5) {
edges {
node {
id
name
branding {
designTokens {
colors { palette { color1 color2 } }
cornerRadius { small base large }
}
}
}
}
}
}

Anchor to Updating a configurationUpdating a configuration

Use the checkoutAndAccountsConfigurationUpdate mutation:

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

GraphQL mutation

mutation UpdateBranding($id: ID!, $configuration: CheckoutAndAccountsConfigurationInput!) {
checkoutAndAccountsConfigurationUpdate(id: $id, configuration: $configuration) {
checkoutAndAccountsConfiguration {
id
branding {
designTokens { colors { palette { color1 } } }
}
}
userErrors { field message code }
}
}

Query variables

{
"id": "gid://shopify/CheckoutAndAccountsConfiguration/123",
"configuration": {
"branding": {
"designTokens": {
"colors": { "palette": { "color1": "#1A1A2E" } }
}
}
}
}

Anchor to Mapping from the Checkout Branding APIMapping from the Checkout Branding API

Checkout Branding API (checkoutBrandingUpsert)Checkout and Accounts Configuration API (checkoutAndAccountsConfigurationUpdate)
checkoutProfileId parameterid parameter (configuration ID)
designSystem.colors.globalbranding.designTokens.colors.palette + branding.components.shared.colors
designSystem.colors.schemesbranding.surfaces.*.components.*.colors (per-surface color roles)
designSystem.typographybranding.designTokens.typography
designSystem.cornerRadiusbranding.designTokens.cornerRadius
customizations.primaryButtonbranding.components.primaryButton
customizations.headerbranding.components.header + branding.surfaces.checkout.components.header
customizations.footerbranding.components.footer + branding.surfaces.checkout.components.footer
customizations.mainbranding.surfaces.checkout.components.main
customizations.orderSummarybranding.surfaces.checkout.components.orderSummary
customizations.faviconbranding.components.favicon
customizations.controlbranding.components.control
N/Abranding.surfaces.customerAccounts (new)
N/Abranding.surfaces.signIn (new)

Anchor to Get startedGet started

Apply Checkout and Accounts Configuration styling with the following tutorials:

Customize typography

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

Add the favicon

Learn how to set the favicon through the Checkout and Accounts Configuration API.

Customize form controls

Learn how to customize form controls, checkboxes, and buttons across surfaces.

Update color settings

Learn how to design and apply a color palette and per-surface color roles.

Customize sections

Learn how to style sections per surface — checkout, customer accounts, and sign-in.

Was this page helpful?