Shopify Checkout Branding API vs. Checkout and Accounts Configuration: Which Should You Use?

Type: Decision Guide / Complete Guide · Stage: Optimize / Scale · Topic: Checkout / Customer Accounts / Branding API

Why old checkout branding guides are incomplete

Most pre-2026 tutorials start with checkoutBrandingUpsert, a checkout profile ID, designSystem, and customizations. That model is still useful for checkout-only work. It becomes awkward when a team wants the same logo, color tokens, buttons, form fields, and typography on checkout, customer accounts, and sign-in.

Shopify’s May 13, 2026 announcement introduced the unified configuration model for Plus merchants. The modern object has three parts: branding.designTokens for shared values, branding.components for shared components, and branding.surfaces for checkout, customer account, or sign-in overrides.

Decide which configuration you actually need

Do not promise this API to non-Plus merchants. Shopify documents checkout styling API customizations as Plus-only.

Read the existing configuration before writing

Use GraphQL Admin API version 2026-10 or another supported version that exposes the unified API. Query available configuration IDs instead of copying a checkout profile ID into a new mutation:

query CheckoutBrandingConfigurations {
  checkoutAndAccountsConfigurations(first: 10) {
    nodes {
      id
      name
      branding {
        designTokens {
          colors { palette { color1 color2 } }
          cornerRadius { small base large }
        }
      }
    }
  }
}

Identify the intended configuration, whether it is active or a test configuration in your release process, and record its existing settings. Do not assume a configuration GID equals the old checkout profile GID. Before writing, read the full fields you intend to change and understand how your update merges with or replaces nested values.

Apply a small, controlled branding change

This is the documented mutation shape. The example updates a shared color token; replace the ID with the actual configuration returned by your query:

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

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

For a real store, choose color tokens that exist in the design system and preview the result across all three surfaces. Shopify also supports component-level settings and surface-specific overrides, such as a different account header alignment. Keep global and local overrides distinct so a shared palette change does not unexpectedly affect sign-in or order status.

Plan the migration instead of doing a blind field rename

1. Export or record the old checkout branding values, current active configuration, and any market-specific variants.
2. Map old designSystem values to new designTokens and old customizations to components.
3. Decide which values are truly shared and which belong under a surfaces override.
4. Test with a non-active configuration or controlled release path before touching live checkout.
5. Check checkout, account sign-in, order history, and any custom UI extensions. Extension placement and content are separate from branding.
6. Document the active configuration ID, market coverage, rollback values, and who owns future updates.

Watch the Checkout Blocks editor deadline

Shopify’s Help Center says the Checkout Blocks branding editor is deprecated and scheduled for removal on December 31, 2026. If a team’s only documented process is Apps → Checkout Blocks → Branding editor, update the operational runbook before that date. Existing saved branding does not automatically vanish when the editor goes away, but staff need a supported way to maintain it afterward.

For teams using the Shopify admin’s native checkout and accounts editor, verify the current UI path in the store rather than assuming an old Checkout Blocks screenshot still matches.

Sources and further reading

Documentation checked October 23, 2026.