checkoutBrandingUpsert still runs, and it is deprecated. The Shopify checkout branding API is now checkoutAndAccountsConfigurationUpdate, which arrived in Admin API version 2026-04 and writes one configuration that styles checkout, customer accounts and sign-in together. The checkout profile you used to target is now a checkout and accounts configuration.
Shopify’s developer changelog entry, dated 13 May 2026, says the new API replaces “the Checkout Profile API and Checkout Branding API (both are now deprecated)”. No removal date has been announced, and nothing breaks this quarter. The reason to move anyway is reach. Shopify’s line on the release is that branding settings “now apply consistently across checkout, customer accounts, and sign-in pages”, which is a statement about what the two older APIs, split between them, did not manage.
Everything below is written against 2026-07, the current stable Admin API version.
Which mutation is the Shopify checkout branding API now?
The old call took a checkout profile ID plus a branding blob, and the reference page now opens with “Deprecated. Use checkoutAndAccountsConfigurationUpdate instead”:
# Deprecated since 2026-04
mutation LegacyBranding($checkoutProfileId: ID!, $checkoutBrandingInput: CheckoutBrandingInput) {
checkoutBrandingUpsert(
checkoutProfileId: $checkoutProfileId
checkoutBrandingInput: $checkoutBrandingInput
) {
userErrors {
field
message
}
}
}The replacement takes a configuration ID and a configuration:
mutation UpdateBranding($id: ID!, $configuration: CheckoutAndAccountsConfigurationInput!) {
checkoutAndAccountsConfigurationUpdate(id: $id, configuration: $configuration) {
configuration {
id
name
isPublished
editedAt
}
userErrors {
field
message
}
}
}On the old mutation checkoutBrandingInput was optional. On the new one both arguments are non-null, so the least you can send is an empty configuration object.
The access requirements moved too. checkoutBrandingUpsert asks for “access to checkout branding settings” plus the preferences staff permission, and states the shop “must be on a Plus plan or a Development store plan”. checkoutAndAccountsConfigurationUpdate wants write_checkout_and_accounts_configurations or write_checkout_settings, the manage_checkout_settings permission, access to the checkout and accounts editor, and the shop to have contextualised checkouts and customer accounts enabled.
That last condition is the one that catches app developers. A shop can be on Plus, have your app installed with the right scope, and still not be eligible. Check before you migrate the code path, not after a merchant opens a ticket.
How do you find the configuration ID to update?
Same shape as the old profile lookup, different connection. checkoutProfiles is deprecated in favour of checkoutAndAccountsConfigurations:
query PublishedConfiguration {
checkoutAndAccountsConfigurations(first: 10) {
nodes {
id
name
isPublished
updatedAt
}
}
}Read isPublished and pick the node where it is true. That is the configuration customers actually see. The others are drafts sitting in the editor, and writing to one of those is the quiet failure mode of this API: the mutation succeeds, userErrors is empty, and checkout looks exactly as it did.
A single configuration is fetched with checkoutAndAccountsConfiguration(id: ID!).
What goes inside the branding input?
CheckoutAndAccountsConfigurationInput has two fields, branding and overrides. Branding then splits three ways: designTokens for brand-wide values, components for named pieces of UI, and surfaces for per-surface adjustments.
{
"id": "gid://shopify/CheckoutAndAccountsConfiguration/1",
"configuration": {
"branding": {
"designTokens": {
"colors": {
"palette": {
"color1": "#101820",
"color2": "#0d7d6f",
"color3": "#f6f5f2"
}
},
"cornerRadius": { "base": 5, "small": 3, "large": 10 },
"typography": {
"primary": {
"customFontGroup": {
"base": { "genericFileId": "gid://shopify/GenericFile/1", "weight": 400 },
"bold": { "genericFileId": "gid://shopify/GenericFile/2", "weight": 700 }
}
}
}
},
"components": {
"primaryButton": { "cornerRadius": "LARGE" },
"header": { "divided": true }
}
}
}
}Two things in there are worth reading twice.
The corner radius on the button is an enum, not a number. LARGE is documented as “the corner radius with a pixel value defined by designTokens.cornerRadius.large”, so the button picks up the 10 you set in the same payload. BASE, SMALL and NONE are the other three values, and NONE is a literal 0px rather than a lookup. Change large to 2 and every component referencing LARGE moves with it, which is the entire point of a token.
The font is a file, not a name. customFontGroup needs a base and a bold, each a genericFileId from the Files API with a weight between 100 and 900, and the docs restrict uploads to .woff and .woff2. If you would rather use a Shopify-hosted face, shopifyFontGroup takes baseFontHandle and boldFontHandle instead. typography.primary covers text, buttons and form controls; typography.secondary is what headings use by default.
The component list is fixed and fairly long: checkbox, choiceList, control, divider, favicon, footer, header, headingLevel1 through headingLevel3, main, merchandiseThumbnail, primaryButton, secondaryButton, select, shared and textField. Header alone accepts alignment, background, colors, divided, logo and padding.
What did you actually gain by moving off checkout profiles?
Three things, and the rename is not one of them.
Colours became a flat palette. CheckoutAndAccountsConfigurationBrandingPaletteInput is twenty optional string fields, color1 through color20, each a hex value. The changelog describes it as a way to “save your brand colors to a reusable palette of up to 20 colors”, with updates applying everywhere the colour is referenced. Compared with assembling colour schemes, it is a much shorter path from a brand guideline to a working payload.
One write now covers three surfaces. Set the shared branding once, then reach for surfaces.checkout, surfaces.customerAccounts or surfaces.signIn only where one of them has to differ, which Shopify documents for logos, colours and section styles. A sign-in page that needs a different logo treatment from checkout is a two-field override rather than a second integration. If your app also handles the login side of this, our walkthrough of Customer Account API authentication covers the surface those pages sit on.
Then overrides, a list where each entry carries an id and its own branding. The mutation demands view_markets and create_and_edit_markets when you touch them, which tells you plainly what they are for even though the input object itself does not spell it out.
What can you still not style?
The plan gate has not moved. Shopify’s checkout styling overview states that “Checkout styling customizations are available only to Shopify Plus merchants”, with development stores allowed for building against.
Two stated limits are easy to trip over. “You can’t currently customize styling for individual pages”, so information, shipping and payment share one look. And “SVG is not a supported image type for styling checkout”, which surprises everyone whose logo lives as an SVG. Export a PNG at 2x and move on.
Beyond that, the API sets token values on components Shopify already renders. You cannot inject CSS, add a component, or move an element. Anything structural is a Checkout UI extension, and the two systems have different rules about what runs where, which our guide to checkout UI extensions goes through.
Should you migrate now, or wait?
Migrate now if you write branding programmatically. The concepts survived the move, so most of the work is re-nesting: designSystem becomes designTokens, customizations becomes components, and colour schemes flatten into the twenty-slot palette. None of it needs a new design decision, which is what makes it worth doing before it becomes urgent.
Wait if branding is set once at launch through the editor and never touched again. Nobody is paying you to rewrite a script that runs annually, and the removal has not been scheduled.
Either way, pin the API version in your client and read the changelog each quarter. A branding call that silently writes to an unpublished configuration is worse than one that errors, and the difference between those two outcomes is one boolean you have to check yourself.
Whoooop builds and maintains Shopify Plus checkouts, including branding automation, checkout UI extensions and the apps behind them. We take on migrations where the checkout has to be rebuilt as well as restyled. There is more on our Shopify development page.