---
title: "Create a new selling plan"
description: "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 th"
url: https://docs.stoqapp.com/v1/preorders/create-a-new-selling-plan/
api: "API v1 (legacy)"
method: POST
path: "/external/preorders"
---

# Create a new selling plan

`POST https://app.stoqapp.com/api/v1/external/preorders`

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.

## Headers

- `X-Auth-Token` (string, required): API key for authentication

## Request body

- `selling_plan` (object): Input schema for creating or updating selling plans
  - `name` (string): Display name of the selling plan
  - `internal_name` (string): Internal name for the selling plan
  - `enabled` (boolean): Whether the selling plan is enabled
  - `billing_type` (string): Type of billing for the selling plan One of: `exact_time`, `no_remaining_balance`, `time_after_checkout`.
  - `billing_at` (string): Exact billing time if billing_type is exact_time
  - `billing_after_n_intervals` (integer): Number of intervals after checkout to bill
  - `billing_after_interval_type` (string): Type of interval for billing One of: `day`.
  - `billing_checkout_charge_amount` (number): Fixed amount to charge at checkout
  - `billing_checkout_charge_percentage` (number): Percentage to charge at checkout
  - `billing_checkout_charge_type` (string): Type of checkout charge One of: `percentage`, `price`.
  - `billing_title` (string): Title for billing section
  - `billing_description` (string): Description for billing section
  - `delivery_type` (string): Type of delivery for the selling plan One of: `anchor`, `asap`, `exact_time`, `unknown`.
  - `delivery_at` (string): Exact delivery time if delivery_type is exact_time
  - `delivery_after_n_intervals` (integer): Number of intervals after checkout for delivery
  - `delivery_after_interval_type` (string): Type of interval for delivery One of: `day`.
  - `inventory_reserve_type` (string): When to reserve inventory One of: `on_sale`, `on_fulfillment`.
  - `inventory_provider` (string): Inventory provider One of: `stoq`, `shopify`.
  - `pricing_type` (string): Type of pricing discount One of: `percentage`, `price`, `fixed_amount`, `no_discount`.
  - `pricing_amount` (number): Fixed discount amount
  - `pricing_percentage` (number): Percentage discount
  - `quantity_limit_text` (string): Text to display for quantity limits
  - `preorder_button_text` (string): Text for the preorder button
  - `preorder_button_text_color` (string): Text color for the preorder button
  - `preorder_button_background_color` (string): Background color for the preorder button
  - `preorder_button_colors_enabled` (boolean): Whether custom colors are enabled for the preorder button
  - `preorder_discounted_price_enabled` (boolean): Whether to show discounted price on the preorder button
  - `preorder_button_description` (string): Description text for the preorder button
  - `preorder_button_description_background_color` (string): Background color for the preorder button description
  - `preorder_button_description_border_radius` (string): Border radius for the preorder button description
  - `preorder_button_description_quantity_limit_suffix` (string): Suffix text for quantity limit in button description
  - `preorder_button_description_shipping_text_prefix` (string): Prefix text for shipping information in button description
  - `preorder_button_description_show_quantity_limit` (boolean): Whether to show quantity limit in button description
  - `preorder_button_description_show_shipping` (boolean): Whether to show shipping information in button description
  - `preorder_button_description_text_color` (string): Text color for the preorder button description
  - `preorder_badge_enabled` (boolean): Whether preorder badge is enabled
  - `preorder_badge_text` (string): Text for the preorder badge
  - `preorder_badge_text_color` (string): Text color for the preorder badge
  - `preorder_badge_background_color` (string): Background color for the preorder badge
  - `preorder_shipping_text` (string): Shipping text specific to preorders
  - `shipping_text` (string): Shipping information text
  - `shipping_line_item_property_enabled` (boolean): Whether to enable shipping line item properties
  - `shipping_applies_to_all_products` (boolean): Whether shipping settings apply to all products
  - `discount_text` (string): Discount information text
  - `preorder_tags` (string): Tags to apply to preorder items
  - `product_variants_source` (string): Source of product variants for this selling plan One of: `all`, `collection`, `custom`.
  - `product_variants_source_id` (integer): ID of the source (e.g., collection ID)
  - `markets_enabled` (boolean): Whether market-specific settings are enabled for this selling plan
  - `shopify_market_ids` (array of integers): List of Shopify market IDs where this selling plan is available. Required if markets_enabled is true.
  - `auto_collect_payment` (boolean): Whether to automatically collect payment when the order is ready to fulfill
  - `use_shopify_selling_plan` (boolean): 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_widget` (boolean): Whether to display the payment/billing widget on the product page
  - `split_fulfillments_enabled` (boolean): Whether to enable split fulfillments for preorders. When enabled, preorder items can be shipped separately from regular items in the same order.
  - `split_orders_enabled` (boolean): 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_variant` (boolean): 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_date` (boolean): 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_acknowledgement` (boolean): Whether customers must accept terms and conditions before adding a preorder item to their cart.
  - `preorder_acknowledgement_text` (string): The terms and conditions text that customers must acknowledge when require_preorder_acknowledgement is enabled.
  - `allow_mixed_cart` (boolean): 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_message` (string): 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_quantity` (integer): Minimum quantity required per order for preorder items. When set, customers must purchase at least this many units.
  - `preorder_max_quantity` (integer): Maximum quantity allowed per order for preorder items. When set, customers cannot purchase more than this many units.
  - `payment_line_item_property_enabled` (boolean): Whether to add payment information as a line item property (e.g., "Payment - Pay in full").
  - `custom_line_item_property_text` (string): Custom text to add as a line item property for preorder items. Useful for adding custom order notes or metadata.
  - `auto_collect_payment_on_fulfillment` (boolean): Whether to automatically collect remaining payment when the order is fulfilled (for partial payment preorders).
  - `hold_fulfillments_enabled` (boolean): Whether to automatically hold fulfillments for preorder items. When enabled, fulfillments will be held until manually released.
  - `hold_fulfillments_reason_note` (string): The reason note displayed when fulfillments are held (when hold_fulfillments_enabled is true).
  - `disable_button_until_acknowledged` (boolean): 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](https://docs.stoqapp.com/v1/preorders/).

Rate limit: this call costs 2 points ([rate limits](https://docs.stoqapp.com/docs/rate-limits/)).

## Example request

```sh
curl -X POST "https://app.stoqapp.com/api/v1/external/preorders" \
  -H "X-Auth-Token: $STOQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
    }
  }'
```

## 201

Selling plan created successfully

```json
{
  "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": []
}
```

## 401

Unauthorized

## 422

Validation errors