Widget API
A custom widget is a definition (data, not code) that a merchant can place on any page. Two kinds exist: a template widget (Throttle Template plus restricted CSS) and a composite widget (other widgets wired to a few settings). The Widget API stores them. The editor and the MCP tools use the same checks.
Authentication and limits
Base URL https://builder.usethrottle.dev. Send a secret key as Authorization: Bearer tb_sk_.... A secret key is refused when the request carries an
Origin, and a publishable key never works here. Writes need widgets:write; the two reads accept widgets:read or widgets:write. Every answer is cache-control: no-store.
- 30 writes a minute for the whole store (two keys share it): the 31st is
429 RATE_LIMITEDwithRetry-After: 60. Validation has its own allowance of the same size. - A request body is at most 128 KB, a definition at most 64 KB, and JSON may nest at most 40 levels.
- An answer lists at most 50 issues.
Endpoints
| Endpoint | Scope | Answer |
|---|---|---|
POST /v1/widgets/validate | widgets:write | A dry run through the same checks as a write. 200 { ok, issues, definition? }. Nothing is stored. |
POST /v1/widgets | widgets:write | Stores a new widget type. 201 { type, version, status: "active" }. |
POST /v1/widgets/:type/versions | widgets:write | Stores the next version of an existing type. The body's type must equal the path. 201, as above. |
PATCH /v1/widgets/:type | widgets:write | Body { status: "active" | "disabled" }. :type may be custom.name@2 to change one version. 200 { type, status, versions }. |
GET /v1/widgets | widgets:read | { widgets: [{ type, title, kind, latestVersion, versionCount, status }] } |
GET /v1/widgets/:type | widgets:read | The latest version, or custom.name@2 for one: { type, version, kind, status, createdAt, definition, versions }. |
curl -X POST https://builder.usethrottle.dev/v1/widgets/validate \
-H "Authorization: Bearer $THROTTLE_BUILDER_SECRET_KEY" \
-H "content-type: application/json" \
-d @new-arrivals.json
# 200: nothing was stored
{ "ok": true, "issues": [], "definition": { "...": "the normalised definition" } }
# 200: not valid
{ "ok": false, "issues": [
{ "path": "css:1:25", "code": "CSS_FORBIDDEN", "message": "url( can load a resource or run code and is not allowed" }
] } curl -X POST https://builder.usethrottle.dev/v1/widgets \
-H "Authorization: Bearer $THROTTLE_BUILDER_SECRET_KEY" \
-H "content-type: application/json" \
-d @new-arrivals.json
# 201
{ "type": "custom.new-arrivals", "version": 1, "status": "active" }
# A new version: the same body with "v": 2
curl -X POST https://builder.usethrottle.dev/v1/widgets/custom.new-arrivals/versions ...
# Turn one version, or every version, off
curl -X PATCH https://builder.usethrottle.dev/v1/widgets/custom.new-arrivals@1 \
-H "Authorization: Bearer $THROTTLE_BUILDER_SECRET_KEY" \
-H "content-type: application/json" \
-d '{ "status": "disabled" }'
A definition is plain JSON data. A type is custom. followed by a lower-case name of letters, digits and hyphens (at most 64 characters after the dot).
A new widget, and each new version, is stored as active. A widget a merchant turned off in the Builder can only be turned back on by the merchant: a key gets 403 WIDGET_REENABLE_DASHBOARD_ONLY.
Errors
{
"error": {
"code": "WIDGET_INVALID",
"message": "The widget definition is not valid.",
"requestId": "...",
"issues": [{ "path": "template", "code": "UNKNOWN_REFERENCE", "message": "..." }]
}
} | Status | Code | Meaning |
|---|---|---|
| 400 | INVALID_REQUEST | The body is not JSON, is empty, has the wrong content type, or a status body is malformed. |
| 401 | AUTHENTICATION_FAILED | No key, an unknown or revoked key, or the wrong kind of key. Repeated failures from one address are rate limited (429). |
| 403 | INSUFFICIENT_SCOPE | The key lacks widgets:write or widgets:read. |
| 403 | SECRET_KEY_IN_BROWSER | A secret key was sent with an Origin header. |
| 403 | WIDGET_REENABLE_DASHBOARD_ONLY | A merchant turned this widget off. Not retryable. |
| 404 | WIDGET_NOT_FOUND | No such type or version. |
| 409 | WIDGET_EXISTS | That type, or that version of it, is already stored. |
| 413 | WIDGET_TOO_LARGE | The body or definition is over the size limit. Carries issues. |
| 422 | WIDGET_INVALID | The definition failed the checks. Carries issues. |
| 422 | LIMIT_EXCEEDED | A store limit was reached (200 types, or 50 versions of one type). |
| 429 | RATE_LIMITED | Over the write allowance. Wait for Retry-After. |
| 503 | RATE_LIMITER_UNAVAILABLE | The write could not be counted, so it was not made. Retry shortly. |
An issue is { path, code, message }. The codes you will meet are INVALID_SHAPE, INVALID_VALUE, REQUIRED, FORBIDDEN_KEY, DUPLICATE_KEY, LIMIT_EXCEEDED, VERSION_RULE, TEMPLATE_SYNTAX, TEMPLATE_FORBIDDEN, ELEMENT_NOT_ALLOWED, ATTRIBUTE_NOT_ALLOWED, FIELD_NOT_ALLOWED, UNKNOWN_REFERENCE, CSS_SYNTAX, CSS_FORBIDDEN, CSS_PROPERTY_NOT_ALLOWED, NO_RECURSION, BINDING_TARGET_MISSING and BINDING_TYPE_MISMATCH. A path inside the template or CSS carries a line and column, such as css:1:25.
A definition
{
"kind": "template",
"type": "custom.new-arrivals",
"v": 1,
"title": "New arrivals",
"description": "A short row of products with their prices.",
"icon": "grid",
"group": "custom",
"settings": [
{ "key": "heading", "label": "Heading", "tab": "content", "output": "markup",
"control": "text", "translatable": true, "default": { "en": "New arrivals" }, "maxLength": 80 },
{ "key": "accent", "label": "Accent colour", "tab": "style", "output": "css",
"control": "color", "default": "token:primary" }
],
"data": {
"products": { "accepts": ["product[]"], "required": true, "label": "Products" }
},
"template": "<section class=\"arrivals\"><h2>{{settings.heading}}</h2><ul>{{#each data.products as product}}<li><a href=\"{{product.url}}\"><img src=\"{{product.imageUrl}}\" alt=\"{{product.imageAlt}}\"><strong>{{product.title|truncate:40}}</strong><span class=\"price\">{{product.price.display}}</span></a></li>{{/each}}</ul></section>",
"css": ".arrivals h2 { color: var(--w-accent, #111111); } .arrivals ul { display: grid; gap: 16px; grid-template-columns: repeat(4, 1fr); list-style: none; padding: 0; } @media (max-width: 767px) { .arrivals ul { grid-template-columns: repeat(2, 1fr); } }"
} {
"kind": "composite",
"type": "custom.promo-strip",
"v": 1,
"title": "Promo strip",
"description": "A heading and a button, edited as one widget.",
"icon": "megaphone",
"group": "custom",
"settings": [
{ "key": "message", "label": "Message", "tab": "content", "output": "markup",
"control": "text", "translatable": true, "default": { "en": "Free shipping this week" }, "maxLength": 100 },
{ "key": "label", "label": "Button label", "tab": "content", "output": "markup",
"control": "text", "translatable": true, "default": { "en": "Shop now" }, "maxLength": 100 },
{ "key": "target", "label": "Button link", "tab": "content", "output": "markup",
"control": "link", "default": null }
],
"body": {
"stack": [
{ "id": "promohead01", "type": "basic.heading", "v": 1, "props": { "level": "h3" } },
{ "id": "promobtn001", "type": "basic.button", "v": 1, "props": { "style": "primary" } }
]
},
"bindings": [
{ "setting": "message", "targets": [{ "node": "promohead01", "prop": "text" }] },
{ "setting": "label", "targets": [{ "node": "promobtn001", "prop": "label" }] },
{ "setting": "target", "targets": [{ "node": "promobtn001", "prop": "link" }] }
]
} - Settings. At most 40 of your own, each with a
key(a letter, then letters and digits, at most 40), alabel, atab(content,styleoradvanced), anoutputand acontrol:text,richtext,number,select,toggle,color,spacing,image,link,icon,alignmentorfont-size. The common settingshidden,anchor,spacingTopandspacingBottomare added for you and do not count. Every setting needs a default that passes its own control. Aselectneeds options. - Output. A
markupsetting is read by the template. Acsssetting reaches the stylesheet asvar(--w-<key>), so it must use thecolor,spacing,font-size,alignment,number,toggleorselectcontrol, never free text, and it cannot be translatable. A select option that reaches CSS is lower-case letters, digits, hyphens and colons. - Translatable text. A text setting with
translatable: truetakes a map of locale to text, such as{ "en": "Hello", "fr": "Bonjour" }. - Data inputs. At most 5. Each names the result types it accepts (
product[],product,collection,category[],review[],customer,cart), whether it is required and a label. The merchant binds the input to a data source; a template may read only the fields of the sources the input accepts. Money is printed only asprice.display(orprice.currency): a template that reads a money amount as a number is refused. - Composite. The body is either
columns(an inner section, which then only goes at the top level of a column) or astackof widgets. Each binding copies a setting into a node's prop and must use the same control. Data inputs reach inner nodes throughtargets. A composite cannot hold another composite.
Throttle Template reference
A template is HTML-like markup with {{ }} tags, parsed into a closed set of nodes. Nothing builds a string of HTML from it: the renderer returns React elements, so a value is always text.
{{settings.heading}} a setting declared "output": "markup"
{{data.products}} / {{product.title}} data input fields, and the item of a loop
{{locale}} the locale being rendered
{{product.title|truncate:40|upper}} up to 4 filters: upper, lower, truncate:N, default:"text"
{{#if product.onSale}} ... {{else}} ... {{/if}}
{{#unless product.inStock}} ... {{/unless}}
{{#each data.products as product}} ... {{/each}} at most 100 items, nested at most 2 deep - A tag holds one plain path (letters and digits, up to six segments) and optional filters. Helpers, arguments, comparisons, index access, parent paths and
{{else if}}are refused. - Paths start at
settings,data,localeor a loop variable. Names that exist on every object (such asconstructor) are refused. - Elements:
div span p h1 h2 h3 h4 h5 h6 a img ul ol li strong em small figure figcaption section article header footer details summary br hr. A heading or block element cannot sit inside ap.detailswith asummarygives a click-to-open section (an FAQ accordion, for example) with no script; it always starts closed, since theopenattribute is not allowed. - Attributes:
class,title,aria-label,aria-hiddenandroleon any element;hrefona;srcandaltonimg; anddata-*(notdata-b-, which the renderer owns). Noid, nostyle, no event handlers. -
class,role,aria-hiddenanddata-*are static text. A class is 1 to 10 tokens of lower-case letters, digits and hyphens, and none may start withb-,tb-,tsf-orthrottle-. Aroleis a non-interactive one (such asregion,listorimg). -
hrefis either one{{ }}value with no filters (a link setting or a url field) or a fixed https URL or path.srcis one{{ }}value: an image setting or an image field, served from the store's media origin only. - A filter is
upper,lower,truncate:N(N up to 500) ordefault:"text"(up to 200 characters). At most 4 per tag.
CSS rules
The CSS is read as CSS, checked against allow-lists, and written back from what was understood: the text you sent is never echoed. It is scoped to the widget ([data-b-w="custom.name"] .x), and a widget is boxed in so its CSS
cannot restyle or cover anything outside it.
- Selectors: your own classes (
.price), the allowed elements, descendant,>,+and~combinators (at most 20 selectors, 8 parts each), and the pseudo-classes:hover :focus :focus-visible :focus-within :active :first-child :last-child :only-child :first-of-type :last-of-type :emptyand:nth-child()style counters (at most 4 per selector part). Ids, attribute selectors and pseudo-elements are refused. - At-rules: only
@media, with(max-width: 767px)for phones,(min-width: 768px) and (max-width: 1024px)for tablets or(min-width: 1025px)for desktops, and not nested.@import,@font-faceand every other at-rule are refused. - Properties: layout (display, sizes, margin, padding, flex, grid, gap, overflow), typography, colour and background, borders, radius, outline, shadows, and transforms and transitions. Not
position, notz-index. - Values: a fixed list of functions (
calc,min,max,clamp,var, colours, gradients, transforms,repeat,minmax), a fixed list of units, andvar(--w-<key>, fallback)to read a css setting. Neverurl(),image-set(),attr(),env(),expression(), a backslash escape or!important. - At most 10 KB of CSS.
Limits
| Limit | Value |
|---|---|
| Definition size | 64 KB |
| Request body | 128 KB |
| Own settings per widget | 40 |
| Data inputs per widget | 5 |
| Template source | 20 KB |
| Template nodes / nesting depth | 2,000 / 12 |
| Loop nesting, and items rendered per loop | 2, and 100 |
| Nodes one widget may render | 20,000 |
| CSS | 10 KB |
| Custom widget types per store | 200 |
| Versions per type | 50 |
| Writes per minute per store | 30 |
| Issues in one answer | 50 |
Versioning
Widgets are versioned, and a published page keeps what it was published with: at publish, the exact versions the page uses are frozen into its document, so a later version or a switched-off widget never changes a live page until the merchant updates and publishes it.
- The first version is
"v": 1, with nothing renamed or removed. A new version is the previous number plus one, and the previous version must exist (VERSION_RULE). - A new version stays the same kind (template or composite) and cannot change the control of a setting. To change a control, add a new key and remove the old one.
-
A setting that disappears must be listed: in
removed, or renamed withrenamed({ "old": "new" }, same control, no collision). The Builder's Update action uses these to carry a merchant's values to the new version. -
Switching a type or version off stops anyone adding it to a page (an insert is refused). A new version of a type that is off is born off. A page already published keeps rendering the widget it froze; when the page is published again
the off widget is frozen as off, the publish warns
WIDGET_DISABLED, and the widget renders nothing in the store.
The API path is /v1. Authoring guidance is in the widget guideline, and the document the widgets live in is in the document schema.