---
title: About the Checkout and Accounts Configuration API
description: >-
  Learn how the Checkout and Accounts Configuration API styles checkout,
  customer accounts, and sign-in surfaces through a unified GraphQL Admin API.
source_url:
  html: >-
    https://shopify.dev/docs/apps/build/checkout/styling/checkout-and-accounts-configuration
  md: >-
    https://shopify.dev/docs/apps/build/checkout/styling/checkout-and-accounts-configuration.md
api_name: checkout-ui-extensions
---

# About the Checkout and Accounts Configuration API

**Plus:**

Checkout styling customizations are available only to [Shopify Plus](https://www.shopify.com/plus) merchants.

The [`checkoutAndAccountsConfigurationUpdate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/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](https://shopify.dev/docs/apps/build/checkout/styling).

**When to use which API:**

The [Checkout Branding API](https://shopify.dev/docs/apps/build/checkout/styling) (using [`checkoutBrandingUpsert`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/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.

***

## Data structures

The Checkout and Accounts Configuration API's [`branding`](https://shopify.dev/docs/api/admin-graphql/latest/objects/CheckoutAndAccountsConfigurationBranding) object is structured around three pillars:

* **[`designTokens`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/CheckoutAndAccountsConfigurationBrandingDesignTokensInput)**: 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`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/CheckoutAndAccountsConfigurationBrandingComponentsInput)**: 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`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/CheckoutAndAccountsConfigurationBrandingSurfacesInput)**: 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

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

***

## Retrieving a configuration

Instead of checkout profiles, the Checkout and Accounts Configuration API uses configuration IDs. Use the [`checkoutAndAccountsConfigurations`](https://shopify.dev/docs/api/admin-graphql/latest/queries/checkoutAndAccountsConfigurations) query to retrieve available configurations:

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

## GraphQL query

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

***

## Updating a configuration

Use the [`checkoutAndAccountsConfigurationUpdate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/checkoutAndAccountsConfigurationUpdate) mutation:

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

## GraphQL mutation

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

## Query variables

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

***

## Mapping from the Checkout Branding API

| Checkout Branding API (`checkoutBrandingUpsert`) | Checkout and Accounts Configuration API (`checkoutAndAccountsConfigurationUpdate`) |
| - | - |
| `checkoutProfileId` parameter | `id` parameter (configuration ID) |
| `designSystem.colors.global` | `branding.designTokens.colors.palette` + `branding.components.shared.colors` |
| `designSystem.colors.schemes` | `branding.surfaces.*.components.*.colors` (per-surface color roles) |
| `designSystem.typography` | `branding.designTokens.typography` |
| `designSystem.cornerRadius` | `branding.designTokens.cornerRadius` |
| `customizations.primaryButton` | `branding.components.primaryButton` |
| `customizations.header` | `branding.components.header` + `branding.surfaces.checkout.components.header` |
| `customizations.footer` | `branding.components.footer` + `branding.surfaces.checkout.components.footer` |
| `customizations.main` | `branding.surfaces.checkout.components.main` |
| `customizations.orderSummary` | `branding.surfaces.checkout.components.orderSummary` |
| `customizations.favicon` | `branding.components.favicon` |
| `customizations.control` | `branding.components.control` |
| N/A | `branding.surfaces.customerAccounts` (new) |
| N/A | `branding.surfaces.signIn` (new) |

***

## Get started

Apply Checkout and Accounts Configuration styling with the following tutorials:

[Customize typography\
\
](https://shopify.dev/docs/apps/build/checkout/styling/checkout-and-accounts-configuration/customize-typography)

[Learn how to apply different font types and other typographical customizations across surfaces.](https://shopify.dev/docs/apps/build/checkout/styling/checkout-and-accounts-configuration/customize-typography)

[Add the favicon\
\
](https://shopify.dev/docs/apps/build/checkout/styling/checkout-and-accounts-configuration/add-favicon)

[Learn how to set the favicon through the Checkout and Accounts Configuration API.](https://shopify.dev/docs/apps/build/checkout/styling/checkout-and-accounts-configuration/add-favicon)

[Customize form controls\
\
](https://shopify.dev/docs/apps/build/checkout/styling/checkout-and-accounts-configuration/customize-form-controls)

[Learn how to customize form controls, checkboxes, and buttons across surfaces.](https://shopify.dev/docs/apps/build/checkout/styling/checkout-and-accounts-configuration/customize-form-controls)

[Update color settings\
\
](https://shopify.dev/docs/apps/build/checkout/styling/checkout-and-accounts-configuration/update-color-settings)

[Learn how to design and apply a color palette and per-surface color roles.](https://shopify.dev/docs/apps/build/checkout/styling/checkout-and-accounts-configuration/update-color-settings)

[Customize sections\
\
](https://shopify.dev/docs/apps/build/checkout/styling/checkout-and-accounts-configuration/customize-sections)

[Learn how to style sections per surface — checkout, customer accounts, and sign-in.](https://shopify.dev/docs/apps/build/checkout/styling/checkout-and-accounts-configuration/customize-sections)

***