--- title: "Update a widget on an offer" description: "Update any subset of the widget configuration on a preorder offer." url: https://docs.stoqapp.com/v2-reference/preorders-offers/update-a-widget-on-an-offer/ api: "API v2 reference" method: PATCH path: "/preorders/offers/{id}/widget" --- # Update a widget on an offer `PATCH https://app.stoqapp.com/api/v2/external/preorders/offers/{id}/widget` Update any subset of the widget configuration on a preorder offer. **Note:** 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. ## Path parameters - `id` (string, required) ## Headers - `Idempotency-Key` (string): 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 - `button` (object) - `button_text` (string, nullable): Button text -- the preorder call-to-action label. - `text_color` (string): The button's Text color. Hex. Only shows when button.custom_colors_enabled is true; send it too. - `background_color` (string): The button's Background color. Hex. Only shows when button.custom_colors_enabled is true; send it too. - `custom_colors_enabled` (boolean): Use custom colors for button. False falls back to the theme's own button colors. - `disclaimer` (object) - `show_disclaimer` (boolean): Add disclaimer -- shows or hides the disclaimer line under the button. - `disclaimer_text` (string, nullable): Disclaimer -- the line shown under the preorder button. - `text_color` (string): The disclaimer's Text color. Hex. - `background_color` (string): The disclaimer's Background color. Hex. - `border_radius` (integer): The disclaimer's Border radius in pixels. - `badge` (object) - `show_badge` (boolean): 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_text` (string, nullable): Badge -- the label printed on the preorder badge. - `text_color` (string): The badge's Text color. Hex. - `background_color` (string): The badge's Background color. Hex. - `locale` (string): Language the translated fields are written in, such as 'fr' or 'pt-BR'. Omitted: the shop's default language. Untranslated fields ignore it. ## Returns - `button` (object) - `button_text` (string): e.g. `Reserve Now` - `custom_colors_enabled` (boolean): e.g. `true` - `text_color` (string): e.g. `#FFFFFF` - `background_color` (string): e.g. `#1a1a1a` - `disclaimer` (object) - `show_disclaimer` (boolean): e.g. `true` - `disclaimer_text` (string): e.g. `Expected to ship by August 2026` - `text_color` (string): e.g. `#000000` - `background_color` (string): e.g. `#FFFFFF` - `border_radius` (integer): e.g. `4` - `badge` (object) - `show_badge` (boolean): e.g. `true` - `badge_text` (string): e.g. `Pre-Order` - `text_color` (string): e.g. `#000000` - `background_color` (string): e.g. `#FFFFFF` Rate limit: this call costs 2 points ([rate limits](https://docs.stoqapp.com/docs/rate-limits/)). ## Example request ```sh 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" } }' ``` ## 200 Success: example response shown. ```json { "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" } } ``` ## 202 Saved. Returns the updated section, with also_changed for cascades. ## 401 Missing or invalid `X-Auth-Token`. ```json { "errors": [ "Invalid API key" ], "code": "auth_invalid", "details": [ { "code": "auth_invalid", "message": "Invalid API key", "path": null, "value": null, "expected": null } ] } ``` ## 404 The resource does not exist for this shop, or the action path is not registered. ```json { "errors": [ "Offer not found" ], "code": "not_found", "details": [ { "code": "not_found", "message": "Offer not found", "path": null, "value": null, "expected": null } ] } ``` ## 409 An earlier request with the same Idempotency-Key is still running. Wait, then resend the same request with the same key. ```json { "errors": [ "A request with this Idempotency-Key is still running" ], "code": "idempotency_key_in_progress", "details": [ { "code": "idempotency_key_in_progress", "message": "A request with this Idempotency-Key is still running", "path": null, "value": null, "expected": null } ] } ``` ## 422 Invalid fields: one `details` entry per field error, its `path` the canonical section path. Nothing was saved. ```json { "errors": [ "widget.button.text_color must be a hex color" ], "code": "invalid_params", "details": [ { "code": "invalid_params", "message": "must be a hex color", "path": "widget.button.text_color", "value": "blue", "expected": { "type": "string" } } ] } ``` ## 429 Rate limited: cost-weighted per token (read 1, write 2; 360 points / 60s). Check `Retry-After`. ```json { "errors": [ "Rate limit exceeded" ], "code": "rate_limited", "details": [ { "code": "rate_limited", "message": "Rate limit exceeded", "path": null, "value": null, "expected": null } ] } ```