Developers / Throttle Builder

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_LIMITED with Retry-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

EndpointScopeAnswer
POST /v1/widgets/validatewidgets:writeA dry run through the same checks as a write. 200 { ok, issues, definition? }. Nothing is stored.
POST /v1/widgetswidgets:writeStores a new widget type. 201 { type, version, status: "active" }.
POST /v1/widgets/:type/versionswidgets:writeStores the next version of an existing type. The body's type must equal the path. 201, as above.
PATCH /v1/widgets/:typewidgets:writeBody { status: "active" | "disabled" }. :type may be custom.name@2 to change one version. 200 { type, status, versions }.
GET /v1/widgetswidgets:read{ widgets: [{ type, title, kind, latestVersion, versionCount, status }] }
GET /v1/widgets/:typewidgets:readThe latest version, or custom.name@2 for one: { type, version, kind, status, createdAt, definition, versions }.
Validate
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" }
] }
Create, version, switch off
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 body
{
  "error": {
    "code": "WIDGET_INVALID",
    "message": "The widget definition is not valid.",
    "requestId": "...",
    "issues": [{ "path": "template", "code": "UNKNOWN_REFERENCE", "message": "..." }]
  }
}
StatusCodeMeaning
400INVALID_REQUESTThe body is not JSON, is empty, has the wrong content type, or a status body is malformed.
401AUTHENTICATION_FAILEDNo key, an unknown or revoked key, or the wrong kind of key. Repeated failures from one address are rate limited (429).
403INSUFFICIENT_SCOPEThe key lacks widgets:write or widgets:read.
403SECRET_KEY_IN_BROWSERA secret key was sent with an Origin header.
403WIDGET_REENABLE_DASHBOARD_ONLYA merchant turned this widget off. Not retryable.
404WIDGET_NOT_FOUNDNo such type or version.
409WIDGET_EXISTSThat type, or that version of it, is already stored.
413WIDGET_TOO_LARGEThe body or definition is over the size limit. Carries issues.
422WIDGET_INVALIDThe definition failed the checks. Carries issues.
422LIMIT_EXCEEDEDA store limit was reached (200 types, or 50 versions of one type).
429RATE_LIMITEDOver the write allowance. Wait for Retry-After.
503RATE_LIMITER_UNAVAILABLEThe 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

A template widget
{
  "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); } }"
}
A composite widget
{
  "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), a label, a tab (content, style or advanced), an output and a control: text, richtext, number, select, toggle, color, spacing, image, link, icon, alignment or font-size. The common settings hidden, anchor, spacingTop and spacingBottom are added for you and do not count. Every setting needs a default that passes its own control. A select needs options.
  • Output. A markup setting is read by the template. A css setting reaches the stylesheet as var(--w-<key>), so it must use the color, spacing, font-size, alignment, number, toggle or select control, 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: true takes 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 as price.display (or price.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 a stack of widgets. Each binding copies a setting into a node's prop and must use the same control. Data inputs reach inner nodes through targets. 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.

Tags
{{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, locale or a loop variable. Names that exist on every object (such as constructor) 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 a p. details with a summary gives a click-to-open section (an FAQ accordion, for example) with no script; it always starts closed, since the open attribute is not allowed.
  • Attributes: class, title, aria-label, aria-hidden and role on any element; href on a; src and alt on img; and data-* (not data-b-, which the renderer owns). No id, no style, no event handlers.
  • class, role, aria-hidden and data-* are static text. A class is 1 to 10 tokens of lower-case letters, digits and hyphens, and none may start with b-, tb-, tsf- or throttle-. A role is a non-interactive one (such as region, list or img).
  • href is either one {{ }} value with no filters (a link setting or a url field) or a fixed https URL or path. src is 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) or default:"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 :empty and :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-face and 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, not z-index.
  • Values: a fixed list of functions (calc, min, max, clamp, var, colours, gradients, transforms, repeat, minmax), a fixed list of units, and var(--w-<key>, fallback) to read a css setting. Never url(), image-set(), attr(), env(), expression(), a backslash escape or !important.
  • At most 10 KB of CSS.

Limits

LimitValue
Definition size64 KB
Request body128 KB
Own settings per widget40
Data inputs per widget5
Template source20 KB
Template nodes / nesting depth2,000 / 12
Loop nesting, and items rendered per loop2, and 100
Nodes one widget may render20,000
CSS10 KB
Custom widget types per store200
Versions per type50
Writes per minute per store30
Issues in one answer50

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 with renamed ({ "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.