Create a new selling plan

Create a new selling plan

post

Authorizations

ApiKeyAuth

X-Auth-TokenstringRequired

Header parameters

X-Auth-TokenstringRequired

API key for authentication

Body

application/json

Responses

201

Selling plan created successfully

application/json

idstringOptional

Unique identifier for the selling plan

namestringOptional

Display name of the selling plan

internal_namestringOptional

Internal name for the selling plan

enabledbooleanOptional

Whether the selling plan is enabled

billing_typestring · enumOptional

Type of billing for the selling plan

Possible values:

billing_atstring · date-time · nullableOptional

Exact billing time if billing_type is exact_time

billing_after_n_intervalsinteger · nullableOptional

Number of intervals after checkout to bill

billing_after_interval_typestring · enumOptional

Type of interval for billing

Possible values:

billing_checkout_charge_amountnumber · nullableOptional

Fixed amount to charge at checkout

billing_checkout_charge_percentagenumber · nullableOptional

Percentage to charge at checkout

billing_checkout_charge_typestring · enumOptional

Type of checkout charge

Possible values:

billing_titlestringOptional

Title for billing section

billing_descriptionstringOptional

Description for billing section

delivery_typestring · enumOptional

Type of delivery for the selling plan

Possible values:

delivery_atstring · date-time · nullableOptional

Exact delivery time if delivery_type is exact_time

delivery_after_n_intervalsinteger · nullableOptional

Number of intervals after checkout for delivery

delivery_after_interval_typestring · enumOptional

Type of interval for delivery

Possible values:

inventory_reserve_typestring · enumOptional

When to reserve inventory

Possible values:

inventory_providerstring · enumOptional

Inventory provider

Possible values:

pricing_typestring · enumOptional

Type of pricing discount

Possible values:

pricing_amountnumber · nullableOptional

Fixed discount amount

pricing_percentagenumber · nullableOptional

Percentage discount

quantity_limit_textstringOptional

Text to display for quantity limits

preorder_button_textstringOptional

Text for the preorder button

preorder_button_text_colorstringOptional

Text color for the preorder button

preorder_button_background_colorstringOptional

Background color for the preorder button

preorder_button_colors_enabledbooleanOptional

Whether custom colors are enabled for the preorder button

preorder_discounted_price_enabledbooleanOptional

Whether to show discounted price on the preorder button

preorder_button_descriptionstringOptional

Description text for the preorder button

preorder_button_description_background_colorstringOptional

Background color for the preorder button description

preorder_button_description_border_radiusstringOptional

Border radius for the preorder button description

preorder_button_description_quantity_limit_suffixstringOptional

Suffix text for quantity limit in button description

preorder_button_description_shipping_text_prefixstringOptional

Prefix text for shipping information in button description

preorder_button_description_show_quantity_limitbooleanOptional

Whether to show quantity limit in button description

preorder_button_description_show_shippingbooleanOptional

Whether to show shipping information in button description

preorder_button_description_text_colorstringOptional

Text color for the preorder button description

preorder_badge_enabledbooleanOptional

Whether preorder badge is enabled

preorder_badge_textstringOptional

Text for the preorder badge

preorder_badge_text_colorstringOptional

Text color for the preorder badge

preorder_badge_background_colorstringOptional

Background color for the preorder badge

preorder_shipping_textstringOptional

Shipping text specific to preorders

shipping_textstringOptional

Shipping information text

shipping_line_item_property_enabledbooleanOptional

Whether to enable shipping line item properties

shipping_applies_to_all_productsbooleanOptional

Whether shipping settings apply to all products

discount_textstringOptional

Discount information text

preorder_tagsstringOptional

Tags to apply to preorder items

product_variants_sourcestring · enumOptional

Source of product variants for this selling plan

Possible values:

product_variants_source_idinteger · nullableOptional

ID of the source (e.g., collection ID)

selling_plan_product_variants_countintegerOptional

Number of product variants associated with this selling plan

shopify_selling_plan_idinteger · nullableOptional

Shopify selling plan ID

shopify_selling_plan_group_idinteger · nullableOptional

Shopify selling plan group ID

use_shopify_selling_planbooleanOptional

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_widgetbooleanOptional

Whether to display the payment/billing widget on the product page

split_fulfillments_enabledbooleanOptional

Whether to enable split fulfillments for preorders. When enabled, preorders will be separted into its own fulfillment order.

require_preorder_acknowledgementbooleanOptional

Whether customers must accept terms and conditions before adding a preorder item to their cart.

preorder_acknowledgement_textstringOptional

The terms and conditions text that customers must acknowledge when require_preorder_acknowledgement is enabled.

allow_mixed_cartbooleanOptional

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_messagestringOptional

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 · nullableOptional

Minimum quantity required per order for preorder items. When set, customers must purchase at least this many units.

preorder_max_quantityinteger · nullableOptional

Maximum quantity allowed per order for preorder items. When set, customers cannot purchase more than this many units.

payment_line_item_property_enabledbooleanOptional

Whether to add payment information as a line item property (e.g., "Payment - Pay in full").

custom_line_item_property_textstring · nullableOptional

Custom text to add as a line item property for preorder items. Useful for adding custom order notes or metadata.

auto_collect_payment_on_fulfillmentbooleanOptional

Whether to automatically collect remaining payment when the order is fulfilled (for partial payment preorders).

hold_fulfillments_enabledbooleanOptional

Whether to automatically hold fulfillments for preorder items. When enabled, fulfillments will be held until manually released.

hold_fulfillments_reason_notestringOptional

The reason note displayed when fulfillments are held (when hold_fulfillments_enabled is true).

disable_button_until_acknowledgedbooleanOptional

Whether to disable the add to cart button until the customer acknowledges the preorder terms (when require_preorder_acknowledgement is true).

shop_idintegerOptional

Shop ID this selling plan belongs to

market_idinteger · nullableOptional

Market ID for multi-market stores

created_atstring · date-timeOptional

Timestamp when the selling plan was created

updated_atstring · date-timeOptional

Timestamp when the selling plan was last updated

discarded_atstring · date-time · nullableOptional

Timestamp when the selling plan was soft deleted

ongoing_jobbooleanOptional

Whether there is an ongoing job for this selling plan

shopify_variant_idsinteger[]Optional

List of Shopify variant IDs associated with this selling plan

401

Unauthorized

422

Validation errors

application/json

post

/preorders

HTTPcURLJavaScriptPython

POST /api/v1/external/preorders HTTP/1.1
Host: app.stoqapp.com
X-Auth-Token: text
Content-Type: application/json
Accept: */*
Content-Length: 2248

{
  "selling_plan": {
    "name": "text",
    "internal_name": "text",
    "enabled": true,
    "billing_type": "exact_time",
    "billing_at": "2026-02-27T16:29:49.484Z",
    "billing_after_n_intervals": 1,
    "billing_after_interval_type": "day",
    "billing_checkout_charge_amount": 1,
    "billing_checkout_charge_percentage": 1,
    "billing_checkout_charge_type": "percentage",
    "billing_title": "text",
    "billing_description": "text",
    "delivery_type": "anchor",
    "delivery_at": "2026-02-27T16:29:49.484Z",
    "delivery_after_n_intervals": 1,
    "delivery_after_interval_type": "day",
    "inventory_reserve_type": "on_sale",
    "inventory_provider": "stoq",
    "pricing_type": "percentage",
    "pricing_amount": 1,
    "pricing_percentage": 1,
    "quantity_limit_text": "text",
    "preorder_button_text": "text",
    "preorder_button_text_color": "text",
    "preorder_button_background_color": "text",
    "preorder_button_colors_enabled": true,
    "preorder_discounted_price_enabled": true,
    "preorder_button_description": "text",
    "preorder_button_description_background_color": "text",
    "preorder_button_description_border_radius": "text",
    "preorder_button_description_quantity_limit_suffix": "text",
    "preorder_button_description_shipping_text_prefix": "text",
    "preorder_button_description_show_quantity_limit": true,
    "preorder_button_description_show_shipping": true,
    "preorder_button_description_text_color": "text",
    "preorder_badge_enabled": true,
    "preorder_badge_text": "text",
    "preorder_badge_text_color": "text",
    "preorder_badge_background_color": "text",
    "preorder_shipping_text": "text",
    "shipping_text": "text",
    "shipping_line_item_property_enabled": true,
    "shipping_applies_to_all_products": true,
    "discount_text": "text",
    "preorder_tags": "text",
    "product_variants_source": "all",
    "product_variants_source_id": 1,
    "markets_enabled": true,
    "shopify_market_ids": [
      1
    ],
    "auto_collect_payment": true,
    "use_shopify_selling_plan": true,
    "enable_billing_widget": true,
    "split_fulfillments_enabled": true,
    "require_preorder_acknowledgement": true,
    "preorder_acknowledgement_text": "text",
    "allow_mixed_cart": true,
    "mixed_cart_error_message": "text",
    "preorder_min_quantity": 1,
    "preorder_max_quantity": 1,
    "payment_line_item_property_enabled": true,
    "custom_line_item_property_text": "text",
    "auto_collect_payment_on_fulfillment": true,
    "hold_fulfillments_enabled": true,
    "hold_fulfillments_reason_note": "text",
    "disable_button_until_acknowledged": true
  }
}

{
  "id": "text",
  "name": "text",
  "internal_name": "text",
  "enabled": true,
  "billing_type": "exact_time",
  "billing_at": "2026-02-27T16:29:49.484Z",
  "billing_after_n_intervals": 1,
  "billing_after_interval_type": "day",
  "billing_checkout_charge_amount": 1,
  "billing_checkout_charge_percentage": 1,
  "billing_checkout_charge_type": "percentage",
  "billing_title": "text",
  "billing_description": "text",
  "delivery_type": "anchor",
  "delivery_at": "2026-02-27T16:29:49.484Z",
  "delivery_after_n_intervals": 1,
  "delivery_after_interval_type": "day",
  "inventory_reserve_type": "on_sale",
  "inventory_provider": "stoq",
  "pricing_type": "percentage",
  "pricing_amount": 1,
  "pricing_percentage": 1,
  "quantity_limit_text": "text",
  "preorder_button_text": "text",
  "preorder_button_text_color": "text",
  "preorder_button_background_color": "text",
  "preorder_button_colors_enabled": true,
  "preorder_discounted_price_enabled": true,
  "preorder_button_description": "text",
  "preorder_button_description_background_color": "text",
  "preorder_button_description_border_radius": "text",
  "preorder_button_description_quantity_limit_suffix": "text",
  "preorder_button_description_shipping_text_prefix": "text",
  "preorder_button_description_show_quantity_limit": true,
  "preorder_button_description_show_shipping": true,
  "preorder_button_description_text_color": "text",
  "preorder_badge_enabled": true,
  "preorder_badge_text": "text",
  "preorder_badge_text_color": "text",
  "preorder_badge_background_color": "text",
  "preorder_shipping_text": "text",
  "shipping_text": "text",
  "shipping_line_item_property_enabled": true,
  "shipping_applies_to_all_products": true,
  "discount_text": "text",
  "preorder_tags": "text",
  "product_variants_source": "all",
  "product_variants_source_id": 1,
  "selling_plan_product_variants_count": 1,
  "shopify_selling_plan_id": 1,
  "shopify_selling_plan_group_id": 1,
  "use_shopify_selling_plan": true,
  "enable_billing_widget": true,
  "split_fulfillments_enabled": true,
  "require_preorder_acknowledgement": true,
  "preorder_acknowledgement_text": "text",
  "allow_mixed_cart": true,
  "mixed_cart_error_message": "text",
  "preorder_min_quantity": 1,
  "preorder_max_quantity": 1,
  "payment_line_item_property_enabled": true,
  "custom_line_item_property_text": "text",
  "auto_collect_payment_on_fulfillment": true,
  "hold_fulfillments_enabled": true,
  "hold_fulfillments_reason_note": "text",
  "disable_button_until_acknowledged": true,
  "shop_id": 1,
  "market_id": 1,
  "created_at": "2026-02-27T16:29:49.484Z",
  "updated_at": "2026-02-27T16:29:49.484Z",
  "discarded_at": "2026-02-27T16:29:49.484Z",
  "ongoing_job": true,
  "shopify_variant_ids": [
    1
  ]
}