Create a new selling plan
LegacyAPI v1 is the older API. It still works and is supported, but new integrations should use API v2. Migrating from v1 to v2
const url = 'https://app.stoqapp.com/api/v1/external/preorders';const options = { method: 'POST', headers: {'X-Auth-Token': '<X-Auth-Token>', 'Content-Type': 'application/json'}, body: '{"selling_plan":{"name":"Summer Preorder","internal_name":"summer-2026","enabled":true,"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":"Preorder now","preorder_badge_enabled":true,"preorder_badge_text":"Preorder","product_variants_source":"custom"}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://app.stoqapp.com/api/v1/external/preorders \ --header 'Content-Type: application/json' \ --header 'X-Auth-Token: <X-Auth-Token>' \ --data '{ "selling_plan": { "name": "Summer Preorder", "internal_name": "summer-2026", "enabled": true, "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": "Preorder now", "preorder_badge_enabled": true, "preorder_badge_text": "Preorder", "product_variants_source": "custom" } }'Create a new preorder selling plan. The selling_plan object defines billing, delivery, discount, button, badge, and fulfillment behavior; only the fields you set are applied and the rest fall back to defaults. Returns the created selling plan, including its STOQ ID, on success.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”API key for authentication
Request Bodyrequired
Section titled “Request Bodyrequired”object
Input schema for creating or updating selling plans
object
Display name of the selling plan
Internal name for the selling plan
Whether the selling plan is enabled
Type of billing for the selling plan
Exact billing time if billing_type is exact_time
Number of intervals after checkout to bill
Type of interval for billing
Fixed amount to charge at checkout
Percentage to charge at checkout
Type of checkout charge
Title for billing section
Description for billing section
Type of delivery for the selling plan
Exact delivery time if delivery_type is exact_time
Number of intervals after checkout for delivery
Type of interval for delivery
When to reserve inventory
Inventory provider
Type of pricing discount
Fixed discount amount
Percentage discount
Text to display for quantity limits
Text for the preorder button
Text color for the preorder button
Background color for the preorder button
Whether custom colors are enabled for the preorder button
Whether to show discounted price on the preorder button
Description text for the preorder button
Background color for the preorder button description
Border radius for the preorder button description
Suffix text for quantity limit in button description
Prefix text for shipping information in button description
Whether to show quantity limit in button description
Whether to show shipping information in button description
Text color for the preorder button description
Whether preorder badge is enabled
Text for the preorder badge
Text color for the preorder badge
Background color for the preorder badge
Shipping text specific to preorders
Shipping information text
Whether to enable shipping line item properties
Whether shipping settings apply to all products
Discount information text
Tags to apply to preorder items
Source of product variants for this selling plan
ID of the source (e.g., collection ID)
Whether market-specific settings are enabled for this selling plan
List of Shopify market IDs where this selling plan is available. Required if markets_enabled is true.
Whether to automatically collect payment when the order is ready to fulfill
Whether to use Shopify’s native selling plan functionality for this preorder offer. When true, this enables advanced selling plan features in Shopify.
Whether to display the payment/billing widget on the product page
Whether to enable split fulfillments for preorders. When enabled, preorder items can be shipped separately from regular items in the same order.
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.
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.
Whether customers must accept terms and conditions before adding a preorder item to their cart.
The terms and conditions text that customers must acknowledge when require_preorder_acknowledgement is enabled.
Whether to allow customers to mix preorder items with regular items in the same cart. When false, customers must purchase preorders separately.
Error message displayed to customers when they attempt to mix preorder and regular items in their cart (when allow_mixed_cart is false).
Minimum quantity required per order for preorder items. When set, customers must purchase at least this many units.
Maximum quantity allowed per order for preorder items. When set, customers cannot purchase more than this many units.
Whether to add payment information as a line item property (e.g., “Payment - Pay in full”).
Custom text to add as a line item property for preorder items. Useful for adding custom order notes or metadata.
Whether to automatically collect remaining payment when the order is fulfilled (for partial payment preorders).
Whether to automatically hold fulfillments for preorder items. When enabled, fulfillments will be held until manually released.
The reason note displayed when fulfillments are held (when hold_fulfillments_enabled is true).
Whether to disable the add to cart button until the customer acknowledges the preorder terms (when require_preorder_acknowledgement is true).
Example
{ "selling_plan": { "name": "Summer Preorder", "internal_name": "summer-2026", "enabled": true, "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": "Preorder now", "preorder_badge_enabled": true, "preorder_badge_text": "Preorder", "product_variants_source": "custom" }}Responses
Section titled “Responses”Selling plan created successfully
object
Unique identifier for the selling plan
Display name of the selling plan
Internal name for the selling plan
Whether the selling plan is enabled
Type of billing for the selling plan
Exact billing time if billing_type is exact_time
Number of intervals after checkout to bill
Type of interval for billing
Fixed amount to charge at checkout
Percentage to charge at checkout
Type of checkout charge
Title for billing section
Description for billing section
Type of delivery for the selling plan
Exact delivery time if delivery_type is exact_time
Number of intervals after checkout for delivery
Type of interval for delivery
When to reserve inventory
Inventory provider
Type of pricing discount
Fixed discount amount
Percentage discount
Text to display for quantity limits
Text for the preorder button
Text color for the preorder button
Background color for the preorder button
Whether custom colors are enabled for the preorder button
Whether to show discounted price on the preorder button
Description text for the preorder button
Background color for the preorder button description
Border radius for the preorder button description
Suffix text for quantity limit in button description
Prefix text for shipping information in button description
Whether to show quantity limit in button description
Whether to show shipping information in button description
Text color for the preorder button description
Whether preorder badge is enabled
Text for the preorder badge
Text color for the preorder badge
Background color for the preorder badge
Shipping text specific to preorders
Shipping information text
Whether to enable shipping line item properties
Whether shipping settings apply to all products
Discount information text
Tags to apply to preorder items
Source of product variants for this selling plan
ID of the source (e.g., collection ID)
Number of product variants associated with this selling plan
Shopify selling plan ID
Shopify selling plan group ID
Whether to use Shopify’s native selling plan functionality for this preorder offer. When true, this enables advanced selling plan features in Shopify.
Whether to display the payment/billing widget on the product page
Whether to enable split fulfillments for preorders. When enabled, preorders will be separted into its own fulfillment order.
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.
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.
Whether customers must accept terms and conditions before adding a preorder item to their cart.
The terms and conditions text that customers must acknowledge when require_preorder_acknowledgement is enabled.
Whether to allow customers to mix preorder items with regular items in the same cart. When false, customers must purchase preorders separately.
Error message displayed to customers when they attempt to mix preorder and regular items in their cart (when allow_mixed_cart is false).
Minimum quantity required per order for preorder items. When set, customers must purchase at least this many units.
Maximum quantity allowed per order for preorder items. When set, customers cannot purchase more than this many units.
Whether to add payment information as a line item property (e.g., “Payment - Pay in full”).
Custom text to add as a line item property for preorder items. Useful for adding custom order notes or metadata.
Whether to automatically collect remaining payment when the order is fulfilled (for partial payment preorders).
Whether to automatically hold fulfillments for preorder items. When enabled, fulfillments will be held until manually released.
The reason note displayed when fulfillments are held (when hold_fulfillments_enabled is true).
Whether to disable the add to cart button until the customer acknowledges the preorder terms (when require_preorder_acknowledgement is true).
Shop ID this selling plan belongs to
Market ID for multi-market stores
Timestamp when the selling plan was created
Timestamp when the selling plan was last updated
Timestamp when the selling plan was soft deleted
Whether there is an ongoing job for this selling plan
List of Shopify variant IDs associated with this selling plan
Example
{ "id": "79b44c6c-ebc7-41d4-8a1b-573d7c693454", "name": "Summer Preorder", "internal_name": "summer-2026", "enabled": true, "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": "Preorder now", "preorder_badge_enabled": true, "preorder_badge_text": "Preorder", "selling_plan_product_variants_count": 0, "shopify_selling_plan_id": null, "shopify_selling_plan_group_id": null, "shop_id": 43, "created_at": "2026-06-20T10:00:00Z", "updated_at": "2026-06-24T08:30:00Z", "ongoing_job": false, "shopify_variant_ids": []}Unauthorized
Validation errors
object
object
Example generated
{ "errors": {}}Thanks for letting us know.
Still stuck? Ask Quinn or chat with support