Articles on: API

Use STOQ's Preorder APIs to manage preorder products

Preorders API - Complete Guide



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 docs.stoqapp.com/preorders-api


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 > Integrations"
  3. Scroll down to find "API Key" section
  4. Click copy to get your API key


API Key Location


Important: Keep your API key secure and never share it publicly.



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/selling_plans


Query Parameters:

  • enabled - Filter by enabled status (true/false)
  • page, per_page - Pagination (max 100 per page)


Example:

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.



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:

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));



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/selling_plans


Example:

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.



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:

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.



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:

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'));



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_variants


Example:

fetch('https://app.stoqapp.com/api/v1/external/selling_plans/123/add_variants', {
  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.



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: POST /api/v1/external/selling_plans/{id}/remove_variants


Example:

fetch('https://app.stoqapp.com/api/v1/external/selling_plans/123/remove_variants', {
  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));



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: POST /api/v1/external/selling_plans/{id}/update_variant_settings


Example:

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));



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:

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.



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/selling_plans/{id}/variants


Example:

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



Quick Start Example


// 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/selling_plans', {
    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_variants`, {
    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 https://docs.stoqapp.com/preorders-api
  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: docs.stoqapp.com/preorders-api. If you need any assistance in using the Preorders API, feel free to contact our 24/7 live support. We're happy to help!


Updated on: 15/01/2026

Was this article helpful?

Share your feedback

Cancel

Thank you!