Branding Themes

A branding theme is a named colour palette — and optional logos and font — you attach to a product's checkout styles. Attach it with branding_theme_id on Update Product Styles.

The list contains themes you created for this store. Built-in dashboard palettes are not included and cannot be addressed by UUID.

Overview

• List branding themes
• Retrieve a branding theme
• Create a branding theme
• Update a branding theme
• Delete a branding theme

Themes are not nested on Get store. Storefront theme_id is a different field and does not apply this palette.

Default

At most one theme per store has is_default: true. Setting is_default to true on create or update clears the previous default. Setting it to false, or deleting the current default, is allowed — a store may have no default. Nothing is promoted automatically.

Colours

Theme colour fields accept null or # plus exactly 6 hex digits (#aabbcc). Values are stored and returned lowercase. transparent and 3-digit hex (#abc) return 422. This is stricter than product style colours.

The six colour fields are brand_color, background_color, text_color, card_background_color, card_text_color, and border_color. A theme has no main_background_color, main_border_color, price_text_color, or shadow tokens.

Attaching to a product

Send branding_theme_id on live or draft Update Product Styles. Attach copies a colour or logo onto the product only when the theme value is non-null — the product's existing colour or logo stays when the theme field is null. See Checkout appearance.

Delete

Delete removes the theme from the public list. Products that pointed at it keep their copied colour tokens; their styles branding_theme_id is cleared. The same id cannot be reused.

Branding Theme Object

Field	Type	Nullable	Description
id	string	No	Server-minted UUID.
name	string	No	Label, 1–255 characters.
is_default	boolean	No	At most one per store. See Default.
font	string	Yes	Font name, max 255.
logo_url	string	Yes	Logo URL.
logo_square_url	string	Yes	Square logo URL.
brand_color	string	Yes	Hex colour. See Colours.
background_color	string	Yes	Hex colour. Copied onto product background_color on attach.
text_color	string	Yes	Hex colour.
card_background_color	string	Yes	Hex colour.
card_text_color	string	Yes	Hex colour.
border_color	string	Yes	Hex colour.