Skip to content

Update limits

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

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

    Look and text of the storefront progress bar toward the quantity limit.

    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

    The terms checkbox shoppers accept before preordering.

    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

    Whether a cart can mix preorder and regular items, and the error shown when it cannot.

    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

    Minimum and maximum quantity per order.

    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_variantinteger, nullable

    The same quantity limit for every variant, copied onto each one when set. Null when there is none.

  • display_stylestring

    How shoppers see the limit: none, disclaimer (remaining units in the disclaimer line) or progress_bar.

    One of nonedisclaimerprogress_bar
  • limit_textstring

    Text printed with the remaining-units count.

  • show_iconsboolean

    Whether the widget uses icons for quantity and shipping details.

  • progress_barobject

    Look and text of the storefront progress bar toward the quantity limit.

    Show 7 child attributesHide child attributes
    • progress_textstring

      Progress bar text.

    • fill_colorstring

      Bar fill color, as hex.

    • background_colorstring

      Bar background color, as hex.

    • box_background_colorstring, nullable

      Color behind the bar, as hex. Null uses the disclaimer background.

    • text_colorstring

      Bar text color, as hex.

    • border_radiusinteger

      Bar corner radius in pixels.

    • show_percentageboolean

      Whether a percentage shows next to the bar.

  • order_tagsarray of strings

    Tags Shopify puts on orders containing this offer.

  • termsobject

    The terms checkbox shoppers accept before preordering.

    Show 5 child attributesHide child attributes
    • require_acceptanceboolean

      Whether shoppers must accept the terms before preordering.

    • terms_textstring

      Wording beside the terms checkbox.

    • disable_button_until_acceptedboolean

      Whether the button stays disabled until the terms are accepted.

    • record_acceptanceboolean

      Whether acceptance is recorded as a cart line property.

    • acceptance_labelstring

      Label of the cart line property that records acceptance.

  • cartobject

    Whether a cart can mix preorder and regular items, and the error shown when it cannot.

    Show 2 child attributesHide child attributes
    • allowed_itemsstring

      mixed lets a cart hold preorder and regular items; preorder_only blocks the mix at checkout.

      One of mixedpreorder_only
    • error_messagestring

      Error shown when a blocked mixed cart reaches checkout.

  • order_quantityobject

    Minimum and maximum quantity per order.

    Show 2 child attributesHide child attributes
    • minimuminteger, nullable

      Minimum quantity per order. Null when there is none.

    • maximuminteger, nullable

      Maximum quantity per order. Null when there is none.

Errors

403
plan_required

The 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.

404
not_found

The path is valid but nothing with that id exists in this store.

409
conflict

The request is well formed, but the resource's current state does not allow it.

409
job_in_progress

An earlier bulk change on the same resource is still running.

409
idempotency_key_in_progress

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

422
invalid_params

One or more fields failed the action's schema.

422
quantity_limit_reached

Every 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.

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