---
title: Update color settings with Checkout and Accounts Configuration API
description: >-
  Learn how to design a color palette and apply per-surface color roles using
  the Checkout and Accounts Configuration API.
source_url:
  html: >-
    https://shopify.dev/docs/apps/build/checkout/styling/checkout-and-accounts-configuration/update-color-settings
  md: >-
    https://shopify.dev/docs/apps/build/checkout/styling/checkout-and-accounts-configuration/update-color-settings.md
api_name: checkout-ui-extensions
---

# Update color settings with Checkout and Accounts Configuration API

**Plus:**

Checkout styling customizations are available only to [Shopify Plus](https://www.shopify.com/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`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/CheckoutAndAccountsConfigurationBrandingDesignTokensColorsInput) 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](https://shopify.dev/docs/apps/build/checkout/styling/checkout-and-accounts-configuration). For the equivalent guide using `checkoutBrandingUpsert`, see [Update color settings](https://shopify.dev/docs/apps/build/checkout/styling/update-color-settings).

***

## Requirements

* You're [authenticated with the GraphQL Admin API](https://shopify.dev/docs/apps/build/authentication-authorization).
* Your app has access to the `read_checkout_and_accounts_configurations` and `write_checkout_and_accounts_configurations` access scopes.
* You have a Checkout and Accounts Configuration ID. To learn how to retrieve one, see [About the Checkout and Accounts Configuration API](https://shopify.dev/docs/apps/build/checkout/styling/checkout-and-accounts-configuration).

***

## Set the color palette

The palette accepts up to 20 named colors in [`designTokens.colors.palette`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/CheckoutAndAccountsConfigurationBrandingPaletteInput):

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL mutation

```graphql
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

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

***

## Set shared semantic colors

Instead of global brand or accent colors, use [`components.shared.colors`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/CheckoutAndAccountsConfigurationBrandingSharedColorsInput) for semantic color roles:

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL mutation

```graphql
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

```json
{
  "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"
          }
        }
      }
    }
  }
}
```

***

## Apply 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

```graphql
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

```json
{
  "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" }
              }
            }
          }
        }
      }
    }
  }
}
```

***

## Set 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

```graphql
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

```json
{
  "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"
                }
              }
            }
          }
        }
      }
    }
  }
}
```

***

## Differences from the Checkout Branding API

| Checkout Branding API | Checkout 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.*.colorScheme` | Colors set directly on each surface's components |
| Same colors across all surfaces | Independent colors per surface (checkout, customer accounts, sign-in) |
| `designSystem.colors.schemes.scheme1.base.background` | `branding.surfaces.checkout.components.main.colors.base.background` |
| N/A | `branding.designTokens.colors.palette` — a flat palette of up to 20 hex colors |

***

## Next steps

* Explore the [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql/latest/mutations/checkoutAndAccountsConfigurationUpdate) to learn more about customizing colors across checkout, customer accounts, and sign-in.

***