Update a limit on an offer

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

PATCH/preorders/offers/{id}/limits

Costs 2 rate-limit points · Rate 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.

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.

Also searched asedit checkoutchange checkout settingsmodify checkoutenable termsrequire acknowledgementshow terms checkboxturn on termsrequire termsdisable termshide terms checkboxremove terms requirementturn off termsstop requiring termsenable disable until acknowledgedrequire acknowledgement before buyinglock button until terms acceptedgrey out button until terms checkeddisable button until termsdisable disable until acknowledgeddon't lock button on termsallow buying without acknowledging firstkeep button enabled before termsinclude terms in line item propertiesrecord terms acceptance on orderadd acknowledgement to line itemsshow terms accepted on orderrecord terms acceptanceallow mixed cartpermit mixed cartenable mixed cartlet preorders mix with regular itemsblock mixed cartdisable mixed cartprevent mixed cartforce separate checkoutblock mixed cartsdont allow mixed cartsadd order tagadd tag to preorder ordersappend order tagremove order tagdelete order tagdrop order tagmixed cart ordersset mixed cart error messagechange mixed cart messageset mixed cart warningcustomize mixed cart errorset order tagsreplace order tagschange order tagsset tags on preorder ordersaccept termsterms checkboxset terms textchange terms textupdate termschange acknowledgement textset fine printedit limitschange limitsmodify quantity limitsenable show remainingshow remaining unitsshow stock leftdisplay quantity remainingdisable show remaininghide remaining unitshide stock leftstop showing quantityhide progress barshow iconsenable iconshide iconsdisable iconsicons for detailsset maximum per orderset max quantitymaximum order quantityset order limitset minimum per orderset min quantityminimum order quantityset order minimumprogress barshow counterstock countershow limit as countercrowdfunding barunits left barquantity limit textlimit textunits left textchange limit message

Path parameters

idstringRequired

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

default_per_variantinteger
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_stylestring
How customers see the limit: none, disclaimer (remaining units in the disclaimer) or progress_bar.
One of nonedisclaimerprogress_bar
limit_textstring
Quantity Limit -- the text printed with the remaining-units count.
show_iconsboolean
Use icons for quantity & shipping details on the widget.
progress_barobject
Show 7 child attributesHide child attributes
- progress_textstring
  Progress bar text.
- fill_colorstring
  The bar's Fill color. Hex.
- background_colorstring
  The bar's Background color. Hex.
- box_background_colorstring
  Box background -- the colour behind the bar. Hex; null falls back to the disclaimer background.
- text_colorstring
  The bar's Text color. Hex.
- border_radiusinteger
  The bar's corner radius in pixels.
- show_percentageboolean
  Show percentage next to progress bar.
order_tagsarray 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.
termsobject
Show 5 child attributesHide child attributes
- require_acceptanceboolean
  Require customer to accept terms before preordering.
- terms_textstring
  Acknowledgement text -- the wording beside the terms checkbox.
- disable_button_until_acceptedboolean
  Disable button until terms are accepted.
- record_acceptanceboolean
  Record when customer accepted terms, as a cart line property.
- acceptance_labelstring
  Label for that recorded-acceptance cart line property.
cartobject
Show 2 child attributesHide child attributes
- allowed_itemsstring
  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 mixedpreorder_only
- error_messagestring
  Mixed cart error message -- shown when a blocked mixed cart reaches checkout.
order_quantityobject
Show 2 child attributesHide child attributes
- minimuminteger, nullable
  Minimum quantity per order. null removes it.
- maximuminteger, nullable
  Maximum quantity per order. null removes the cap.
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

default_per_variantany
display_stylestring
Example: progress_bar
limit_textstring
Example: {{ quantity }} units available for preorder
show_iconsboolean
Example: true
progress_barobject
Show 7 child attributesHide child attributes
- progress_textstring
  Example: {{ sold }} of {{ total }} claimed
- fill_colorstring
  Example: #ffffff
- background_colorstring
  Example: #e5e5e5
- box_background_colorany
- text_colorstring
  Example: #ffffff
- border_radiusinteger
  Example: 4
- show_percentageboolean
  Example: false
order_tagsarray of strings
termsobject
Show 5 child attributesHide child attributes
- require_acceptanceboolean
  Example: true
- terms_textstring
  Example: I acknowledge and agree to the preorder terms and conditi…
- disable_button_until_acceptedboolean
  Example: false
- record_acceptanceboolean
  Example: false
- acceptance_labelstring
  Example: Preorder Terms Accepted
cartobject
Show 2 child attributesHide child attributes
- allowed_itemsstring
  Example: mixed
- error_messagestring
  Example: Preorders must be purchased separately from regular items.
order_quantityobject
Show 2 child attributesHide child attributes
- minimumany
- maximumany

Errors

401

Missing or invalid X-Auth-Token.

404

The resource does not exist for this shop, or the action path is not registered.

409

An earlier request with the same Idempotency-Key is still running. Wait, then resend the same request with the same key.

422

Invalid fields: one details entry per field error, its path the canonical section path. Nothing was saved.

429

Rate limited: cost-weighted per token (read 1, write 2; 360 points / 60s). Check Retry-After.

Every error has the same shape: see Errors.

PATCH/preorders/offers/{id}/limits

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

const res = await fetch("https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/limits", {
  method: "PATCH",
  headers: {
    "X-Auth-Token": process.env.STOQ_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "display_style": "progress_bar",
    "order_tags": {
      "$add": [
        "vip"
      ]
    },
    "terms": {
      "require_acceptance": true
    }
  }),
});
const data = await res.json();

import os
import requests

res = requests.patch(
    "https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/limits",
    headers={"X-Auth-Token": os.environ["STOQ_API_KEY"]},
    json={
        "display_style": "progress_bar",
        "order_tags": {
            "$add": [
                "vip"
            ]
        },
        "terms": {
            "require_acceptance": True
        }
    },
)
data = res.json()

require "net/http"
require "json"

uri = URI("https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/limits")
req = Net::HTTP::Patch.new(uri, "X-Auth-Token" => ENV["STOQ_API_KEY"], "Content-Type" => "application/json")
req.body = {
  display_style: "progress_bar",
  order_tags: {
    "$add" => [
      "vip"
    ]
  },
  terms: {
    require_acceptance: true
  }
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)

Response

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

{
  "errors": [
    "Invalid API key"
  ],
  "code": "auth_invalid",
  "details": [
    {
      "code": "auth_invalid",
      "message": "Invalid API key",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}

{
  "errors": [
    "Offer not found"
  ],
  "code": "not_found",
  "details": [
    {
      "code": "not_found",
      "message": "Offer not found",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}

{
  "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
    }
  ]
}

{
  "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"
      }
    }
  ]
}

{
  "errors": [
    "Rate limit exceeded"
  ],
  "code": "rate_limited",
  "details": [
    {
      "code": "rate_limited",
      "message": "Rate limit exceeded",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}