Update a selling plan

API v1 is the older API. It still works, but new integrations should use API v2. Migrating from v1 to v2

PUT/external/preorders/{id}

Costs 2 rate-limit points · Rate limits

Update an existing preorder selling plan. Supply a selling_plan object with the fields you want to change; omitted fields are left unchanged. Returns the updated selling plan, or 422 with validation errors if the changes are invalid.

Path parameters

idstringRequired
Selling plan ID

Headers

X-Auth-TokenstringRequired
API key for authentication

Request body

selling_planobject
Input schema for creating or updating selling plans
Show 68 child attributesHide child attributes
- namestring
  Display name of the selling plan
- internal_namestring
  Internal name for the selling plan
- enabledboolean
  Whether the selling plan is enabled
- billing_typestring
  Type of billing for the selling plan
  One of exact_timeno_remaining_balancetime_after_checkout
- billing_atstring
  Exact billing time if billing_type is exact_time
- billing_after_n_intervalsinteger
  Number of intervals after checkout to bill
- billing_after_interval_typestring
  Type of interval for billing
  One of day
- billing_checkout_charge_amountnumber
  Fixed amount to charge at checkout
- billing_checkout_charge_percentagenumber
  Percentage to charge at checkout
- billing_checkout_charge_typestring
  Type of checkout charge
  One of percentageprice
- billing_titlestring
  Title for billing section
- billing_descriptionstring
  Description for billing section
- delivery_typestring
  Type of delivery for the selling plan
  One of anchorasapexact_timeunknown
- delivery_atstring
  Exact delivery time if delivery_type is exact_time
- delivery_after_n_intervalsinteger
  Number of intervals after checkout for delivery
- delivery_after_interval_typestring
  Type of interval for delivery
  One of day
- inventory_reserve_typestring
  When to reserve inventory
  One of on_saleon_fulfillment
- inventory_providerstring
  Inventory provider
  One of stoqshopify
- pricing_typestring
  Type of pricing discount
  One of percentagepricefixed_amountno_discount
- pricing_amountnumber
  Fixed discount amount
- pricing_percentagenumber
  Percentage discount
- quantity_limit_textstring
  Text to display for quantity limits
- preorder_button_textstring
  Text for the preorder button
- preorder_button_text_colorstring
  Text color for the preorder button
- preorder_button_background_colorstring
  Background color for the preorder button
- preorder_button_colors_enabledboolean
  Whether custom colors are enabled for the preorder button
- preorder_discounted_price_enabledboolean
  Whether to show discounted price on the preorder button
- preorder_button_descriptionstring
  Description text for the preorder button
- preorder_button_description_background_colorstring
  Background color for the preorder button description
- preorder_button_description_border_radiusstring
  Border radius for the preorder button description
- preorder_button_description_quantity_limit_suffixstring
  Suffix text for quantity limit in button description
- preorder_button_description_shipping_text_prefixstring
  Prefix text for shipping information in button description
- preorder_button_description_show_quantity_limitboolean
  Whether to show quantity limit in button description
- preorder_button_description_show_shippingboolean
  Whether to show shipping information in button description
- preorder_button_description_text_colorstring
  Text color for the preorder button description
- preorder_badge_enabledboolean
  Whether preorder badge is enabled
- preorder_badge_textstring
  Text for the preorder badge
- preorder_badge_text_colorstring
  Text color for the preorder badge
- preorder_badge_background_colorstring
  Background color for the preorder badge
- preorder_shipping_textstring
  Shipping text specific to preorders
- shipping_textstring
  Shipping information text
- shipping_line_item_property_enabledboolean
  Whether to enable shipping line item properties
- shipping_applies_to_all_productsboolean
  Whether shipping settings apply to all products
- discount_textstring
  Discount information text
- preorder_tagsstring
  Tags to apply to preorder items
- product_variants_sourcestring
  Source of product variants for this selling plan
  One of allcollectioncustom
- product_variants_source_idinteger
  ID of the source (e.g., collection ID)
- markets_enabledboolean
  Whether market-specific settings are enabled for this selling plan
- shopify_market_idsarray of integers
  List of Shopify market IDs where this selling plan is available. Required if markets_enabled is true.
- auto_collect_paymentboolean
  Whether to automatically collect payment when the order is ready to fulfill
- use_shopify_selling_planboolean
  Whether to use Shopify's native selling plan functionality for this preorder offer. When true, this enables advanced selling plan features in Shopify.
- enable_billing_widgetboolean
  Whether to display the payment/billing widget on the product page
- split_fulfillments_enabledboolean
  Whether to enable split fulfillments for preorders. When enabled, preorder items can be shipped separately from regular items in the same order.
- split_orders_enabledboolean
  Whether to move preorder items into a separate Shopify order after checkout ("Move preorder items to a separate order"). In-stock items stay on the original order. Only one of split_orders_enabled, split_fulfillments_enabled and hold_fulfillments_enabled can be on: turning this on turns the others off. It also turns off use_shopify_selling_plan, so deposits and partial payments aren't available.
- split_orders_per_variantboolean
  Only applies when split_orders_enabled is on. false (default): all preorder items from this offer in a checkout move to one new order. true: each preorder variant from this offer moves to its own new order, so products sharing one offer still ship separately.
- split_orders_per_ship_dateboolean
  Only applies when split_orders_enabled is on. true: preorder items from this offer that ship on the same date (the same batch, or the same shipping text) move to one new order, and each other ship date gets its own. Turning it on turns split_orders_per_variant off, and the other way round.
- require_preorder_acknowledgementboolean
  Whether customers must accept terms and conditions before adding a preorder item to their cart.
- preorder_acknowledgement_textstring
  The terms and conditions text that customers must acknowledge when require_preorder_acknowledgement is enabled.
- allow_mixed_cartboolean
  Whether to allow customers to mix preorder items with regular items in the same cart. When false, customers must purchase preorders separately.
- mixed_cart_error_messagestring
  Error message displayed to customers when they attempt to mix preorder and regular items in their cart (when allow_mixed_cart is false).
- preorder_min_quantityinteger
  Minimum quantity required per order for preorder items. When set, customers must purchase at least this many units.
- preorder_max_quantityinteger
  Maximum quantity allowed per order for preorder items. When set, customers cannot purchase more than this many units.
- payment_line_item_property_enabledboolean
  Whether to add payment information as a line item property (e.g., "Payment - Pay in full").
- custom_line_item_property_textstring
  Custom text to add as a line item property for preorder items. Useful for adding custom order notes or metadata.
- auto_collect_payment_on_fulfillmentboolean
  Whether to automatically collect remaining payment when the order is fulfilled (for partial payment preorders).
- hold_fulfillments_enabledboolean
  Whether to automatically hold fulfillments for preorder items. When enabled, fulfillments will be held until manually released.
- hold_fulfillments_reason_notestring
  The reason note displayed when fulfillments are held (when hold_fulfillments_enabled is true).
- disable_button_until_acknowledgedboolean
  Whether to disable the add to cart button until the customer acknowledges the preorder terms (when require_preorder_acknowledgement is true).

Returns

The preorder object.

Errors

401

Unauthorized

404

Selling plan not found

422

Validation errors

PUT/external/preorders/{id}

curl -X PUT "https://app.stoqapp.com/api/v1/external/preorders/79b44c6c-ebc7-41d4-8a1b-573d7c693454" \
  -H "X-Auth-Token: $STOQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "selling_plan": {
      "enabled": false,
      "preorder_button_text": "Coming soon"
    }
  }'

const res = await fetch("https://app.stoqapp.com/api/v1/external/preorders/79b44c6c-ebc7-41d4-8a1b-573d7c693454", {
  method: "PUT",
  headers: {
    "X-Auth-Token": process.env.STOQ_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "selling_plan": {
      "enabled": false,
      "preorder_button_text": "Coming soon"
    }
  }),
});
const data = await res.json();

import os
import requests

res = requests.put(
    "https://app.stoqapp.com/api/v1/external/preorders/79b44c6c-ebc7-41d4-8a1b-573d7c693454",
    headers={"X-Auth-Token": os.environ["STOQ_API_KEY"]},
    json={
        "selling_plan": {
            "enabled": False,
            "preorder_button_text": "Coming soon"
        }
    },
)
data = res.json()

require "net/http"
require "json"

uri = URI("https://app.stoqapp.com/api/v1/external/preorders/79b44c6c-ebc7-41d4-8a1b-573d7c693454")
req = Net::HTTP::Put.new(uri, "X-Auth-Token" => ENV["STOQ_API_KEY"], "Content-Type" => "application/json")
req.body = {
  selling_plan: {
    enabled: false,
    preorder_button_text: "Coming soon"
  }
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)

Response

{
  "id": "79b44c6c-ebc7-41d4-8a1b-573d7c693454",
  "name": "Summer Preorder",
  "internal_name": "summer-2026",
  "enabled": false,
  "billing_type": "time_after_checkout",
  "billing_checkout_charge_type": "percentage",
  "billing_checkout_charge_percentage": 20,
  "delivery_type": "asap",
  "pricing_type": "no_discount",
  "preorder_button_text": "Coming soon",
  "preorder_badge_enabled": true,
  "preorder_badge_text": "Preorder",
  "selling_plan_product_variants_count": 12,
  "shopify_selling_plan_id": 645123456,
  "shopify_selling_plan_group_id": 9912345,
  "shop_id": 43,
  "created_at": "2026-06-20T10:00:00Z",
  "updated_at": "2026-06-24T08:30:00Z",
  "ongoing_job": false,
  "shopify_variant_ids": [
    43900910010503,
    43900910010999
  ]
}