Widget configuration

The configuration a storefront loads once per page to know what to offer, where, and how it should look.

GET https://{HOST_NAME}/quote/api/storeWidgetConfig/v2/{storeName}

The SureBright storefront SDK calls this endpoint when a page loads, before any quote. The response says which offers are on for your store (product page, cart, checkout, shipping protection, post-purchase, registration), how the widget should look and read, which page elements it attaches to, and which A/B treatment or page-specific design this visitor gets. A headless storefront that renders its own widget reads the same configuration from here.

Everything in the response is what you publish from the merchant portal; see Settings.

Headers#

No authentication header is needed for this endpoint.

Parameters#

string

Your store identifier. You can send it as the storeId or storeName query parameter instead and call /quote/api/storeWidgetConfig/v2.

string

The visitor's session id from an earlier call. When omitted, SureBright creates a visit and returns its id in data.visitId; send that id on every later quote call for the session.

string

Default SHOPIFY.

string

The storefront theme the page is rendered with (on Shopify, the theme id). Used by design targeting rules.

string

The page template suffix (on Shopify, the product template suffix). Used by design targeting rules.

string

false to read the published configuration directly instead of SureBright's cached copy. Use it to check a change you just published.

Example request#

bash
curl 'https://{HOST_NAME}/quote/api/storeWidgetConfig/v2/example-store.myshopify.com?visitId=6a0d0c1e-2b4f-4d8e-9f21-3c5e7a9b1d2f&themeId=151234567890&pageTemplate=premium'

Response#

statusCodenumber

0 on success.

statusMessagestring

success.

dataobject

Caching#

  • A successful response is cacheable at the edge and in the browser: Cache-Control: public, max-age=3600, s-maxage=2592000 (one hour in the browser, 30 days at the edge), with Vary: CloudFront-Viewer-Country, Accept-Encoding. SureBright purges the edge copy when you publish.

  • When the visitor is in an experiment (experimentTracking set) or the store has targeting rules (designTargeting.isActive), the response is per visitor or per page and is sent with Cache-Control: no-store.

  • SureBright also keeps a server-side copy of the published configuration. useCache=false skips it for that request.

Errors#

CodeBodyMeaning
400{"isError": true, "message": "Store ID is required"}No store in the path or query
404{"isError": true, "message": "Store not found or V2 config not available"}Unknown store, or the store has no published configuration
500{"isError": true, "message": "Internal Server Error"}Unexpected failure

Error responses are never cached.