---
title: "Update a limit on an offer"
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-a-limit-on-an-offer/
api: "API v2 reference"
method: PATCH
path: "/preorders/offers/{id}/limits"
---

# Update a limit on an offer

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

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.

**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)

## 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 & shipping details on the widget.
- `progress_bar` (object)
  - `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; {"$add": [...], "$remove": [...]} edits them. Blanks and duplicates are dropped; null or [] clears.
- `terms` (object)
  - `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)
  - `allowed_items` (string): mixed lets a cart hold preorder and regular items; preorder_only blocks the mix at checkout (the editor's "Don't allow mixed cart orders"). One of: `mixed`, `preorder_only`.
  - `error_message` (string): Mixed cart error message -- shown when a blocked mixed cart reaches checkout.
- `order_quantity` (object)
  - `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` (any)
- `display_style` (string): e.g. `progress_bar`
- `limit_text` (string): e.g. `{{ quantity }} units available for preorder`
- `show_icons` (boolean): e.g. `true`
- `progress_bar` (object)
  - `progress_text` (string): e.g. `{{ sold }} of {{ total }} claimed`
  - `fill_color` (string): e.g. `#ffffff`
  - `background_color` (string): e.g. `#e5e5e5`
  - `box_background_color` (any)
  - `text_color` (string): e.g. `#ffffff`
  - `border_radius` (integer): e.g. `4`
  - `show_percentage` (boolean): e.g. `false`
- `order_tags` (array of strings)
- `terms` (object)
  - `require_acceptance` (boolean): e.g. `true`
  - `terms_text` (string): e.g. `I acknowledge and agree to the preorder terms and conditi…`
  - `disable_button_until_accepted` (boolean): e.g. `false`
  - `record_acceptance` (boolean): e.g. `false`
  - `acceptance_label` (string): e.g. `Preorder Terms Accepted`
- `cart` (object)
  - `allowed_items` (string): e.g. `mixed`
  - `error_message` (string): e.g. `Preorders must be purchased separately from regular items.`
- `order_quantity` (object)
  - `minimum` (any)
  - `maximum` (any)

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

## 200

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

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