---
title: "Update widget"
description: "Update any subset of the widget configuration on a preorder offer."
url: https://docs.stoqapp.com/v2-reference/preorders-offers/update-widget/
api: "API v2 reference"
method: PATCH
path: "/preorders/offers/{id}/widget"
---

# Update widget

`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): The offer's ID, from [`GET /preorders/offers`](https://docs.stoqapp.com/v2-reference/preorders-offers/list-offers/).

## 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): Text and colors of the preorder button.
  - `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): The disclaimer line shown under the preorder button.
  - `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): The preorder badge shown on product pages and product cards.
  - `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): Text and colors of the preorder button.
  - `button_text` (string, nullable): Preorder button label.
  - `custom_colors_enabled` (boolean): true uses text_color and background_color; false uses the theme's own button colors.
  - `text_color` (string): Button text color, as hex. Used when custom_colors_enabled is true.
  - `background_color` (string): Button background color, as hex. Used when custom_colors_enabled is true.
- `disclaimer` (object): The disclaimer line shown under the preorder button.
  - `show_disclaimer` (boolean): Whether the disclaimer line shows under the button.
  - `disclaimer_text` (string, nullable): Text of the disclaimer line.
  - `text_color` (string): Disclaimer text color, as hex.
  - `background_color` (string): Disclaimer background color, as hex.
  - `border_radius` (integer): Disclaimer corner radius in pixels.
- `badge` (object): The preorder badge shown on product pages and product cards.
  - `show_badge` (boolean): Whether the preorder badge shows.
  - `badge_text` (string): Label printed on the preorder badge.
  - `text_color` (string): Badge text color, as hex.
  - `background_color` (string): Badge background color, as hex.

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"
    }
  }'
```

## 202

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"
  }
}
```

## 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
    }
  ]
}
```

