{ "openapi": "3.1.0", "info": { "title": "STOQ API v1", "version": "1.0.0", "description": "## Back in Stock\n\nBefore diving into the API reference, it's important to understand the key term we use - Intent\n\nIntents are essentially \"waitlist requests\" or \"subscriptions\" that customers create when they want to be notified with a back in stock alert.\n\n1. **Core Purpose**:\n * When a product is out of stock, customers can sign up to be notified when it becomes available again\n * Each intent represents a single customer's request to be notified about a specific product variant.\n * Intent is unique to a customer, product variant & market.\n2. **What data is present in an Intent?**\n * **Customer Information**: Each intent contains customer details like email, phone, and name\n * **Product Information**: Shopify product and product variant IDs\n * **Notification Preference**: Specifies how the customer wants to be notified (email or SMS)\n * **Quantity**: How many units the customer is interested in when the product is back in stock\n3. **Lifecycle of an Intent**:\n * Created when a customer signs up for notifications\n * Can be notified when the product becomes available\n * Can be blocked from sending notifications\n * Can be unsubscribed by the customer\n * Tracks notification history and opt-in status\n4. **Compliance & Privacy**:\n * Includes GDPR opt-in confirmation tracking\n * Tracks marketing preferences\n * Maintains unsubscribe status\n\n## Preorders\n\nBefore diving into the API reference, it's important to understand the key term we use - Selling Plans\n\n#### What are Selling Plans?\n\nSelling Plans in the context of preorders are configurations that define how a preorder product is sold, billed, and delivered to customers.\n\n#### Core Purpose:\n\n* Enable merchants to sell products before they're in stock or available for immediate shipping\n* Define payment schedules, delivery timelines, and inventory management for preordered items\n* Provide customization options for how preorders appear and function in the storefront\n\n#### What data is present in a Selling Plan?\n\n* **Basic Information**: Name, internal reference name, enabled status\n* **Billing Configuration**: When and how much to charge (at checkout or later), charge types (percentage or fixed amount)\n* **Delivery Settings**: When products will be delivered (exact date or interval after purchase)\n* **Inventory Management**: How inventory is reserved and which system manages it\n* **Pricing Options**: Discount amounts or percentages for preordered items\n* **UI Customization**: Button text, badge styling, shipping information text\n\n#### Variant Association:\n\n* Selling plans can be associated with product variants in three ways:\n * All products in the store\n * Products in a specific collection\n * Custom selection of individual variants\n* Each variant can have custom settings like shipping text and maximum preorder quantity\n\n#### Multi-Market Support:\n\n* Selling plans can be configured for specific markets in multi-market stores\n* Different markets may have different preorder terms or availability", "contact": { "name": "STOQ Support", "email": "support@stoqapp.com", "url": "https://app.stoqapp.com" } }, "servers": [ { "url": "https://app.stoqapp.com/api/v1", "description": "Production" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Back in Stock" }, { "name": "Preorders" } ], "paths": { "/intents.json": { "post": { "summary": "Create Customer Intent to Buy Product", "description": "Create a new intent for a customer to be notified when a product is back in stock. Unlike other API endpoints for Back in Stock, this API endpoint does not require an API Key.", "tags": [ "Back in Stock" ], "parameters": [ { "in": "header", "name": "X-Shopify-Shop-Domain", "required": true, "schema": { "type": "string" }, "description": "The Shopify shop domain (e.g. 'restock-rocket-demo.myshopify.com')" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "description": "Must be application/json" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "intent", "customer" ], "properties": { "intent": { "type": "object", "required": [ "shopify_variant_id", "shopify_product_id", "channel", "quantity", "source" ], "properties": { "shopify_variant_id": { "type": "integer", "description": "The ID for the Shopify Variant" }, "shopify_product_id": { "type": "integer", "description": "The ID for the Shopify Product" }, "shopify_market_id": { "type": "integer", "description": "The ID for the Shopify Market (for multi-market stores)" }, "channel": { "type": "string", "enum": [ "email", "sms", "push" ], "description": "The notification channel (email requires customer.email, sms requires customer.phone, push requires customer.push)" }, "quantity": { "type": "integer", "description": "The quantity of the Variant they want" }, "source": { "type": "string", "enum": [ "api" ], "description": "Should be set to 'api'" } } }, "customer": { "type": "object", "properties": { "id": { "type": "string", "description": "Optional customer id from previous API call response" }, "name": { "type": "string", "description": "Customer's name (Shop must be on standard plan or above)" }, "email": { "type": "string", "description": "Customer email address (required if channel is email)" }, "phone": { "type": "string", "description": "Customer phone number with country code but without '+' (required if channel is sms)" }, "push": { "type": "string", "description": "Push notification token (required if channel is push)" }, "country_code": { "type": "string", "description": "Country code for the customer phone number" }, "country": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Country in two letter code for the customer (improves phone number validation)" }, "accepts_marketing": { "type": "boolean", "description": "Whether the customer has agreed to receive email content from your online store" }, "locale": { "type": "string", "description": "Customer locale" }, "shopify_market_id": { "type": "integer", "description": "Customer's Shopify Market ID for multi-market stores" }, "shopify_customer_id": { "type": "string", "description": "Customer's Shopify ID" } } }, "product": { "type": "object", "description": "Product data is only needed if you have optin confirmation or alerts to your shop set up", "properties": { "variant_count": { "type": "integer", "description": "The number of variants the Shopify Product has" }, "title": { "type": "string", "description": "The title for the Shopify Product" }, "variant_title": { "type": "string", "description": "The title for the Shopify Variant" }, "vendor": { "type": "string", "description": "The vendor/brand of the product" }, "sku": { "type": "string", "description": "The SKU of the variant" } } } } }, "example": { "intent": { "shopify_variant_id": 43900910010503, "shopify_product_id": 7891234567890, "channel": "email", "quantity": 1, "source": "api" }, "customer": { "email": "shopper@example.com", "name": "Alex Shopper", "accepts_marketing": true, "country": "us" } } } } }, "responses": { "200": { "description": "Request processed but with errors", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } } } } } }, "201": { "description": "Intent created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "intents": { "type": "array", "items": { "type": "object", "description": "Created intent details" } }, "errors": { "type": "array", "items": { "type": "string" } } } }, "example": { "intents": [ { "id": "8f3c2b1a-7d4e-4c2a-9f10-2b3c4d5e6f70", "channel": "email", "email": "shopper@example.com", "phone": null, "quantity": 1, "notified_at": null, "optin_confirmed": true, "source": "api", "type": "restock", "sent_notifications_count": 0, "created_at": "2026-06-20T14:30:00Z", "updated_at": "2026-06-20T14:30:00Z", "customer_id": "c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f", "shop_id": "a1b2c3d4-5e6f-7081-92a3-b4c5d6e7f809", "shopify_product_id": 7891234567890, "shopify_variant_id": 43900910010503, "accepts_marketing": true } ], "errors": [] } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" } }, "security": [] } }, "/external/intents/bulk_destroy": { "delete": { "summary": "Delete intents (single or multiple)", "description": "Delete one or more intents by their IDs. Only intents that have not been sent (notified_at is null) can be deleted.\nIf any of the intents have been sent, the entire operation will fail and return a 422 error with the IDs of sent intents.\nYou can pass a single intent ID in the array to delete just one intent.\n", "tags": [ "Back in Stock" ], "parameters": [ { "in": "header", "name": "X-Auth-Token", "required": true, "schema": { "type": "string" }, "description": "API key for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "intent_ids": { "type": "array", "items": { "type": "string" }, "description": "Array of intent IDs to delete" } }, "required": [ "intent_ids" ] }, "example": { "intent_ids": [ "8f3c2b1a-7d4e-4c2a-9f10-2b3c4d5e6f70", "1a2b3c4d-5e6f-7081-92a3-b4c5d6e7f809" ] } } } }, "responses": { "200": { "description": "All intents deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "deleted_count": { "type": "integer", "description": "Number of intents successfully deleted" } } }, "example": { "success": true, "deleted_count": 2 } } } }, "400": { "description": "Bad request - invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "No valid intents found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Cannot delete intents that have already been sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "sent_intent_ids": { "type": "array", "items": { "type": "string" }, "description": "IDs of intents that have already been sent and cannot be deleted" } } } } } } } } }, "/external/intents/{id}": { "get": { "summary": "Get a specific intent", "tags": [ "Back in Stock" ], "parameters": [ { "in": "header", "name": "X-Auth-Token", "required": true, "schema": { "type": "string" }, "description": "API key for authentication" }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Intent ID" } ], "responses": { "200": { "description": "Intent details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Intent" }, "example": { "id": "8f3c2b1a-7d4e-4c2a-9f10-2b3c4d5e6f70", "channel": "email", "email": "shopper@example.com", "phone": null, "quantity": 1, "notified_at": null, "optin_confirmed": true, "source": "api", "type": "restock", "sent_notifications_count": 0, "created_at": "2026-06-20T14:30:00Z", "updated_at": "2026-06-20T14:30:00Z", "customer_id": "c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f", "shop_id": "a1b2c3d4-5e6f-7081-92a3-b4c5d6e7f809", "shopify_product_id": 7891234567890, "shopify_variant_id": 43900910010503, "accepts_marketing": true } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Intent not found" } }, "description": "Retrieve a single back-in-stock intent (signup) by its STOQ ID. Returns the full intent record — the customer contact details, channel, requested quantity, and notification status. Returns 404 if no intent with that ID exists for the authenticated shop." } }, "/external/intents/products_in_demand": { "get": { "summary": "Get products in demand report", "description": "Retrieve a paginated list of product variants with demand metrics based on customer intents.\nReturns aggregated data showing total intents, pending intents, and last requested date for each variant.\nResults can be filtered by date range and sorted by different metrics.\n", "tags": [ "Back in Stock" ], "parameters": [ { "in": "header", "name": "X-Auth-Token", "required": true, "schema": { "type": "string" }, "description": "API key for authentication" }, { "in": "query", "name": "start_date", "schema": { "type": "string", "format": "date" }, "description": "Filter by start date (YYYY-MM-DD). Filters based on last_requested_at field." }, { "in": "query", "name": "end_date", "schema": { "type": "string", "format": "date" }, "description": "Filter by end date (YYYY-MM-DD). Filters based on last_requested_at field." }, { "in": "query", "name": "sort_by", "schema": { "type": "string", "enum": [ "pending", "total", "last_requested_at" ], "default": "pending" }, "description": "Sort results by pending intents, total intents, or last requested date" }, { "in": "query", "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort direction (ascending or descending)" }, { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1 }, "description": "Page number for pagination" }, { "in": "query", "name": "per_page", "schema": { "type": "integer", "default": 25, "maximum": 500 }, "description": "Number of items per page (maximum 500)" }, { "in": "query", "name": "intent_type", "schema": { "type": "string" }, "description": "Filter by intent type (used when loading product data)" } ], "responses": { "200": { "description": "A paginated list of product variants with demand metrics", "content": { "application/json": { "schema": { "type": "object", "properties": { "product_variants_in_demand": { "type": "array", "items": { "$ref": "#/components/schemas/ProductVariantDemand" } }, "page": { "type": "integer", "description": "Current page number" }, "per_page": { "type": "integer", "description": "Number of items per page" }, "has_next_page": { "type": "boolean", "description": "Whether there is a next page" }, "has_prev_page": { "type": "boolean", "description": "Whether there is a previous page" } } }, "example": { "product_variants_in_demand": [ { "shopify_variant_id": 43900910010503, "shopify_product_id": 7891234567890, "total": 42, "pending": 37, "last_requested_at": "2026-06-24T09:12:00Z", "variant_data": { "id": 43900910010503, "title": "Medium / Red", "sku": "TSHIRT-M-RED" }, "product_data": { "id": 7891234567890, "title": "Classic T-Shirt", "vendor": "Acme" } } ], "page": 1, "per_page": 25, "has_next_page": true, "has_prev_page": false } } } }, "400": { "description": "Bad request - invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized" } } } }, "/external/intents": { "get": { "summary": "List and filter intents", "tags": [ "Back in Stock" ], "parameters": [ { "in": "header", "name": "X-Auth-Token", "required": true, "schema": { "type": "string" }, "description": "API key for authentication" }, { "in": "query", "name": "shopify_variant_id", "schema": { "type": "integer" }, "description": "Filter by Shopify Variant ID" }, { "in": "query", "name": "shopify_product_id", "schema": { "type": "integer" }, "description": "Filter by Shopify Product ID" }, { "in": "query", "name": "email", "schema": { "type": "string" }, "description": "Filter by customer email" }, { "in": "query", "name": "phone", "schema": { "type": "string" }, "description": "Filter by customer phone" }, { "in": "query", "name": "start_date", "schema": { "type": "string", "format": "date" }, "description": "Filter by start date (YYYY-MM-DD)" }, { "in": "query", "name": "end_date", "schema": { "type": "string", "format": "date" }, "description": "Filter by end date (YYYY-MM-DD)" }, { "in": "query", "name": "notified", "schema": { "type": "boolean" }, "description": "Filter by notification status (true = notified, false = not notified)" }, { "in": "query", "name": "page", "schema": { "type": "integer" }, "description": "Page number for pagination" }, { "in": "query", "name": "per_page", "schema": { "type": "integer" }, "description": "Number of items per page (maximum 500)" } ], "responses": { "200": { "description": "A paginated list of intents", "content": { "application/json": { "schema": { "type": "object", "properties": { "intents": { "type": "array", "items": { "$ref": "#/components/schemas/Intent" } }, "meta": { "type": "object", "properties": { "total_count": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_pages": { "type": "integer" } } } } }, "example": { "intents": [ { "id": "8f3c2b1a-7d4e-4c2a-9f10-2b3c4d5e6f70", "channel": "email", "email": "shopper@example.com", "phone": null, "quantity": 1, "notified_at": null, "optin_confirmed": true, "source": "api", "type": "restock", "sent_notifications_count": 0, "created_at": "2026-06-20T14:30:00Z", "updated_at": "2026-06-20T14:30:00Z", "customer_id": "c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f", "shop_id": "a1b2c3d4-5e6f-7081-92a3-b4c5d6e7f809", "shopify_product_id": 7891234567890, "shopify_variant_id": 43900910010503, "accepts_marketing": true } ], "meta": { "total_count": 128, "page": 1, "per_page": 25, "total_pages": 6 } } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" } }, "description": "List back-in-stock intents (signups) for the shop, newest first. Supports filtering by Shopify product or variant, customer email or phone, creation date range, and notification status, with page-based pagination (up to 500 per page). Returns the matching intents alongside pagination metadata." } }, "/external/intents/notify_intent": { "post": { "summary": "Notify a single intent", "tags": [ "Back in Stock" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Intent ID" }, "allow_resend": { "type": "boolean", "description": "Allow resending notification" } } }, "example": { "id": "8f3c2b1a-7d4e-4c2a-9f10-2b3c4d5e6f70", "allow_resend": false } } } }, "responses": { "200": { "description": "Notification sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "intent_id": { "type": "string" } } }, "example": { "success": true, "intent_id": "8f3c2b1a-7d4e-4c2a-9f10-2b3c4d5e6f70" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Intent not found" }, "422": { "description": "Failed to notify intent" } }, "description": "Send the back-in-stock notification for a single intent immediately, regardless of current inventory. By default an intent that has already been notified will not be sent again; set `allow_resend` to true to force a resend. Returns 404 if the intent does not exist and 422 if the notification could not be sent." } }, "/external/intents/bulk_notify_intent": { "post": { "summary": "Notify multiple intents in bulk", "tags": [ "Back in Stock" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "intent_ids": { "type": "array", "items": { "type": "string" }, "description": "Array of intent IDs" }, "allow_resend": { "type": "boolean", "description": "Allow resending notifications" } } }, "example": { "intent_ids": [ "8f3c2b1a-7d4e-4c2a-9f10-2b3c4d5e6f70", "1a2b3c4d-5e6f-7081-92a3-b4c5d6e7f809" ], "allow_resend": false } } } }, "responses": { "200": { "description": "All notifications sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "array", "items": { "type": "string" } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "intent_id": { "type": "string" }, "error": { "type": "string" } } } } } }, "example": { "success": [ "8f3c2b1a-7d4e-4c2a-9f10-2b3c4d5e6f70" ], "failed": [ { "intent_id": "1a2b3c4d-5e6f-7081-92a3-b4c5d6e7f809", "error": "Already notified" } ] } } } }, "207": { "description": "Partial success (some notifications failed)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "array", "items": { "type": "string" } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "intent_id": { "type": "string" }, "error": { "type": "string" } } } } } } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" } }, "description": "Send back-in-stock notifications for multiple intents in one request. Each intent is processed independently; the response reports which succeeded and which failed, returning 207 when only some succeed. Set `allow_resend` to true to re-notify intents that were already sent." } }, "/external/intents/transfer_signups": { "post": { "summary": "Transfer signups from one variant to another", "description": "Transfer intents (signups) from a source variant to a target variant.\nThis is useful when consolidating variants or when products are restructured.\nBy default transfers pending intents, but can transfer sent or all intents based on intent_type parameter.\n", "tags": [ "Back in Stock" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from_shopify_variant_id": { "type": "integer", "description": "Shopify variant ID to transfer signups from" }, "from_shopify_product_id": { "type": "integer", "description": "Shopify product ID of the source variant" }, "to_shopify_variant_id": { "type": "integer", "description": "Shopify variant ID to transfer signups to" }, "to_shopify_product_id": { "type": "integer", "description": "Shopify product ID of the target variant" }, "intent_type": { "type": "string", "enum": [ "unsent", "sent", "all" ], "description": "Type of intents to transfer (default is unsent/pending)" } }, "required": [ "from_shopify_variant_id", "from_shopify_product_id", "to_shopify_variant_id", "to_shopify_product_id" ] }, "example": { "from_shopify_variant_id": 43900910010503, "from_shopify_product_id": 7891234567890, "to_shopify_variant_id": 43900910010999, "to_shopify_product_id": 7891234567890, "intent_type": "unsent" } } } }, "responses": { "200": { "description": "Transfer completed successfully" }, "400": { "description": "Bad request - invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Transfer failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "object", "description": "Interactor errors object" } } } } } } } } }, "/external/preorders/{id}/add_variant": { "post": { "summary": "Add multiple product variants to a selling plan", "tags": [ "Preorders" ], "parameters": [ { "in": "header", "name": "X-Auth-Token", "required": true, "schema": { "type": "string" }, "description": "API key for authentication" }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Selling plan ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shopify_variant_ids": { "type": "array", "items": { "type": "integer" }, "description": "Array of Shopify variant IDs to add" } }, "required": [ "shopify_variant_ids" ] }, "example": { "shopify_variant_ids": [ 43900910010503, 43900910010999 ] } } } }, "responses": { "200": { "description": "Variants added successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "variants_added": { "type": "array", "items": { "type": "integer" }, "description": "List of variant IDs that were added" } } }, "example": { "success": true, "message": "2 variants added to selling plan", "variants_added": [ 43900910010503, 43900910010999 ] } } } }, "400": { "description": "Bad request - missing or invalid shopify_variant_ids", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Selling plan not found" }, "422": { "description": "Some variants already added or other error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "existing_variants": { "type": "array", "items": { "type": "integer" }, "description": "List of variant IDs that were already added" } } } } } } }, "description": "Attach one or more Shopify product variants to a selling plan so they become available for preorder. Pass the variant IDs in `shopify_variant_ids`; any that are already attached are reported back under `existing_variants` with a 422. Returns the list of variant IDs that were newly added." } }, "/external/preorders": { "post": { "summary": "Create a new selling plan", "tags": [ "Preorders" ], "parameters": [ { "in": "header", "name": "X-Auth-Token", "required": true, "schema": { "type": "string" }, "description": "API key for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "selling_plan": { "$ref": "#/components/schemas/SellingPlanInput" } } }, "example": { "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" } } } } }, "responses": { "201": { "description": "Selling plan created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellingPlan" }, "example": { "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": { "description": "Unauthorized" }, "422": { "description": "Validation errors", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "object" } } } } } } }, "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 the created selling plan, including its STOQ ID, on success." }, "get": { "summary": "List and filter selling plans", "tags": [ "Preorders" ], "parameters": [ { "in": "header", "name": "X-Auth-Token", "required": true, "schema": { "type": "string" }, "description": "API key for authentication" }, { "in": "query", "name": "name", "schema": { "type": "string" }, "description": "Filter by selling plan name or internal name" }, { "in": "query", "name": "page", "schema": { "type": "integer" }, "description": "Page number for pagination" }, { "in": "query", "name": "per_page", "schema": { "type": "integer" }, "description": "Number of items per page" } ], "responses": { "200": { "description": "A paginated list of selling plans", "content": { "application/json": { "schema": { "type": "object", "properties": { "selling_plans": { "type": "array", "items": { "$ref": "#/components/schemas/SellingPlanList" } }, "meta": { "type": "object", "properties": { "total_count": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_pages": { "type": "integer" } } } } }, "example": { "selling_plans": [ { "id": "79b44c6c-ebc7-41d4-8a1b-573d7c693454", "name": "Summer Preorder", "internal_name": "summer-2026", "enabled": true, "selling_plan_product_variants_count": 12, "created_at": "2026-06-20T10:00:00Z", "updated_at": "2026-06-24T08:30:00Z", "shopify_variant_ids": [ 43900910010503, 43900910010999 ] } ], "meta": { "total_count": 3, "page": 1, "per_page": 25, "total_pages": 1 } } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" } }, "description": "List the shop's preorder selling plans, newest first, with page-based pagination. Optionally filter by `name` (matches the display or internal name). Returns a lightweight representation of each plan plus pagination metadata; use Get a Specific Selling Plan for the full object." } }, "/external/preorders/{id}": { "delete": { "summary": "Delete a selling plan (soft delete)", "tags": [ "Preorders" ], "parameters": [ { "in": "header", "name": "X-Auth-Token", "required": true, "schema": { "type": "string" }, "description": "API key for authentication" }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Selling plan ID" } ], "responses": { "200": { "description": "Selling plan deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } }, "example": { "success": true, "message": "Selling plan deleted" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Selling plan not found" }, "422": { "description": "Failed to delete selling plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "description": "Soft-delete a preorder selling plan by ID. The plan is discarded (its `discarded_at` is set) and detached from the storefront, but historical preorder data is preserved. Returns 404 if the plan does not exist and 422 if it could not be deleted." }, "get": { "summary": "Get a specific selling plan", "tags": [ "Preorders" ], "parameters": [ { "in": "header", "name": "X-Auth-Token", "required": true, "schema": { "type": "string" }, "description": "API key for authentication" }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Selling plan ID" } ], "responses": { "200": { "description": "Selling plan details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellingPlan" }, "example": { "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 ] } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Selling plan not found" } }, "description": "Retrieve a single preorder selling plan by its STOQ ID, including the full billing, delivery, pricing, button, badge, fulfillment, and market configuration, the count of attached variants, and the associated Shopify selling-plan IDs. Returns 404 if no plan with that ID exists for the shop." }, "put": { "summary": "Update a selling plan", "tags": [ "Preorders" ], "parameters": [ { "in": "header", "name": "X-Auth-Token", "required": true, "schema": { "type": "string" }, "description": "API key for authentication" }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Selling plan ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "selling_plan": { "$ref": "#/components/schemas/SellingPlanInput" } } }, "example": { "selling_plan": { "enabled": false, "preorder_button_text": "Coming soon" } } } } }, "responses": { "200": { "description": "Selling plan updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellingPlan" }, "example": { "id": "79b44c6c-ebc7-41d4-8a1b-573d7c693454", "name": "Summer Preorder", "internal_name": "summer-2026", "enabled": false, "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": "Coming soon", "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 ] } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Selling plan not found" }, "422": { "description": "Validation errors", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "object" } } } } } } }, "description": "Update an existing preorder selling plan. Supply a `selling_plan` object with the fields you want to change; omitted fields are left unchanged. Returns the updated selling plan, or 422 with validation errors if the changes are invalid." } }, "/external/preorders/{id}/product_variants": { "get": { "summary": "Get product variants associated with a selling plan", "description": "Retrieve product variants associated with a selling plan, including their preorder details and sales metrics.\n\nFiltering behavior:\n- No parameters: Returns all product variants in the selling plan\n- shopify_product_id: Returns all variants for that specific product\n- shopify_variant_id: Returns only that specific variant (single object response)\n", "tags": [ "Preorders" ], "parameters": [ { "in": "header", "name": "X-Auth-Token", "required": true, "schema": { "type": "string" }, "description": "API key for authentication" }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Selling plan ID" }, { "in": "query", "name": "shopify_product_id", "schema": { "type": "integer" }, "description": "Filter by specific Shopify product ID to get all variants for that product" }, { "in": "query", "name": "shopify_variant_id", "schema": { "type": "integer" }, "description": "Filter by specific Shopify variant ID to get only that variant (returns single object)" } ], "responses": { "200": { "description": "Product variants with their preorder details and sales metrics", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SellingPlanProductVariantsResponse" }, { "$ref": "#/components/schemas/SellingPlanSingleVariantResponse" } ] }, "example": { "selling_plan_id": "79b44c6c-ebc7-41d4-8a1b-573d7c693454", "selling_plan_name": "Summer Preorder", "currency": "USD", "product_variants": [ { "shopify_product_id": 7891234567890, "shopify_variant_id": 43900910010503, "product_title": "Classic T-Shirt", "variant_title": "Medium / Red", "preorder_units_sold": 18, "preorder_max_count": 100, "shipping_text": "Ships July 2026" } ], "meta": { "total_variants": 12, "total_units_sold": 140 } } } } }, "400": { "description": "Bad request - cannot filter by both product and variant ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Selling plan not found or variant not found in this selling plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/external/preorders/{id}/remove_variant": { "delete": { "summary": "Remove multiple product variants from a selling plan", "description": "Remove multiple product variants from a selling plan. Optionally, you can also update the inventory policy\nof the removed variants in the same request to avoid making separate API calls.\n\nWhen `inventory_policy` is provided, the inventory policy update is performed synchronously (inline)\nfor better performance and to avoid race conditions.\n", "tags": [ "Preorders" ], "parameters": [ { "in": "header", "name": "X-Auth-Token", "required": true, "schema": { "type": "string" }, "description": "API key for authentication" }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Selling plan ID" }, { "in": "query", "name": "shopify_variant_ids", "required": true, "schema": { "type": "array", "items": { "type": "integer" } }, "description": "Array of Shopify variant IDs to remove", "style": "form", "explode": false }, { "in": "query", "name": "inventory_policy", "required": false, "schema": { "type": "string", "enum": [ "CONTINUE", "DENY" ] }, "description": "Optional. Inventory policy to set for the removed variants. CONTINUE allows overselling, DENY prevents it." } ], "responses": { "200": { "description": "Variants removed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "variants_removed": { "type": "array", "items": { "type": "integer" }, "description": "List of variant IDs that were removed" }, "inventory_policy_updated": { "type": "boolean", "description": "Whether the inventory policy was successfully updated (only present when inventory_policy is provided)" }, "inventory_policy": { "type": "string", "enum": [ "CONTINUE", "DENY" ], "description": "The inventory policy that was set (only present when inventory_policy_updated is true)" } } }, "example": { "success": true, "message": "1 variant removed", "variants_removed": [ 43900910010503 ], "inventory_policy_updated": true, "inventory_policy": "DENY" } } } }, "400": { "description": "Bad request - missing or invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Selling plan or variants not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Failed to remove variants or invalid inventory policy", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/external/preorders/send_shipping_update": { "post": { "summary": "Send shipping update emails to multiple orders", "description": "Send shipping update emails to multiple preorders. You can specify orders using either:\n- STOQ internal order IDs (UUIDs) via `order_ids`\n- Shopify order IDs via `shopify_order_ids`\n\nYou must provide one or the other, but not both.\n", "tags": [ "Preorders" ], "parameters": [ { "in": "header", "name": "X-Auth-Token", "required": true, "schema": { "type": "string" }, "description": "API key for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "order_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Array of STOQ internal order UUIDs to send shipping updates to (mutually exclusive with shopify_order_ids)" }, "shopify_order_ids": { "type": "array", "items": { "type": "integer" }, "description": "Array of Shopify order IDs to send shipping updates to (mutually exclusive with order_ids)" }, "subject": { "type": "string", "description": "Email subject line" }, "header": { "type": "string", "description": "Email header text" }, "description": { "type": "string", "description": "Email body description" } }, "required": [ "subject", "header", "description" ] }, "example": { "shopify_order_ids": [ 5012345678901, 5012345678902 ], "subject": "Your preorder has shipped", "header": "Good news!", "description": "Your Summer Preorder items are on the way and should arrive within 5–7 business days." } } } }, "responses": { "200": { "description": "Shipping update emails queued successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "orders_count": { "type": "integer", "description": "Number of orders that will receive the shipping update" } } }, "example": { "success": true, "message": "Shipping updates queued", "orders_count": 2 } } } }, "400": { "description": "Bad request - missing required parameters or invalid input", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "No valid orders found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/external/preorders/{id}/bulk_toggle_inventory_policy": { "post": { "summary": "Queue a bulk update of inventory policy for multiple variants", "description": "Queues a background job to update the inventory policy for multiple variants.\nThe operation is performed asynchronously to handle large numbers of variants efficiently.\nUpdates are processed in batches of up to 1000 variants to stay within message size limits.\n", "tags": [ "Preorders" ], "parameters": [ { "in": "header", "name": "X-Auth-Token", "required": true, "schema": { "type": "string" }, "description": "API key for authentication" }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Selling plan ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shopify_variant_ids": { "type": "array", "items": { "type": "integer" }, "description": "Array of Shopify variant IDs to update" }, "inventory_policy": { "type": "string", "enum": [ "CONTINUE", "DENY" ], "description": "The inventory policy to set for the variants" } }, "required": [ "shopify_variant_ids", "inventory_policy" ] }, "example": { "shopify_variant_ids": [ 43900910010503, 43900910010999 ], "inventory_policy": "CONTINUE" } } } }, "responses": { "200": { "description": "Inventory policy update has been queued successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "variants_queued": { "type": "array", "items": { "type": "integer" }, "description": "List of variant IDs that were queued for processing" } } }, "example": { "success": true, "message": "Inventory policy update queued", "variants_queued": [ 43900910010503, 43900910010999 ] } } } }, "400": { "description": "Bad request - missing or invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Selling plan not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Invalid inventory policy", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/external/preorders/{id}/update_variant_settings": { "patch": { "summary": "Update variant-specific settings for a selling plan", "tags": [ "Preorders" ], "parameters": [ { "in": "header", "name": "X-Auth-Token", "required": true, "schema": { "type": "string" }, "description": "API key for authentication" }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Selling plan ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shopify_variant_id": { "type": "integer", "description": "Shopify variant ID to update settings for" }, "shipping_text": { "type": [ "string", "null" ], "description": "Custom shipping text for this variant. Send null or an empty string to clear the override." }, "preorder_max_count": { "type": [ "integer", "null" ], "description": "Maximum number of preorders allowed for this variant. Send null or an empty string to clear the override." } }, "required": [ "shopify_variant_id" ] }, "example": { "shopify_variant_id": 43900910010503, "shipping_text": "Ships July 2026", "preorder_max_count": 100 } } } }, "responses": { "200": { "description": "Variant settings updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "variant": { "type": "object", "properties": { "shopify_variant_id": { "type": "integer" }, "shipping_text": { "type": "string" }, "preorder_max_count": { "type": "integer" } } } } }, "example": { "success": true, "message": "Variant settings updated", "variant": { "shopify_variant_id": 43900910010503, "shipping_text": "Ships July 2026", "preorder_max_count": 100 } } } } }, "400": { "description": "Bad request - missing required parameters or no settings to update", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Selling plan or variant not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Failed to update variant settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" }, "description": "List of validation error messages" } } } } } } }, "description": "Update per-variant preorder settings within a selling plan, such as the variant's custom `shipping_text` and `preorder_max_count` (the cap on preorder units). Identify the variant with `shopify_variant_id`; only the settings you include are changed. Returns the updated variant settings." } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Auth-Token", "description": "Authenticate by sending your shop’s STOQ API key in the `X-Auth-Token` header. Find it in the STOQ app under **Settings → Integrations → API Key** — keep it secret. Every request also needs the shop context: Preorders endpoints resolve it from the API key; the one public endpoint, Back in Stock **Create Intent**, takes no key and identifies the shop via the `X-Shopify-Shop-Domain` header instead." } }, "schemas": { "Intent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the intent" }, "blocked_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the intent was blocked from sending" }, "channel": { "type": "string", "description": "Communication channel used for notifications (e.g., Email, SMS)" }, "email": { "type": "string", "description": "Customer's email address for notifications" }, "notified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp of the notification sent" }, "optin_confirmed": { "type": "boolean", "description": "Whether the customer has confirmed their GDPR opt-in for notifications" }, "phone": { "type": "string", "description": "Customer's phone number for SMS notifications" }, "quantity": { "type": "integer", "description": "Requested quantity of the product when back in stock" }, "sent_notifications_count": { "type": "integer", "description": "Number of notifications sent for this intent" }, "source": { "type": "string" }, "type": { "type": "string", "description": "Type of the intent (e.g., restock, wishlist_reminder)" }, "unsubscribed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the customer unsubscribed from notifications" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the intent was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the intent was last updated" }, "customer_id": { "type": "string", "description": "Unique identifier for the customer" }, "intent_trigger_id": { "type": "string", "nullable": true, "description": "Identifier for the trigger that created this intent" }, "product_variant_id": { "type": "string", "nullable": true, "description": "Internal product variant identifier" }, "shop_id": { "type": "string", "description": "Unique identifier for the shop" }, "shopify_inventory_item_id": { "type": "integer", "nullable": true, "description": "Shopify's inventory item identifier" }, "shopify_market_id": { "type": "integer", "nullable": true, "description": "Shopify's market identifier for multi-market stores" }, "shopify_product_id": { "type": "integer", "nullable": true, "description": "Shopify's product identifier" }, "shopify_variant_id": { "type": "integer", "nullable": true, "description": "Shopify's variant identifier" }, "customer_name": { "type": "string", "nullable": true, "description": "Customer's full name" }, "contact": { "type": "string", "nullable": true, "description": "Customer's contact information" }, "customer_unsubscribed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the customer unsubscribed from all notifications" }, "accepts_marketing": { "type": "boolean", "nullable": true, "description": "Whether the customer has opted in to receive marketing communications" }, "notifications_count": { "type": "integer", "nullable": true, "description": "Total number of notifications sent for this intent" } } }, "ProductVariantDemand": { "type": "object", "description": "Product variant with demand metrics and product data", "properties": { "shopify_variant_id": { "type": "integer", "description": "Shopify variant identifier" }, "shopify_product_id": { "type": "integer", "description": "Shopify product identifier" }, "shopify_inventory_item_id": { "type": "integer", "nullable": true, "description": "Shopify inventory item identifier" }, "total": { "type": "integer", "description": "Total number of intents (both pending and sent) for this variant" }, "pending": { "type": "integer", "description": "Number of pending (unsent) intents for this variant" }, "last_requested_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp of the most recent intent created for this variant" }, "product_data": { "type": "object", "nullable": true, "description": "Shopify product data including variants", "properties": { "id": { "type": "integer", "description": "Shopify product ID" }, "title": { "type": "string", "description": "Product title" }, "vendor": { "type": "string", "description": "Product vendor/brand" }, "variants": { "type": "array", "description": "Array of product variants", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Shopify variant ID" }, "title": { "type": "string", "description": "Variant title (e.g., \"Medium / Red\")" }, "sku": { "type": "string", "description": "Variant SKU" } } } } } }, "variant_data": { "type": "object", "nullable": true, "description": "Specific variant data for this demand entry", "properties": { "id": { "type": "integer", "description": "Shopify variant ID" }, "title": { "type": "string", "description": "Variant title (e.g., \"Medium / Red\")" }, "sku": { "type": "string", "description": "Variant SKU" } } } } }, "SellingPlanInput": { "type": "object", "description": "Input schema for creating or updating selling plans", "properties": { "name": { "type": "string", "description": "Display name of the selling plan" }, "internal_name": { "type": "string", "description": "Internal name for the selling plan" }, "enabled": { "type": "boolean", "description": "Whether the selling plan is enabled" }, "billing_type": { "type": "string", "enum": [ "exact_time", "no_remaining_balance", "time_after_checkout" ], "description": "Type of billing for the selling plan" }, "billing_at": { "type": "string", "format": "date-time", "description": "Exact billing time if billing_type is exact_time" }, "billing_after_n_intervals": { "type": "integer", "description": "Number of intervals after checkout to bill" }, "billing_after_interval_type": { "type": "string", "enum": [ "day" ], "description": "Type of interval for billing" }, "billing_checkout_charge_amount": { "type": "number", "description": "Fixed amount to charge at checkout" }, "billing_checkout_charge_percentage": { "type": "number", "description": "Percentage to charge at checkout" }, "billing_checkout_charge_type": { "type": "string", "enum": [ "percentage", "price" ], "description": "Type of checkout charge" }, "billing_title": { "type": "string", "description": "Title for billing section" }, "billing_description": { "type": "string", "description": "Description for billing section" }, "delivery_type": { "type": "string", "enum": [ "anchor", "asap", "exact_time", "unknown" ], "description": "Type of delivery for the selling plan" }, "delivery_at": { "type": "string", "format": "date-time", "description": "Exact delivery time if delivery_type is exact_time" }, "delivery_after_n_intervals": { "type": "integer", "description": "Number of intervals after checkout for delivery" }, "delivery_after_interval_type": { "type": "string", "enum": [ "day" ], "description": "Type of interval for delivery" }, "inventory_reserve_type": { "type": "string", "enum": [ "on_sale", "on_fulfillment" ], "description": "When to reserve inventory" }, "inventory_provider": { "type": "string", "enum": [ "stoq", "shopify" ], "description": "Inventory provider" }, "pricing_type": { "type": "string", "enum": [ "percentage", "price", "fixed_amount", "no_discount" ], "description": "Type of pricing discount" }, "pricing_amount": { "type": "number", "description": "Fixed discount amount" }, "pricing_percentage": { "type": "number", "description": "Percentage discount" }, "quantity_limit_text": { "type": "string", "description": "Text to display for quantity limits" }, "preorder_button_text": { "type": "string", "description": "Text for the preorder button" }, "preorder_button_text_color": { "type": "string", "description": "Text color for the preorder button" }, "preorder_button_background_color": { "type": "string", "description": "Background color for the preorder button" }, "preorder_button_colors_enabled": { "type": "boolean", "description": "Whether custom colors are enabled for the preorder button" }, "preorder_discounted_price_enabled": { "type": "boolean", "description": "Whether to show discounted price on the preorder button" }, "preorder_button_description": { "type": "string", "description": "Description text for the preorder button" }, "preorder_button_description_background_color": { "type": "string", "description": "Background color for the preorder button description" }, "preorder_button_description_border_radius": { "type": "string", "description": "Border radius for the preorder button description" }, "preorder_button_description_quantity_limit_suffix": { "type": "string", "description": "Suffix text for quantity limit in button description" }, "preorder_button_description_shipping_text_prefix": { "type": "string", "description": "Prefix text for shipping information in button description" }, "preorder_button_description_show_quantity_limit": { "type": "boolean", "description": "Whether to show quantity limit in button description" }, "preorder_button_description_show_shipping": { "type": "boolean", "description": "Whether to show shipping information in button description" }, "preorder_button_description_text_color": { "type": "string", "description": "Text color for the preorder button description" }, "preorder_badge_enabled": { "type": "boolean", "description": "Whether preorder badge is enabled" }, "preorder_badge_text": { "type": "string", "description": "Text for the preorder badge" }, "preorder_badge_text_color": { "type": "string", "description": "Text color for the preorder badge" }, "preorder_badge_background_color": { "type": "string", "description": "Background color for the preorder badge" }, "preorder_shipping_text": { "type": "string", "description": "Shipping text specific to preorders" }, "shipping_text": { "type": "string", "description": "Shipping information text" }, "shipping_line_item_property_enabled": { "type": "boolean", "description": "Whether to enable shipping line item properties" }, "shipping_applies_to_all_products": { "type": "boolean", "description": "Whether shipping settings apply to all products" }, "discount_text": { "type": "string", "description": "Discount information text" }, "preorder_tags": { "type": "string", "description": "Tags to apply to preorder items" }, "product_variants_source": { "type": "string", "enum": [ "all", "collection", "custom" ], "description": "Source of product variants for this selling plan" }, "product_variants_source_id": { "type": "integer", "description": "ID of the source (e.g., collection ID)" }, "markets_enabled": { "type": "boolean", "description": "Whether market-specific settings are enabled for this selling plan" }, "shopify_market_ids": { "type": "array", "items": { "type": "integer" }, "description": "List of Shopify market IDs where this selling plan is available. Required if markets_enabled is true." }, "auto_collect_payment": { "type": "boolean", "description": "Whether to automatically collect payment when the order is ready to fulfill" }, "use_shopify_selling_plan": { "type": "boolean", "description": "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": { "type": "boolean", "description": "Whether to display the payment/billing widget on the product page" }, "split_fulfillments_enabled": { "type": "boolean", "description": "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": { "type": "boolean", "description": "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": { "type": "boolean", "description": "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." }, "require_preorder_acknowledgement": { "type": "boolean", "description": "Whether customers must accept terms and conditions before adding a preorder item to their cart." }, "preorder_acknowledgement_text": { "type": "string", "description": "The terms and conditions text that customers must acknowledge when require_preorder_acknowledgement is enabled." }, "allow_mixed_cart": { "type": "boolean", "description": "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": { "type": "string", "description": "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": { "type": "integer", "description": "Minimum quantity required per order for preorder items. When set, customers must purchase at least this many units." }, "preorder_max_quantity": { "type": "integer", "description": "Maximum quantity allowed per order for preorder items. When set, customers cannot purchase more than this many units." }, "payment_line_item_property_enabled": { "type": "boolean", "description": "Whether to add payment information as a line item property (e.g., \"Payment - Pay in full\")." }, "custom_line_item_property_text": { "type": "string", "description": "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": { "type": "boolean", "description": "Whether to automatically collect remaining payment when the order is fulfilled (for partial payment preorders)." }, "hold_fulfillments_enabled": { "type": "boolean", "description": "Whether to automatically hold fulfillments for preorder items. When enabled, fulfillments will be held until manually released." }, "hold_fulfillments_reason_note": { "type": "string", "description": "The reason note displayed when fulfillments are held (when hold_fulfillments_enabled is true)." }, "disable_button_until_acknowledged": { "type": "boolean", "description": "Whether to disable the add to cart button until the customer acknowledges the preorder terms (when require_preorder_acknowledgement is true)." } } }, "SellingPlan": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the selling plan" }, "name": { "type": "string", "description": "Display name of the selling plan" }, "internal_name": { "type": "string", "description": "Internal name for the selling plan" }, "enabled": { "type": "boolean", "description": "Whether the selling plan is enabled" }, "billing_type": { "type": "string", "enum": [ "exact_time", "no_remaining_balance", "time_after_checkout" ], "description": "Type of billing for the selling plan" }, "billing_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Exact billing time if billing_type is exact_time" }, "billing_after_n_intervals": { "type": "integer", "nullable": true, "description": "Number of intervals after checkout to bill" }, "billing_after_interval_type": { "type": "string", "enum": [ "day" ], "description": "Type of interval for billing" }, "billing_checkout_charge_amount": { "type": "number", "nullable": true, "description": "Fixed amount to charge at checkout" }, "billing_checkout_charge_percentage": { "type": "number", "nullable": true, "description": "Percentage to charge at checkout" }, "billing_checkout_charge_type": { "type": "string", "enum": [ "percentage", "price" ], "description": "Type of checkout charge" }, "billing_title": { "type": "string", "description": "Title for billing section" }, "billing_description": { "type": "string", "description": "Description for billing section" }, "delivery_type": { "type": "string", "enum": [ "anchor", "asap", "exact_time", "unknown" ], "description": "Type of delivery for the selling plan" }, "delivery_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Exact delivery time if delivery_type is exact_time" }, "delivery_after_n_intervals": { "type": "integer", "nullable": true, "description": "Number of intervals after checkout for delivery" }, "delivery_after_interval_type": { "type": "string", "enum": [ "day" ], "description": "Type of interval for delivery" }, "inventory_reserve_type": { "type": "string", "enum": [ "on_sale", "on_fulfillment" ], "description": "When to reserve inventory" }, "inventory_provider": { "type": "string", "enum": [ "stoq", "shopify" ], "description": "Inventory provider" }, "pricing_type": { "type": "string", "enum": [ "percentage", "price", "fixed_amount", "no_discount" ], "description": "Type of pricing discount" }, "pricing_amount": { "type": "number", "nullable": true, "description": "Fixed discount amount" }, "pricing_percentage": { "type": "number", "nullable": true, "description": "Percentage discount" }, "quantity_limit_text": { "type": "string", "description": "Text to display for quantity limits" }, "preorder_button_text": { "type": "string", "description": "Text for the preorder button" }, "preorder_button_text_color": { "type": "string", "description": "Text color for the preorder button" }, "preorder_button_background_color": { "type": "string", "description": "Background color for the preorder button" }, "preorder_button_colors_enabled": { "type": "boolean", "description": "Whether custom colors are enabled for the preorder button" }, "preorder_discounted_price_enabled": { "type": "boolean", "description": "Whether to show discounted price on the preorder button" }, "preorder_button_description": { "type": "string", "description": "Description text for the preorder button" }, "preorder_button_description_background_color": { "type": "string", "description": "Background color for the preorder button description" }, "preorder_button_description_border_radius": { "type": "string", "description": "Border radius for the preorder button description" }, "preorder_button_description_quantity_limit_suffix": { "type": "string", "description": "Suffix text for quantity limit in button description" }, "preorder_button_description_shipping_text_prefix": { "type": "string", "description": "Prefix text for shipping information in button description" }, "preorder_button_description_show_quantity_limit": { "type": "boolean", "description": "Whether to show quantity limit in button description" }, "preorder_button_description_show_shipping": { "type": "boolean", "description": "Whether to show shipping information in button description" }, "preorder_button_description_text_color": { "type": "string", "description": "Text color for the preorder button description" }, "preorder_badge_enabled": { "type": "boolean", "description": "Whether preorder badge is enabled" }, "preorder_badge_text": { "type": "string", "description": "Text for the preorder badge" }, "preorder_badge_text_color": { "type": "string", "description": "Text color for the preorder badge" }, "preorder_badge_background_color": { "type": "string", "description": "Background color for the preorder badge" }, "preorder_shipping_text": { "type": "string", "description": "Shipping text specific to preorders" }, "shipping_text": { "type": "string", "description": "Shipping information text" }, "shipping_line_item_property_enabled": { "type": "boolean", "description": "Whether to enable shipping line item properties" }, "shipping_applies_to_all_products": { "type": "boolean", "description": "Whether shipping settings apply to all products" }, "discount_text": { "type": "string", "description": "Discount information text" }, "preorder_tags": { "type": "string", "description": "Tags to apply to preorder items" }, "product_variants_source": { "type": "string", "enum": [ "all", "collection", "custom" ], "description": "Source of product variants for this selling plan" }, "product_variants_source_id": { "type": "integer", "nullable": true, "description": "ID of the source (e.g., collection ID)" }, "selling_plan_product_variants_count": { "type": "integer", "description": "Number of product variants associated with this selling plan" }, "shopify_selling_plan_id": { "type": "integer", "nullable": true, "description": "Shopify selling plan ID" }, "shopify_selling_plan_group_id": { "type": "integer", "nullable": true, "description": "Shopify selling plan group ID" }, "use_shopify_selling_plan": { "type": "boolean", "description": "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": { "type": "boolean", "description": "Whether to display the payment/billing widget on the product page" }, "split_fulfillments_enabled": { "type": "boolean", "description": "Whether to enable split fulfillments for preorders. When enabled, preorders will be separted into its own fulfillment order." }, "split_orders_enabled": { "type": "boolean", "description": "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": { "type": "boolean", "description": "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." }, "require_preorder_acknowledgement": { "type": "boolean", "description": "Whether customers must accept terms and conditions before adding a preorder item to their cart." }, "preorder_acknowledgement_text": { "type": "string", "description": "The terms and conditions text that customers must acknowledge when require_preorder_acknowledgement is enabled." }, "allow_mixed_cart": { "type": "boolean", "description": "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": { "type": "string", "description": "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": { "type": "integer", "nullable": true, "description": "Minimum quantity required per order for preorder items. When set, customers must purchase at least this many units." }, "preorder_max_quantity": { "type": "integer", "nullable": true, "description": "Maximum quantity allowed per order for preorder items. When set, customers cannot purchase more than this many units." }, "payment_line_item_property_enabled": { "type": "boolean", "description": "Whether to add payment information as a line item property (e.g., \"Payment - Pay in full\")." }, "custom_line_item_property_text": { "type": "string", "nullable": true, "description": "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": { "type": "boolean", "description": "Whether to automatically collect remaining payment when the order is fulfilled (for partial payment preorders)." }, "hold_fulfillments_enabled": { "type": "boolean", "description": "Whether to automatically hold fulfillments for preorder items. When enabled, fulfillments will be held until manually released." }, "hold_fulfillments_reason_note": { "type": "string", "description": "The reason note displayed when fulfillments are held (when hold_fulfillments_enabled is true)." }, "disable_button_until_acknowledged": { "type": "boolean", "description": "Whether to disable the add to cart button until the customer acknowledges the preorder terms (when require_preorder_acknowledgement is true)." }, "shop_id": { "type": "integer", "description": "Shop ID this selling plan belongs to" }, "market_id": { "type": "integer", "nullable": true, "description": "Market ID for multi-market stores" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the selling plan was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the selling plan was last updated" }, "discarded_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the selling plan was soft deleted" }, "ongoing_job": { "type": "boolean", "description": "Whether there is an ongoing job for this selling plan" }, "shopify_variant_ids": { "type": "array", "items": { "type": "integer" }, "description": "List of Shopify variant IDs associated with this selling plan" } } }, "SellingPlanProductVariantsResponse": { "type": "object", "properties": { "selling_plan_id": { "type": "string", "description": "ID of the selling plan" }, "selling_plan_name": { "type": "string", "description": "Name of the selling plan" }, "currency": { "type": "string", "description": "Shop currency code" }, "product_variants": { "type": "array", "items": { "$ref": "#/components/schemas/ProductVariantDetails" }, "description": "List of product variants associated with this selling plan" }, "meta": { "type": "object", "properties": { "total_variants": { "type": "integer", "description": "Total number of variants in results" }, "total_units_sold": { "type": "integer", "description": "Total units sold across all variants" } } } } }, "ProductVariantDetails": { "type": "object", "properties": { "shopify_product_id": { "type": "integer", "description": "Shopify product ID" }, "shopify_variant_id": { "type": "integer", "description": "Shopify variant ID" }, "product_title": { "type": "string", "description": "Product title" }, "variant_title": { "type": "string", "description": "Variant title (null for single-variant products)" }, "preorder_units_sold": { "type": "integer", "description": "Total units sold through preorders for this variant" }, "preorder_max_count": { "type": "integer", "nullable": true, "description": "Maximum number of preorders allowed for this variant" }, "shipping_text": { "type": "string", "nullable": true, "description": "Custom shipping text configured for this variant in the selling plan" } } }, "SellingPlanSingleVariantResponse": { "type": "object", "properties": { "selling_plan_id": { "type": "string", "description": "ID of the selling plan" }, "selling_plan_name": { "type": "string", "description": "Name of the selling plan" }, "currency": { "type": "string", "description": "Shop currency code" }, "product_variant": { "$ref": "#/components/schemas/ProductVariantDetails" }, "meta": { "type": "object", "properties": { "total_units_sold": { "type": "integer", "description": "Units sold for this variant" } } } } }, "SellingPlanList": { "type": "object", "description": "Simplified selling plan object for list views", "properties": { "id": { "type": "string", "description": "Unique identifier for the selling plan" }, "name": { "type": "string", "description": "Display name of the selling plan" }, "internal_name": { "type": "string", "description": "Internal name for the selling plan" }, "enabled": { "type": "boolean", "description": "Whether the selling plan is enabled" }, "selling_plan_product_variants_count": { "type": "integer", "description": "Number of product variants associated with this selling plan" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the selling plan was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the selling plan was last updated" }, "shopify_variant_ids": { "type": "array", "items": { "type": "integer" }, "description": "List of Shopify variant IDs associated with this selling plan" } } } } } }