---
title: "Preorders"
description: "Preorders: Add multiple product variants to a selling plan, List and filter selling plans, Create a new selling plan, Get a specific selling plan, Update a selling plan, Delete a selling plan (soft delete), Get product v"
url: https://docs.stoqapp.com/v1/preorders/
api: "API v1 (legacy)"
---

# Preorders

## The preorder object

- `id` (string): Unique identifier for the selling plan
- `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, nullable): Exact billing time if billing_type is exact_time
- `billing_after_n_intervals` (integer, nullable): 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, nullable): Fixed amount to charge at checkout
- `billing_checkout_charge_percentage` (number, nullable): 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, nullable): Exact delivery time if delivery_type is exact_time
- `delivery_after_n_intervals` (integer, nullable): 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, nullable): Fixed discount amount
- `pricing_percentage` (number, nullable): 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, nullable): ID of the source (e.g., collection ID)
- `selling_plan_product_variants_count` (integer): Number of product variants associated with this selling plan
- `shopify_selling_plan_id` (integer, nullable): Shopify selling plan ID
- `shopify_selling_plan_group_id` (integer, nullable): Shopify selling plan group ID
- `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, preorders will be separted into its own fulfillment 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, nullable): Minimum quantity required per order for preorder items. When set, customers must purchase at least this many units.
- `preorder_max_quantity` (integer, nullable): 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, nullable): 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).
- `shop_id` (integer): Shop ID this selling plan belongs to
- `market_id` (integer, nullable): Market ID for multi-market stores
- `created_at` (string): Timestamp when the selling plan was created
- `updated_at` (string): Timestamp when the selling plan was last updated
- `discarded_at` (string, nullable): Timestamp when the selling plan was soft deleted
- `ongoing_job` (boolean): Whether there is an ongoing job for this selling plan
- `shopify_variant_ids` (array of integers): List of Shopify variant IDs associated with this selling plan

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

## Endpoints

- `POST /external/preorders/{id}/add_variant`: [Add multiple product variants to a selling plan](https://docs.stoqapp.com/v1/preorders/add-multiple-product-variants-to-a-selling-plan.md)
- `GET /external/preorders`: [List and filter selling plans](https://docs.stoqapp.com/v1/preorders/list-and-filter-selling-plans.md)
- `POST /external/preorders`: [Create a new selling plan](https://docs.stoqapp.com/v1/preorders/create-a-new-selling-plan.md)
- `GET /external/preorders/{id}`: [Get a specific selling plan](https://docs.stoqapp.com/v1/preorders/get-a-specific-selling-plan.md)
- `PUT /external/preorders/{id}`: [Update a selling plan](https://docs.stoqapp.com/v1/preorders/update-a-selling-plan.md)
- `DELETE /external/preorders/{id}`: [Delete a selling plan (soft delete)](https://docs.stoqapp.com/v1/preorders/delete-a-selling-plan-soft-delete.md)
- `GET /external/preorders/{id}/product_variants`: [Get product variants associated with a selling plan](https://docs.stoqapp.com/v1/preorders/get-product-variants-associated-with-a-selling-plan.md)
- `DELETE /external/preorders/{id}/remove_variant`: [Remove multiple product variants from a selling plan](https://docs.stoqapp.com/v1/preorders/remove-multiple-product-variants-from-a-selling-plan.md)
- `POST /external/preorders/send_shipping_update`: [Send shipping update emails to multiple orders](https://docs.stoqapp.com/v1/preorders/send-shipping-update-emails-to-multiple-orders.md)
- `POST /external/preorders/{id}/bulk_toggle_inventory_policy`: [Queue a bulk update of inventory policy for multiple variants](https://docs.stoqapp.com/v1/preorders/queue-a-bulk-update-of-inventory-policy-for-multiple-variants.md)
- `PATCH /external/preorders/{id}/update_variant_settings`: [Update variant-specific settings for a selling plan](https://docs.stoqapp.com/v1/preorders/update-variant-specific-settings-for-a-selling-plan.md)