> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://stoqapp.crisp.help/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Use STOQ's Preorder APIs to manage preorder products

The Preorders API lets you programmatically manage selling plans (preorder offers) in your store. Perfect for automating preorder creation, syncing with external inventory systems, bulk updating shipping dates, or building custom preorder management interfaces. This article provides a high-level overview of our Preorders API capabilities. For complete documentation, detailed parameters, request/response examples, and interactive testing, visit https://docs.stoqapp.com/v1/#tag-preorders

**Base URL:** `https://app.stoqapp.com/api/v1/`
**Authentication:** API Key (get it from: Back in stock alerts > Integrations in your STOQ dashboard)

---

## What are Selling Plans?

In STOQ, **selling plans** are the configurations that define how a preorder product is sold, billed, and delivered to customers. Each selling plan contains:

* **Basic Info:** Name, enabled status, associated variants
* **Billing Configuration:** Payment timing (at checkout or later), charge types (percentage or fixed amount)
* **Delivery Settings:** When products ship (exact date or interval after purchase)
* **Inventory Management:** How inventory is reserved and tracked
* **Pricing Options:** Discounts for preordered items
* **UI Customization:** Button text, badge styling, shipping information text
* **Multi-Market Support:** Different settings for different Shopify markets

### Variant Association

Selling plans can be associated with product variants in three ways:
* All products in the store
* Products in a specific collection
* Custom selection of individual variants

---

## Getting Your API Key

To use the Preorders API, you'll need your API key:

1. Open STOQ app inside your Shopify Admin
2. Go to "Back in stock alerts from left menu bar > Settings tab > Integrations > Click on "See Integrations" button
3. Scroll down to find the "Developer" section and click on "Set up" for the API card
4. Click copy to get your API key
**Important:** Keep your API key secure and never share it publicly.

![](https://storage.crisp.chat/users/helpdesk/website/-/f/6/9/b/f69b1402a211d800/image_8b0g3j.png)
---

## Key API Capabilities

### 1. List and Filter Selling Plans

Retrieve all your selling plans with powerful filtering options. Perfect for building dashboards, syncing data to external systems, or auditing your preorder configurations. You can filter by enabled status, variant associations, and market availability.

**Endpoint:** `GET /api/v1/external/preorders`

**Query Parameters:**
* `enabled` - Filter by enabled status (true/false)
* `page`, `per_page` - Pagination (max 100 per page)

**Example:**
```javascript
fetch('https://app.stoqapp.com/api/v1/external/selling_plans?enabled=true', {
  headers: {
    'X-Auth-Token': 'YOUR_API_KEY'
  }
})
.then(response => response.json())
.then(data => console.log('Selling Plans:', data));
```

**Use Case:** Export all active selling plans for reporting or sync to your ERP.
Docs: [docs.stoqapp.com/v1/#operation-external-preorders-get](https://docs.stoqapp.com/v1/#operation-external-preorders-get)

---

### 2. Get a Specific Selling Plan

Retrieve detailed information about a single selling plan by its ID. Use this to display preorder details in custom interfaces, check current settings before updating, or integrate with your inventory management system.

**Endpoint:** `GET /api/v1/external/selling_plans/{id}`

**Example:**
```javascript
fetch('https://app.stoqapp.com/api/v1/external/selling_plans/123', {
  headers: {
    'X-Auth-Token': 'YOUR_API_KEY'
  }
})
.then(response => response.json())
.then(plan => console.log('Plan Details:', plan));
```

Docs: [docs.stoqapp.com/v1/#operation-external-preorders-id-get](https://docs.stoqapp.com/v1/#operation-external-preorders-id-get)
---

### 3. Create a New Selling Plan

Programmatically create new preorder offers. Ideal for automating preorder setup based on incoming inventory, creating seasonal offers in bulk, or integrating with your product launch workflows. Define all aspects of the preorder: billing, delivery, UI customization, and variant associations.

**Endpoint:** `POST /api/v1/external/preorders`

**Example:**
```javascript
fetch('https://app.stoqapp.com/api/v1/external/selling_plans', {
  method: 'POST',
  headers: {
    'X-Auth-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    selling_plan: {
      name: "Summer 2026 Preorder",
      enabled: true,
      preorder_button_text: "Preorder Now - Ships June 2026",
      delivery_type: "exact_time",
      delivery_at: "2026-06-15",
      billing_checkout_charge_type: "percentage",
      billing_checkout_charge_percentage: 100
    }
  })
})
.then(response => response.json())
.then(data => console.log('Created:', data));
```

**Use Case:** Automatically create preorder offers when new products are added to your catalog.
Docs: [docs.stoqapp.com/v1/#operation-external-preorders-post](https://docs.stoqapp.com/v1/#operation-external-preorders-post)

---

### 4. Update a Selling Plan

Update existing selling plans to change shipping dates, modify button text, adjust pricing, or toggle enabled status. Perfect for seasonal updates, responding to supply chain changes, or A/B testing different preorder configurations.

**Endpoint:** `PUT /api/v1/external/selling_plans/{id}`

**Example:**
```javascript
fetch('https://app.stoqapp.com/api/v1/external/selling_plans/123', {
  method: 'PUT',
  headers: {
    'X-Auth-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    selling_plan: {
      delivery_at: "2026-07-01", // Update shipping date
      preorder_button_text: "Preorder Now - Ships July 2026"
    }
  })
})
.then(response => response.json())
.then(data => console.log('Updated:', data));
```

**Use Case:** Bulk update shipping dates when supplier delivery schedules change.
Docs: [docs.stoqapp.com/v1/#operation-external-preorders-id-put](https://docs.stoqapp.com/v1/#operation-external-preorders-id-put)
---

### 5. Delete a Selling Plan

Remove a selling plan when it's no longer needed. Use this to clean up old preorder offers, remove test configurations, or automate the lifecycle of seasonal preorders.

**Endpoint:** `DELETE /api/v1/external/selling_plans/{id}`

**Example:**
```javascript
fetch('https://app.stoqapp.com/api/v1/external/selling_plans/123', {
  method: 'DELETE',
  headers: {
    'X-Auth-Token': 'YOUR_API_KEY'
  }
})
.then(response => console.log('Deleted successfully'));
```

Docs: [docs.stoqapp.com/v1/#operation-external-preorders-id-delete](https://docs.stoqapp.com/v1/#operation-external-preorders-id-delete)
---

### 6. Add Product Variants to a Selling Plan

Associate product variants with an existing selling plan. Essential for adding new products to ongoing preorder offers, expanding variant coverage, or building custom product selection interfaces.

**Endpoint:** `POST /api/v1/external/selling_plans/{id}/add_variant`

**Example:**
```javascript
fetch('https://app.stoqapp.com/api/v1/external/selling_plans/123/add_variant', {
  method: 'POST',
  headers: {
    'X-Auth-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    variant_ids: [41111111, 41222222, 41333333]
  })
})
.then(response => response.json())
.then(data => console.log('Variants added:', data));
```

**Use Case:** Automatically add new product variants to preorder when they're created.
Docs: [docs.stoqapp.com/v1/#operation-external-preorders-id-add-variant-post](https://docs.stoqapp.com/v1/#operation-external-preorders-id-add-variant-post)
---

### 7. Remove Product Variants from a Selling Plan

Remove variant associations when products are discontinued, restocked, or should no longer be available for preorder. Keeps your preorder offers clean and accurate.

**Endpoint:** `DELETE /api/v1/external/preorders/{id}/remove_variant`

**Example:**
```javascript
fetch('https://app.stoqapp.com/api/v1/external/selling_plans/123/remove_variant', {
  method: 'POST',
  headers: {
    'X-Auth-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    variant_ids: [41111111]
  })
})
.then(response => response.json())
.then(data => console.log('Variants removed:', data));
```

Docs:  [docs.stoqapp.com/v1/#operation-external-preorders-id-remove-variant-delete](https://docs.stoqapp.com/v1/#operation-external-preorders-id-remove-variant-delete)
---

### 8. Update Variant-Specific Settings

Customize per-variant settings like shipping text and maximum preorder quantities. Perfect for products with different delivery timelines, limited edition variants, or market-specific inventory limits.

**Endpoint:** `PATCH /api/v1/external/preorders/{id}/update_variant_settings`

**Example:**
```javascript
fetch('https://app.stoqapp.com/api/v1/external/selling_plans/123/update_variant_settings', {
  method: 'POST',
  headers: {
    'X-Auth-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    variant_id: 41111111,
    shipping_text: "Ships in 4-6 weeks",
    preorder_max_count: 100
  })
})
.then(response => response.json())
.then(data => console.log('Variant settings updated:', data));
```

Docs:  [docs.stoqapp.com/v1/#operation-external-preorders-id-update-variant-settings-patch](https://docs.stoqapp.com/v1/#operation-external-preorders-id-update-variant-settings-patch)
---

### 9. Send Shipping Update Email

Trigger shipping update emails to customers who preordered specific variants. Use this when delivery timelines change, products ship early, or you want to proactively communicate with waiting customers.

**Endpoint:** `POST /api/v1/external/selling_plans/{id}/send_shipping_update`

**Example:**
```javascript
fetch('https://app.stoqapp.com/api/v1/external/selling_plans/123/send_shipping_update', {
  method: 'POST',
  headers: {
    'X-Auth-Token': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    variant_ids: [41111111, 41222222],
    message: "Your preorder is shipping sooner than expected! Estimated arrival: June 1, 2026"
  })
})
.then(response => response.json())
.then(data => console.log('Emails sent:', data));
```

**Use Case:** Notify customers when shipping dates change due to supply chain updates.
Docs: [docs.stoqapp.com/v1/#operation-external-preorders-send-shipping-update-post](https://docs.stoqapp.com/v1/#operation-external-preorders-send-shipping-update-post)
---

### 10. Get Product Variants Associated with a Selling Plan

Retrieve all variants currently associated with a selling plan. Useful for auditing, displaying associated products in dashboards, or checking configuration before making changes.

**Endpoint:** `GET /api/v1/external/preorders/{id}/product_variants`

**Example:**
```javascript
fetch('https://app.stoqapp.com/api/v1/external/preorders/123/variants', {
  headers: {
    'X-Auth-Token': 'YOUR_API_KEY'
  }
})
.then(response => response.json())
.then(variants => console.log('Associated variants:', variants));
```

Docs:  [docs.stoqapp.com/v1/#operation-external-preorders-id-product-variants-get](https://docs.stoqapp.com/v1/#operation-external-preorders-id-product-variants-get)
---

## Quick Start Example

```javascript
// 1. Get your API key from STOQ dashboard

// 2. Create a new preorder offer
const createPreorder = async () => {
  const response = await fetch('https://app.stoqapp.com/api/v1/external/preorders	', {
    method: 'POST',
    headers: {
      'X-Auth-Token': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      selling_plan: {
        name: "Holiday 2026 Preorder",
        enabled: true,
        preorder_button_text: "Preorder for Holiday",
        delivery_type: "exact_time",
        delivery_at: "2026-12-01",
        billing_checkout_charge_type: "percentage",
        billing_checkout_charge_percentage: 50, // 50% upfront
        preorder_badge_enabled: true,
        preorder_badge_text: "Preorder"
      }
    })
  });

  const plan = await response.json();
  console.log('Created selling plan:', plan.id);

  // 3. Add variants to the plan
  await fetch(`https://app.stoqapp.com/api/v1/external/selling_plans/${plan.id}/add_variant`, {
    method: 'POST',
    headers: {
      'X-Auth-Token': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      variant_ids: [41111111, 41222222]
    })
  });

  console.log('Variants added to preorder!');
};

createPreorder();
```

---

## Testing the API

You can test any API endpoint using the "Test it" feature:

1. Go to  [docs.stoqapp.com/v1](https://docs.stoqapp.com/v1/)
2. Select the API endpoint you wish to test
3. Click on "Test it" button
4. Enter the API key and required data to see the result

---

## Authentication

**Header:** `X-Auth-Token: YOUR_API_KEY`

All endpoints require authentication using your API key in the header.

---

## Full API Reference

For detailed parameters, response schemas, and interactive API testing, visit: https://docs.stoqapp.com/v1/#tag-preorders. If you need any assistance in using the Preorders API, feel free to contact our 24/7 live support. We're happy to help!