Skip to content

Update widget

API v2 is in public beta: endpoints and fields can change before general availability. See the changelog

PATCH/preorders/offers/{id}/widget

Costs 2 rate-limit points · Rate limits

Update any subset of the widget configuration on a preorder offer.

Deep partial: absent fields are unchanged. Text can be cleared with null. Button colors only show with button.custom_colors_enabled: true, so send both.

Also searched asedit widgetchange widget settingsmodify widgetupdate preorder uienable badgeshow badgeturn on badgemake badge visibledisable badgehide badgeturn off badgeremove badgeenable disclaimershow disclaimerturn on disclaimershow fine printshow shipping noticedisable disclaimerhide disclaimerturn off disclaimerhide fine printremove shipping noticeremove disclaimerenable custom button colorsuse custom button colorsturn on button colorsapply custom colorsdisable custom button colorsuse theme button colorsturn off button colorsrevert to theme colorschange badge colorsset badge colorcustomize badge colorschange badge backgroundchange badge textset badge labelrename badgechange preorder badge textupdate badge textchange button colorsset button colorcustomize button colorschange button textrename buttonset button labelchange preorder button labelupdate button textchange disclaimer colorsset disclaimer stylestyle the disclaimerset disclaimer border radiuschange disclaimer backgroundchange disclaimer textset disclaimer textedit disclaimerchange disclaimer messageset shipping disclaimer

Path parameters

Headers

  • Idempotency-Keystring

    A fresh unique key for every write (a new UUID, say); reuse it only to retry that write. Keys are remembered for 1 hour: the same key and the same request within that hour returns the first result, with Idempotent-Replayed: true, without running again; the same key with a different method, path or body is refused (422 idempotency_key_reused); a retry while the first is still running gets 409 idempotency_key_in_progress. Keys are per store. Server errors and rate limits are not kept, so their retry runs.

Request body

  • buttonobject

    Text and colors of the preorder button.

    Show 4 child attributesHide child attributes
    • button_textstring, nullable

      Button text -- the preorder call-to-action label.

    • text_colorstring

      The button's Text color. Hex. Only shows when button.custom_colors_enabled is true; send it too.

    • background_colorstring

      The button's Background color. Hex. Only shows when button.custom_colors_enabled is true; send it too.

    • custom_colors_enabledboolean

      Use custom colors for button. False falls back to the theme's own button colors.

  • disclaimerobject

    The disclaimer line shown under the preorder button.

    Show 5 child attributesHide child attributes
    • show_disclaimerboolean

      Add disclaimer -- shows or hides the disclaimer line under the button.

    • disclaimer_textstring, nullable

      Disclaimer -- the line shown under the preorder button.

    • text_colorstring

      The disclaimer's Text color. Hex.

    • background_colorstring

      The disclaimer's Background color. Hex.

    • border_radiusinteger

      The disclaimer's Border radius in pixels.

  • badgeobject

    The preorder badge shown on product pages and product cards.

    Show 4 child attributesHide child attributes
    • show_badgeboolean

      Add badge -- shows or hides the preorder badge. On product pages it sits after the price by default. On home, collection and search pages it shows on the product card, only where Preorder pages turns the Preorder button on.

    • badge_textstring, nullable

      Badge -- the label printed on the preorder badge.

    • text_colorstring

      The badge's Text color. Hex.

    • background_colorstring

      The badge's Background color. Hex.

  • localestring

    Language the translated fields are written in, such as 'fr' or 'pt-BR'. Omitted: the shop's default language. Untranslated fields ignore it.

Returns

  • buttonobject

    Text and colors of the preorder button.

    Show 4 child attributesHide child attributes
    • button_textstring, nullable

      Preorder button label.

    • custom_colors_enabledboolean

      true uses text_color and background_color; false uses the theme's own button colors.

    • text_colorstring

      Button text color, as hex. Used when custom_colors_enabled is true.

    • background_colorstring

      Button background color, as hex. Used when custom_colors_enabled is true.

  • disclaimerobject

    The disclaimer line shown under the preorder button.

    Show 5 child attributesHide child attributes
    • show_disclaimerboolean

      Whether the disclaimer line shows under the button.

    • disclaimer_textstring, nullable

      Text of the disclaimer line.

    • text_colorstring

      Disclaimer text color, as hex.

    • background_colorstring

      Disclaimer background color, as hex.

    • border_radiusinteger

      Disclaimer corner radius in pixels.

  • badgeobject

    The preorder badge shown on product pages and product cards.

    Show 4 child attributesHide child attributes
    • show_badgeboolean

      Whether the preorder badge shows.

    • badge_textstring

      Label printed on the preorder badge.

    • text_colorstring

      Badge text color, as hex.

    • background_colorstring

      Badge background color, as hex.

Errors

404
not_found

The path is valid but nothing with that id exists in this store.

409
idempotency_key_in_progress

A request with the same Idempotency-Key has not finished yet.

422
idempotency_key_invalid

The Idempotency-Key header is empty, longer than 255 characters or has characters other than visible ASCII.

422
idempotency_key_reused

The Idempotency-Key header was already used for a request with a different method, path or body. Keys are remembered for 1 hour.

422
invalid_params

One or more fields failed the action's schema.

Any request can also fail with auth_invalid (401) or rate_limited (429).

Every error has the same shape: see Errors and the list of error codes.

PATCH/preorders/offers/{id}/widget
curl -X PATCH "https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/widget" \
  -H "X-Auth-Token: $STOQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "button": {
      "button_text": "Reserve Now"
    }
  }'
Response
{
  "button": {
    "button_text": "Reserve Now",
    "custom_colors_enabled": true,
    "text_color": "#FFFFFF",
    "background_color": "#1a1a1a"
  },
  "disclaimer": {
    "show_disclaimer": true,
    "disclaimer_text": "Expected to ship by August 2026",
    "text_color": "#000000",
    "background_color": "#FFFFFF",
    "border_radius": 4
  },
  "badge": {
    "show_badge": true,
    "badge_text": "Pre-Order",
    "text_color": "#000000",
    "background_color": "#FFFFFF"
  }
}