Skip to main content
A Variant is one set of overrides on one Theme. It is what you create per brand, per customer, or per white-label deployment. Resolution is the Theme’s document overlaid with the Variant’s, path by path. The Theme owns the structure — the tree, the names, $type, $description — and a Variant owns values and nothing else. A Variant cannot add a token the Theme does not have, and a path it overrides that the Theme lacks is ignored. See Variants.

​
Endpoints

Overrides are a sub-resource with their own rules; see Variant tokens.

​
List Variants

​
string
Exact match, within this Theme.
​
string
default:"ascending"
​
integer
default:"1"
​
integer
default:"100"
​
boolean
default:"false"

​
Create a Variant

Creating a Variant can be refused with 402. The Team’s plan caps how many Variants a Theme may have — 10 on Free, 100 on Pro. The body’s cause is planLimit, and retrying will not help. See Errors and Plans and limits.

​
Update a Variant

Renames the Variant and sets its labels. It cannot touch its overrides. slug and displayName are required and replace what is stored. metadata behaves exactly as it does on a Theme: omit it to leave the labels alone, send {} to clear them. The same bounds apply — 50 keys, 64-character keys, 256-character values.

​
Delete a Variant

Answers 200 with the parent Theme. Every published version of the Variant is removed with it, and anything reading its serving URLs starts getting 404.

​
The Variant resource

​
string
required
​
string
required
​
string
required
Unique within the Theme, not globally.
​
string
required
​
integer
required
How many tokens this Variant overrides — not how many the resolved theme has.
​
integer | null
The newest published version of the overrides.
A Variant version number is the Theme version its overrides are addressed against, not a count of this Variant’s own publishes. A Variant’s overrides only mean anything against a particular Theme structure, so the two numbers are one number.The consequence is a real limit: a Variant can be published only once per Theme version. A second publish against the same Theme version answers 409.
​
string | null
​
boolean
required
Expect this to be true on Variants nobody touched after their Theme publishes — that is the automatic migration waiting for review. See Versioning.
​
object
required
Your labels. Never a secret.
​
object
required
Where this Variant is served: the Theme’s address with this Variant’s id in the third segment, where a Theme on its own carries -.Which files exist is decided by the Theme’s integrations. A Variant has none of its own, so this list and the Theme’s always name the same files.version here is the Theme’s newest published version, for the reason above.
​
string
required
​
string
required

​
What a Variant is not

Say Variant, not “brand” and not “organization”. A Variant is the product concept; “brand” is how we describe what you use it for. Nothing sits between an Environment and a Theme, and nothing sits below a Variant — there is no application, tenant or sub-brand layer, and there will not be.