---
title: "Update limits"
description: "Update any subset of the limits & terms on a preorder offer: quantity limits and their display, order tags, the terms checkbox and mixed-cart rules."
url: https://docs.stoqapp.com/v2-reference/preorders-offers/update-limits/
api: "API v2 reference"
method: PATCH
path: "/preorders/offers/{id}/limits"
---

# Update limits

`PATCH https://app.stoqapp.com/api/v2/external/preorders/offers/{id}/limits`

Update any subset of the limits &amp; terms on a preorder offer: quantity limits and their display, order tags, the terms checkbox and mixed-cart rules.

**Note:** Deep partial: absent fields are unchanged, null clears. default_per_variant is copied onto every variant in the offer when it changes, replacing their own limits, as the editor does after its confirmation.

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

- `default_per_variant` (integer): Same limit for every product: the most units of each variant that can be preordered. Copied onto EVERY variant in the offer when it changes, replacing each variant's own limit. null clears the limit on every variant. Set one variant's limit with the offer's variant settings instead. While batches release_strategy is sequential the editor hides it: per-batch quantities govern.
- `display_style` (string): How customers see the limit: none, disclaimer (remaining units in the disclaimer) or progress_bar. One of: `none`, `disclaimer`, `progress_bar`.
- `limit_text` (string): Quantity Limit -- the text printed with the remaining-units count.
- `show_icons` (boolean): Use icons for quantity &amp; shipping details on the widget.
- `progress_bar` (object): Look and text of the storefront progress bar toward the quantity limit.
  - `progress_text` (string): Progress bar text.
  - `fill_color` (string): The bar's Fill color. Hex.
  - `background_color` (string): The bar's Background color. Hex.
  - `box_background_color` (string): Box background -- the colour behind the bar. Hex; null falls back to the disclaimer background.
  - `text_color` (string): The bar's Text color. Hex.
  - `border_radius` (integer): The bar's corner radius in pixels.
  - `show_percentage` (boolean): Show percentage next to progress bar.
- `order_tags` (array of anys): Tags Shopify puts on orders containing this offer. A list replaces them; {&quot;$add&quot;: [...], &quot;$remove&quot;: [...]} edits them. Blanks and duplicates are dropped; null or [] clears.
- `terms` (object): The terms checkbox shoppers accept before preordering.
  - `require_acceptance` (boolean): Require customer to accept terms before preordering.
  - `terms_text` (string): Acknowledgement text -- the wording beside the terms checkbox.
  - `disable_button_until_accepted` (boolean): Disable button until terms are accepted.
  - `record_acceptance` (boolean): Record when customer accepted terms, as a cart line property.
  - `acceptance_label` (string): Label for that recorded-acceptance cart line property.
- `cart` (object): Whether a cart can mix preorder and regular items, and the error shown when it cannot.
  - `allowed_items` (string): mixed lets a cart hold preorder and regular items; preorder_only blocks the mix at checkout (the editor's &quot;Don't allow mixed cart orders&quot;). One of: `mixed`, `preorder_only`.
  - `error_message` (string): Mixed cart error message -- shown when a blocked mixed cart reaches checkout.
- `order_quantity` (object): Minimum and maximum quantity per order.
  - `minimum` (integer, nullable): Minimum quantity per order. null removes it.
  - `maximum` (integer, nullable): Maximum quantity per order. null removes the cap.
- `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

- `default_per_variant` (integer, nullable): The same quantity limit for every variant, copied onto each one when set. Null when there is none.
- `display_style` (string): How shoppers see the limit: none, disclaimer (remaining units in the disclaimer line) or progress_bar. One of: `none`, `disclaimer`, `progress_bar`.
- `limit_text` (string): Text printed with the remaining-units count.
- `show_icons` (boolean): Whether the widget uses icons for quantity and shipping details.
- `progress_bar` (object): Look and text of the storefront progress bar toward the quantity limit.
  - `progress_text` (string): Progress bar text.
  - `fill_color` (string): Bar fill color, as hex.
  - `background_color` (string): Bar background color, as hex.
  - `box_background_color` (string, nullable): Color behind the bar, as hex. Null uses the disclaimer background.
  - `text_color` (string): Bar text color, as hex.
  - `border_radius` (integer): Bar corner radius in pixels.
  - `show_percentage` (boolean): Whether a percentage shows next to the bar.
- `order_tags` (array of strings): Tags Shopify puts on orders containing this offer.
- `terms` (object): The terms checkbox shoppers accept before preordering.
  - `require_acceptance` (boolean): Whether shoppers must accept the terms before preordering.
  - `terms_text` (string): Wording beside the terms checkbox.
  - `disable_button_until_accepted` (boolean): Whether the button stays disabled until the terms are accepted.
  - `record_acceptance` (boolean): Whether acceptance is recorded as a cart line property.
  - `acceptance_label` (string): Label of the cart line property that records acceptance.
- `cart` (object): Whether a cart can mix preorder and regular items, and the error shown when it cannot.
  - `allowed_items` (string): mixed lets a cart hold preorder and regular items; preorder_only blocks the mix at checkout. One of: `mixed`, `preorder_only`.
  - `error_message` (string): Error shown when a blocked mixed cart reaches checkout.
- `order_quantity` (object): Minimum and maximum quantity per order.
  - `minimum` (integer, nullable): Minimum quantity per order. Null when there is none.
  - `maximum` (integer, nullable): Maximum quantity per order. Null when there is none.

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/limits" \
  -H "X-Auth-Token: $STOQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_style": "progress_bar",
    "order_tags": {
      "$add": [
        "vip"
      ]
    },
    "terms": {
      "require_acceptance": true
    }
  }'
```

## 202

Success: example response shown.

```json
{
  "default_per_variant": null,
  "display_style": "progress_bar",
  "limit_text": "{{ quantity }} units available for preorder",
  "show_icons": true,
  "progress_bar": {
    "progress_text": "{{ sold }} of {{ total }} claimed",
    "fill_color": "#ffffff",
    "background_color": "#e5e5e5",
    "box_background_color": null,
    "text_color": "#ffffff",
    "border_radius": 4,
    "show_percentage": false
  },
  "order_tags": [
    "STOQ-preorder",
    "vip"
  ],
  "terms": {
    "require_acceptance": true,
    "terms_text": "I acknowledge and agree to the preorder terms and conditions for this product.",
    "disable_button_until_accepted": false,
    "record_acceptance": false,
    "acceptance_label": "Preorder Terms Accepted"
  },
  "cart": {
    "allowed_items": "mixed",
    "error_message": "Preorders must be purchased separately from regular items."
  },
  "order_quantity": {
    "minimum": null,
    "maximum": null
  }
}
```

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

