---
title: Customize typography with Checkout and Accounts Configuration API
description: >-
  Learn how to customize fonts, base size and ratio, and per-component
  typography across surfaces using the Checkout and Accounts Configuration API.
source_url:
  html: >-
    https://shopify.dev/docs/apps/build/checkout/styling/checkout-and-accounts-configuration/customize-typography
  md: >-
    https://shopify.dev/docs/apps/build/checkout/styling/checkout-and-accounts-configuration/customize-typography.md
api_name: checkout-ui-extensions
---

# Customize typography 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 customize typography through the Checkout and Accounts Configuration API. Typography lives under [`branding.designTokens.typography`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/CheckoutAndAccountsConfigurationBrandingTypographyInput) for the design system, and under [`branding.components`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/CheckoutAndAccountsConfigurationBrandingComponentsInput) for per-component overrides such as buttons and headings.

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 [Customize typography](https://shopify.dev/docs/apps/build/checkout/styling/customize-typography).

***

## 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).

***

## Update base size and ratio

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

## GraphQL mutation

```graphql
mutation UpdateTypography($id: ID!, $configuration: CheckoutAndAccountsConfigurationInput!) {
  checkoutAndAccountsConfigurationUpdate(id: $id, configuration: $configuration) {
    configuration {
      branding {
        designTokens {
          typography {
            size { base ratio }
          }
        }
      }
    }
    userErrors { field message code }
  }
}
```

## Query variables

```json
{
  "id": "gid://shopify/CheckoutAndAccountsConfiguration/YOUR_CONFIG_ID_HERE",
  "configuration": {
    "branding": {
      "designTokens": {
        "typography": {
          "size": {
            "base": 16,
            "ratio": 1.4
          }
        }
      }
    }
  }
}
```

***

## Apply a Shopify font

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

## GraphQL mutation

```graphql
mutation UpdateFonts($id: ID!, $configuration: CheckoutAndAccountsConfigurationInput!) {
  checkoutAndAccountsConfigurationUpdate(id: $id, configuration: $configuration) {
    configuration { id }
    userErrors { field message code }
  }
}
```

## Query variables

```json
{
  "id": "gid://shopify/CheckoutAndAccountsConfiguration/YOUR_CONFIG_ID_HERE",
  "configuration": {
    "branding": {
      "designTokens": {
        "typography": {
          "primary": {
            "shopifyFontGroup": { "baseFontHandle": "assistant_n4", "boldFontHandle": "assistant_n7" }
          },
          "secondary": {
            "shopifyFontGroup": { "baseFontHandle": "playfair_display_n4", "boldFontHandle": "playfair_display_n7" }
          }
        }
      }
    }
  }
}
```

***

## Apply a custom font

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

## GraphQL mutation

```graphql
mutation UpdateCustomFont($id: ID!, $configuration: CheckoutAndAccountsConfigurationInput!) {
  checkoutAndAccountsConfigurationUpdate(id: $id, configuration: $configuration) {
    configuration { id }
    userErrors { field message code }
  }
}
```

## Query variables

```json
{
  "id": "gid://shopify/CheckoutAndAccountsConfiguration/YOUR_CONFIG_ID_HERE",
  "configuration": {
    "branding": {
      "designTokens": {
        "typography": {
          "secondary": {
            "customFontGroup": {
              "base": {
                "genericFileId": "gid://shopify/GenericFile/YOUR_FILE_ID_HERE",
                "weight": 100
              },
              "bold": {
                "genericFileId": "gid://shopify/GenericFile/YOUR_FILE_ID_HERE",
                "weight": 500
              }
            }
          }
        }
      }
    }
  }
}
```

***

## Style buttons and headings with typography

Button and heading typography customizations live under [`branding.components`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/CheckoutAndAccountsConfigurationBrandingComponentsInput):

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

## GraphQL mutation

```graphql
mutation UpdateComponentTypography($id: ID!, $configuration: CheckoutAndAccountsConfigurationInput!) {
  checkoutAndAccountsConfigurationUpdate(id: $id, configuration: $configuration) {
    configuration {
      branding {
        components {
          primaryButton { typography { font weight letterCase size } }
          headingLevel1 { typography { size letterCase weight } }
        }
      }
    }
    userErrors { field message code }
  }
}
```

## Query variables

```json
{
  "id": "gid://shopify/CheckoutAndAccountsConfiguration/YOUR_CONFIG_ID_HERE",
  "configuration": {
    "branding": {
      "components": {
        "primaryButton": {
          "typography": {
            "font": "SECONDARY",
            "weight": "BOLD",
            "letterCase": "UPPER",
            "size": "MEDIUM"
          }
        },
        "headingLevel1": {
          "typography": {
            "size": "LARGE",
            "letterCase": "UPPER",
            "weight": "BOLD"
          }
        }
      }
    }
  }
}
```

***

## Differences from the Checkout Branding API

| Checkout Branding API | Checkout and Accounts Configuration API |
| - | - |
| `designSystem.typography` | `branding.designTokens.typography` |
| `customizations.primaryButton.typography` | `branding.components.primaryButton.typography` |
| `customizations.headingLevel1.typography` | `branding.components.headingLevel1.typography` |
| Font groups: `shopifyFontGroup` / `customFontGroup` | Nested under `designTokens.typography.primary` / `secondary`. `shopifyFontGroup` uses `baseFontHandle` and `boldFontHandle` instead of a single `name`. |

***

## Next steps

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

***