# Checkout branding API: the tokens worth setting first

Source: https://checkoutoptimizelab.com/2026-11-06-checkout-branding-api-tokens-first.html

The checkout branding API exposes dozens of design tokens, and the documentation lists them all with equal weight, which is the documentation lying by omission. Most of the tokens change things no shopper will ever notice. Five of them change things every shopper sees. Set those five, and the checkout looks like your store. Set the other forty first, and you have spent a week on pixels nobody sees while the button still looks like Shopify.

The five that matter are the ones on the path to payment. The primary button colour and its corner radius, because the button is the largest interactive element on the page. The link colour, because the links are the escape hatches and they need to be visible without shouting. The page background and the form background, because the contrast between them is what makes the form readable. And the font, because a checkout in the store's font reads as the store, and a checkout in the default font reads as a handoff to someone else.

## Why the button comes first

The button is the conversion element, and its colour is the first thing a shopper's eye finds. Set it to the brand's primary action colour, and set the corner radius to match the store's buttons, because a square button on a store full of rounded buttons is a visual tell that the checkout belongs to someone else. Then check the contrast, because a brand colour that fails contrast on the button text is a brand colour that fails accessibility, and the branding API will let you set it anyway. The API does not protect you from your own palette.

Test the button on a phone, not on a desktop, because that is where most checkouts happen. A button that looks right on a wide screen can look cramped on a narrow one, and the corner radius that looks sharp on desktop can look fussy on mobile. The branding API sets the tokens. The phone shows you what the tokens actually do.

## The tokens to leave alone

Leave the section dividers, the secondary button styles, and the fine print colours alone until the five are set and tested. They matter, but they matter second, and a team that sets them first is polishing the edges of a page whose centre does not look like the store yet. There is also a real risk in over-setting: every token you set is a token you have to maintain when the brand changes, and a branding API with forty custom tokens is a design system that nobody remembers the reasons for.

On Plus, the branding API is available through the checkout editor and the API itself. On lower plans, the editor covers branding within its own limits, and the API's full range is not available. That is a plan boundary, not a bug, and it is worth knowing before promising a client a fully branded checkout on a Basic plan.

## The check after setting them

Set the five tokens, run a test order on a phone, and look at the checkout the way a shopper does: does it look like the store, does the button stand out, can you read the form, and does anything look like it belongs to a different website. If the answer is yes to the first three and no to the last, the branding is done. Everything else is a second pass for a quiet afternoon, not a launch blocker.

Keep reading: [Checkout discount auto apply and the code box test](2026-11-04-checkout-discount-auto-apply-code-box-test.md), [Checkout international phone format errors](2026-11-04-checkout-international-phone-format-errors.md).

## Frequently asked questions

### Which checkout branding tokens matter most?

The primary button colour and corner radius, the link colour, the page and form backgrounds, and the font. Those are the tokens every shopper sees. The rest are refinements to set after these five are tested.

### Is the checkout branding API available on all Shopify plans?

No. The full branding API is a Plus feature. Lower plans get branding controls in the checkout editor, but the API's full range is not available. That is a plan boundary to know before promising a fully branded checkout.

### Can the branding API set a button colour that fails contrast?

Yes. The API does not protect you from your own palette. Check the button text contrast yourself, because a brand colour that fails contrast is an accessibility failure, whatever the API allowed.

### Should I set every branding token the API offers?

No. Every token you set is a token you have to maintain when the brand changes. Set the five that shoppers see, test them on a phone, and leave the rest until the centre of the page looks like the store.