---
title: "Widget configuration"
description: "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](/merchant-portal/settings).

## Headers

No authentication header is needed for this endpoint.

## Parameters

<ParamField path="storeName" type="string">
  Your store identifier. You can send it as the `storeId` or `storeName` query parameter instead and call `/quote/api/storeWidgetConfig/v2`.
</ParamField>
<ParamField query="visitId" type="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.
</ParamField>
<ParamField query="platform" type="string">
  Default `SHOPIFY`.
</ParamField>
<ParamField query="themeId" type="string">
  The storefront theme the page is rendered with (on Shopify, the theme id). Used by design targeting rules.
</ParamField>
<ParamField query="pageTemplate" type="string">
  The page template suffix (on Shopify, the product template suffix). Used by design targeting rules.
</ParamField>
<ParamField query="useCache" type="string">
  `false` to read the published configuration directly instead of SureBright's cached copy. Use it to check a change you just published.
</ParamField>

## 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

<ResponseField name="statusCode" type="number">
  `0` on success.
</ResponseField>
<ResponseField name="statusMessage" type="string">
  `success`.
</ResponseField>
<ResponseField name="data" type="object">
  <Expandable title="fields">
    <ResponseField name="storeId" type="string">Your store identifier.</ResponseField>
    <ResponseField name="storeDisplayName" type="string">The store name shown in the widget.</ResponseField>
    <ResponseField name="platform" type="string">The platform the configuration is for.</ResponseField>
    <ResponseField name="configVersion" type="number">Version number of the published configuration.</ResponseField>
    <ResponseField name="configStatus" type="string">Status of that configuration.</ResponseField>
    <ResponseField name="visitId" type="string">The visit id to send on quote calls.</ResponseField>
    <ResponseField name="featureControlFlagSet" type="object">
      Which offers are on. Booleans: `isProductOfferingEnabled`, `isCartOfferingEnabled`, `isCheckoutOfferingEnabled`, `isShippingInsuranceEnabled`, `isPostPurchaseEnabled`, `isProductRegistrationEnabled`, `isBottomCartCTAEnabled`, `isQuickViewEnabled`, `isCartDrawerEnabled`, `isCartNotificationEnabled`, `isRibbonEnabled`, `isNoCoverageOptionVisible`, `isDefaultSelectionEnabled`, `isAnalyticsEnabled`.
    </ResponseField>
    <ResponseField name="widgetAttributeSet" type="object">
      How the widget looks and reads. One section per concern, each `null` when not customised: `theme`, `offeringCardStyle`, `modalOfferingCardStyle`, `offeringCardLabel`, `pdpLayout`, `popupModalLayout`, `quickViewLayout`, `cartLayout`, `postPurchaseLayout`, `productRegistrationLayout`, `shippingInsuranceLayout`, `content`, `responsive`. List-valued fields are always arrays, never `null`.
    </ResponseField>
    <ResponseField name="widgetAttributeSetId" type="string">
      Identifier of the design this visitor received. Differs from `baseAttributeSetId` when an experiment or a targeting rule applied.
    </ResponseField>
    <ResponseField name="baseAttributeSetId" type="string">
      Identifier of the published (control) design.
    </ResponseField>
    <ResponseField name="technicalConfig" type="object">
      How the SDK attaches to your storefront: `selector` (page elements to mount on), `interceptor` (cart and checkout calls to observe), `variantResolution` (how the selected variant is read). Each `null` when the platform defaults apply.
    </ResponseField>
    <ResponseField name="enabledCapabilityIdList" type="string[]">
      Optional behaviours switched on for the store, with their settings in `capabilityParameterMap`.
    </ResponseField>
    <ResponseField name="capabilityParameterMap" type="object">
      Settings for the enabled capabilities, keyed by capability id.
    </ResponseField>
    <ResponseField name="experimentTracking" type="object">
      `{experimentId, treatmentId}` when the visitor is in a running A/B test, otherwise `null`. Pass both on your analytics events so results attribute correctly.
    </ResponseField>
    <ResponseField name="designTargeting" type="object">
      `null` when the store has no page targeting rules. Otherwise `{isActive: true, matchedRuleId, configId}`; `matchedRuleId` and `configId` are `null` when no rule matched the `themeId` and `pageTemplate` you sent and the live design was served.
    </ResponseField>
  </Expandable>
</ResponseField>

## 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

| Code | Body | Meaning |
|------|------|---------|
| `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.
