Update limits
API v2 is in public beta: endpoints and fields can change before general availability. See the changelog
/preorders/offers/{id}/limitsCosts 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
idstringRequiredThe offer's ID, from
GET /preorders/offers.
Headers
Idempotency-KeystringA 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 (422idempotency_key_reused); a retry while the first is still running gets 409idempotency_key_in_progress. Keys are per store. Server errors and rate limits are not kept, so their retry runs.
Request body
default_per_variantintegerSame 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_stylestringHow customers see the limit: none, disclaimer (remaining units in the disclaimer) or progress_bar.
One ofnonedisclaimerprogress_barlimit_textstringQuantity Limit -- the text printed with the remaining-units count.
show_iconsbooleanUse icons for quantity & shipping details on the widget.
progress_barobjectLook and text of the storefront progress bar toward the quantity limit.
Show 7 child attributesHide child attributes
progress_textstringProgress bar text.
fill_colorstringThe bar's Fill color. Hex.
background_colorstringThe bar's Background color. Hex.
box_background_colorstringBox background -- the colour behind the bar. Hex; null falls back to the disclaimer background.
text_colorstringThe bar's Text color. Hex.
border_radiusintegerThe bar's corner radius in pixels.
show_percentagebooleanShow percentage next to progress bar.
order_tagsarray of anysTags Shopify puts on orders containing this offer. A list replaces them; {"$add": [...], "$remove": [...]} edits them. Blanks and duplicates are dropped; null or [] clears.
termsobjectThe terms checkbox shoppers accept before preordering.
Show 5 child attributesHide child attributes
require_acceptancebooleanRequire customer to accept terms before preordering.
terms_textstringAcknowledgement text -- the wording beside the terms checkbox.
disable_button_until_acceptedbooleanDisable button until terms are accepted.
record_acceptancebooleanRecord when customer accepted terms, as a cart line property.
acceptance_labelstringLabel for that recorded-acceptance cart line property.
cartobjectWhether a cart can mix preorder and regular items, and the error shown when it cannot.
Show 2 child attributesHide child attributes
allowed_itemsstringmixed 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 ofmixedpreorder_onlyerror_messagestringMixed cart error message -- shown when a blocked mixed cart reaches checkout.
order_quantityobjectMinimum and maximum quantity per order.
Show 2 child attributesHide child attributes
minimuminteger, nullableMinimum quantity per order. null removes it.
maximuminteger, nullableMaximum quantity per order. null removes the cap.
localestringLanguage 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_variantinteger, nullableThe same quantity limit for every variant, copied onto each one when set. Null when there is none.
display_stylestringHow shoppers see the limit: none, disclaimer (remaining units in the disclaimer line) or progress_bar.
One ofnonedisclaimerprogress_barlimit_textstringText printed with the remaining-units count.
show_iconsbooleanWhether the widget uses icons for quantity and shipping details.
progress_barobjectLook and text of the storefront progress bar toward the quantity limit.
Show 7 child attributesHide child attributes
progress_textstringProgress bar text.
fill_colorstringBar fill color, as hex.
background_colorstringBar background color, as hex.
box_background_colorstring, nullableColor behind the bar, as hex. Null uses the disclaimer background.
text_colorstringBar text color, as hex.
border_radiusintegerBar corner radius in pixels.
show_percentagebooleanWhether a percentage shows next to the bar.
order_tagsarray of stringsTags Shopify puts on orders containing this offer.
termsobjectThe terms checkbox shoppers accept before preordering.
Show 5 child attributesHide child attributes
require_acceptancebooleanWhether shoppers must accept the terms before preordering.
terms_textstringWording beside the terms checkbox.
disable_button_until_acceptedbooleanWhether the button stays disabled until the terms are accepted.
record_acceptancebooleanWhether acceptance is recorded as a cart line property.
acceptance_labelstringLabel of the cart line property that records acceptance.
cartobjectWhether a cart can mix preorder and regular items, and the error shown when it cannot.
Show 2 child attributesHide child attributes
allowed_itemsstringmixed lets a cart hold preorder and regular items; preorder_only blocks the mix at checkout.
One ofmixedpreorder_onlyerror_messagestringError shown when a blocked mixed cart reaches checkout.
order_quantityobjectMinimum and maximum quantity per order.
Show 2 child attributesHide child attributes
minimuminteger, nullableMinimum quantity per order. Null when there is none.
maximuminteger, nullableMaximum quantity per order. Null when there is none.
Errors
plan_requiredThe change uses a feature that is only available on a paid STOQ plan. Connecting a paid-only integration returns 403; a write that sets paid-only fields returns 422 and saves nothing.
not_foundThe path is valid but nothing with that id exists in this store.
conflictThe request is well formed, but the resource's current state does not allow it.
job_in_progressAn earlier bulk change on the same resource is still running.
idempotency_key_in_progressAn earlier request with the same Idempotency-Key is still running. Wait, then resend the same request with the same key.
invalid_paramsOne or more fields failed the action's schema.
quantity_limit_reachedEvery targeted variant has reached its preorder quantity limit, so STOQ keeps it from selling.
Any request can also fail with auth_invalid (401) or rate_limited (429).
Every error has the same shape: see Errors and the list of error codes.
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){
"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
}
]
}