{ "openapi": "3.1.0", "info": { "title": "STOQ API v2 (Beta)", "version": "2.0.0-beta", "description": "STOQ's action-driven, AI-native external API. Every action is self-describing (`description`, `aliases`, `notes`, JSON request schema) and also reachable via the `/help` manifest, `skill.md`, `llms.txt`, and the MCP server. **Public beta** — actions and schemas may change before GA. All endpoints require the `X-Auth-Token` API key.", "contact": { "name": "STOQ Support", "email": "support@stoqapp.com", "url": "https://app.stoqapp.com" } }, "servers": [ { "url": "https://app.stoqapp.com/api/v2/external", "description": "Production" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Account · Help Docs" }, { "name": "Account · Integrations" }, { "name": "Account · Languages" }, { "name": "Account · Locations" }, { "name": "Account · Markets" }, { "name": "Account · Plan Usage" }, { "name": "Account · Products" }, { "name": "Account · Sending" }, { "name": "Account · Settings" }, { "name": "Account · Setup" }, { "name": "Account · Templates" }, { "name": "Account · Translations" }, { "name": "Back In Stock · Copilot" }, { "name": "Back In Stock · Notifications" }, { "name": "Back In Stock · Orders" }, { "name": "Back In Stock · Products" }, { "name": "Back In Stock · Reports" }, { "name": "Back In Stock · Settings" }, { "name": "Back In Stock · Signups" }, { "name": "Back In Stock · Templates" }, { "name": "Preorders · Developer Settings" }, { "name": "Preorders · Notifications" }, { "name": "Preorders · Offer Lookup" }, { "name": "Preorders · Offers" }, { "name": "Preorders · Orders" }, { "name": "Preorders · Product Variants" }, { "name": "Preorders · Products" }, { "name": "Preorders · Reports" }, { "name": "Preorders · Settings" }, { "name": "Preorders · Templates" } ], "paths": { "/account/help_docs": { "get": { "operationId": "get_account_help_docs", "summary": "Get help docs", "description": "Search the STOQ help centre, or read one help article in full. Use for how-to and explanation questions — how a feature works, how to set something up, what a setting means. Search first, then read the article that matches before relaying step-by-step instructions; the snippets are previews, not the whole answer.", "tags": [ "Account · Help Docs" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "help docs", "help center", "search docs", "how do I", "documentation" ], "parameters": [ { "name": "query", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "url", "in": "query", "required": false, "schema": {}, "example": "https://example.com" }, { "name": "limit", "in": "query", "required": false, "schema": {}, "example": 5 } ] } }, "/account/integrations": { "get": { "operationId": "get_account_integrations", "summary": "Get integrations", "description": "Connection state of Klaviyo, Postscript, Omnisend and Mailchimp, where new signups are synced (Klaviyo, Omnisend, Mailchimp, Shopify customers, with the customer tag), the Mailchimp audience, and the Meta Pixel, Shopify Flow trigger and SplitOrder switches. Returns connected / verified flags only, never keys or tokens.", "tags": [ "Account · Integrations" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "integrations", "klaviyo connection", "postscript connection", "omnisend", "mailchimp", "customer sync" ] }, "patch": { "operationId": "patch_account_integrations", "summary": "Update integrations", "description": "Update the shop's integrations: sync signups to Klaviyo, Omnisend, Mailchimp or Shopify customers (with the customer tag), the Omnisend and Mailchimp API keys and Mailchimp audience, the Meta Pixel, Shopify Flow triggers and the SplitOrder app switch. API keys are write only; reads return connected flags.\n\n**Note:** Deep partial. omnisend.api_key and mailchimp.api_key are never returned by any read; an empty string removes the saved key. A Mailchimp key is checked by fetching the account's audiences and is not saved when Mailchimp refuses it; mailchimp.list_id must be one of those audiences. Klaviyo connects with OAuth from the Integrations page; this action only turns its sync on or off. flow_triggers.triggers replaces the stored list.", "tags": [ "Account · Integrations" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "connect omnisend", "connect mailchimp", "set mailchimp api key", "set omnisend api key", "pick mailchimp audience", "sync signups to klaviyo", "sync customers to shopify", "turn on meta pixel", "set meta pixel id", "enable shopify flow triggers", "enable splitorder", "customer sync tag" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "klaviyo": {}, "omnisend": {}, "mailchimp": {}, "shopify": {}, "sync_customers_tag": {}, "meta_pixel": {}, "flow_triggers": {}, "split_order_app": {} } }, "example": { "klaviyo": "string", "omnisend": "string", "mailchimp": "string", "shopify": "string", "sync_customers_tag": "string", "meta_pixel": "string", "flow_triggers": "string", "split_order_app": "string" } } } } } }, "/account/languages": { "get": { "operationId": "get_account_languages", "summary": "Get languages", "description": "The shop's languages: default_locale (the language alerts and the signup widget use), app_locale (the dashboard language), whether multi-language support and translated product titles are on, and, when multi-language is on, the locales published in Shopify.", "tags": [ "Account · Languages" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "languages", "alert language", "default language", "dashboard language", "multi language", "store locales" ] }, "patch": { "operationId": "patch_account_languages", "summary": "Update languages", "description": "Update the shop's language settings: the dashboard language (app_locale), multi-language alerts and widget, and translated product titles in alerts.\n\n**Note:** app_locale only changes the merchant dashboard. multi_language_enabled false also turns product_translations_enabled off. product_translations_enabled true needs the read_translations access the Settings page asks for; the call fails until it is granted.", "tags": [ "Account · Languages" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "change dashboard language", "use stoq in french", "turn on multi language", "send alerts in the customer's language", "use translated product titles" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "app_locale": {}, "multi_language_enabled": {}, "product_translations_enabled": {} } }, "example": { "app_locale": "fr", "multi_language_enabled": true, "product_translations_enabled": true } } } } } }, "/account/locations": { "get": { "operationId": "get_account_locations", "summary": "Get locations", "description": "The store's Shopify locations: id, name, and whether each is active. Use it to name the location ids in back-in-stock delivery settings and in markets.", "tags": [ "Account · Locations" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "locations", "shopify locations", "store locations", "warehouses" ] } }, "/account/markets": { "get": { "operationId": "get_account_markets", "summary": "Get markets", "description": "The store's Shopify Markets (international selling) configuration: active markets, whether the store sells to multiple markets, each market's countries, and which Shopify locations the merchant has linked to each market (location_ids). Distinct from an offer's market availability or restock-alert locations. Only active markets are returned by default.", "tags": [ "Account · Markets" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "markets", "shopify markets", "international selling", "which markets", "sell internationally" ], "parameters": [ { "name": "include_drafts", "in": "query", "required": false, "schema": {}, "example": "string" } ] } }, "/account/plan_usage": { "get": { "operationId": "get_account_plan_usage", "summary": "Get plan usage", "description": "The shop's current STOQ plan and a billing month's usage vs included limits, with the usage-based charges STOQ has metered.", "tags": [ "Account · Plan Usage" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "plan and usage", "billing", "usage charges", "what plan am I on", "how much have I used", "usage this month" ], "parameters": [ { "name": "period", "in": "query", "required": false, "schema": {}, "example": "string" } ] } }, "/account/products": { "get": { "operationId": "get_account_products", "summary": "Get products", "description": "List product variants with their preorder offer link (if any) and back-in-stock waitlist count, sorted by waitlist size (most demand first). search matches product name, variant title, SKU, a storefront/admin product URL, or a numeric/GID product or variant id. With match=product, search returns every variant of each matched product, not only the variants that matched.", "tags": [ "Account · Products" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "products", "find products", "product overview", "what's on preorder", "which products have the most demand", "find product", "look up product" ], "parameters": [ { "name": "filter", "in": "query", "required": false, "schema": { "enum": [ "all", "preorder", "back_in_stock" ] }, "example": "all" }, { "name": "match", "in": "query", "required": false, "schema": { "enum": [ "variant", "product" ] }, "example": "variant" }, { "name": "search", "in": "query", "required": false, "schema": {}, "example": "string" } ] } }, "/account/sending": { "get": { "operationId": "get_account_sending", "summary": "Get sending", "description": "Who sends the shop's customer notifications: the email provider (stoq, klaviyo, flow) and SMS provider, the sender address, sender name and reply-to, the custom sending domain and its DKIM check, whether SMS sending is approved, and whose account sends: `email_account` and `sms_account` are \"stoq\" (STOQ's own email or SMS service, including sms_provider \"twilio\") or \"merchant\" (their Klaviyo, Postscript or Shopify Flow with saved credentials); `email_sender_domain` is \"merchant\" when mail comes from their verified address.", "tags": [ "Account · Sending" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "email provider", "sms provider", "sender address", "from address", "custom sending domain", "sending settings" ] }, "patch": { "operationId": "patch_account_sending", "summary": "Update sending", "description": "Update who sends the shop's customer notifications: email and SMS provider, sender name, the merchant's own sending address, store domain in SMS links, Klaviyo marketing consent and the Postscript API key (write only). Also the email look every template shares: font, header and description text sizes, and logo size.\n\n**Note:** Applies to back-in-stock and preorder notifications. use_custom_email_address true needs email_reply_to_address on a domain that is not a free mail provider, and DKIM set up for it before mail goes out from it. postscript_api_key is never returned by any read; it is checked with Postscript and not saved when Postscript refuses it; \"\" removes it.", "tags": [ "Account · Sending" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "switch email provider", "send emails with klaviyo", "send emails from stoq", "switch sms provider", "use postscript", "set postscript api key", "change sender name", "send from my own email address", "use store domain in sms links", "change email font", "change email text size", "change email logo size" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email_provider": {}, "sms_provider": {}, "email_from_name": {}, "use_custom_email_address": {}, "email_reply_to_address": {}, "sms_custom_domain_enabled": {}, "klaviyo_skip_auto_subscribe": {}, "postscript_api_key": {}, "email_style": {} } }, "example": { "email_provider": "string", "sms_provider": "string", "email_from_name": "Summer Sneaker Drop", "use_custom_email_address": "string", "email_reply_to_address": "string", "sms_custom_domain_enabled": true, "klaviyo_skip_auto_subscribe": "string", "postscript_api_key": "string", "email_style": "string" } } } } } }, "/account/settings/{section_id}": { "get": { "operationId": "get_account_settings_section_id", "summary": "Get settings", "description": "One settings section: label, description, `settings` (the output of the read actions behind it, keyed by block, e.g. settings.widget is GET /back_in_stock/settings/widget), `columns` (field path => model column) and `raw` (field path => stored value). Sections: delivery_settings, signup_widget, notification_channels, notification_templates, preorder_notifications, preorder_pages, preorder_storefront_text, integrations, languages.", "tags": [ "Account · Settings" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "app settings", "current settings", "settings section", "notification settings", "delivery settings", "signup widget settings" ], "parameters": [ { "name": "section_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/account/setup": { "get": { "operationId": "get_account_setup", "summary": "Get setup", "description": "The shop's setup state: whether STOQ's app embed is on in the published theme (with the theme editor link that turns it on when it is off), and the getting-started steps for back in stock and preorders: each step's state, how many are done, the next one, and whether setup is complete.", "tags": [ "Account · Setup" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "setup status", "onboarding", "is the app embed on", "app embed", "getting started", "what is left to set up" ] } }, "/account/templates/{campaign_type}/translations": { "get": { "operationId": "get_account_templates_campaign_type_translations", "summary": "Get translations", "description": "Read every translation override on a notification template, plus the full enumeration of translatable field paths, each field's default-locale source text, and every locale the shop has actually published.", "tags": [ "Account · Templates" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "get notification translations", "template translations", "email translations", "sms translations", "push notification translations" ], "parameters": [ { "name": "campaign_type", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "position", "in": "query", "required": false, "schema": {}, "example": "string" } ] } }, "/account/translations": { "get": { "operationId": "get_account_translations", "summary": "Get translations", "description": "Read every translation override on the shop's notify-me button, signup form, and preorder button/modal text, plus the full enumeration of translatable field paths, each field's default-locale source text, and every locale the shop has actually published.", "tags": [ "Account · Translations" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "get widget translations", "signup form translations", "notify me translations", "shop translations" ] } }, "/back_in_stock/copilot/settings": { "get": { "operationId": "get_back_in_stock_copilot_settings", "summary": "Get settings", "description": "Read all back-in-stock settings for a Copilot preview.", "tags": [ "Back In Stock · Copilot" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "patch_back_in_stock_copilot_settings", "summary": "Update settings", "description": "Patch back-in-stock channels, delivery, compliance, tagging, or alerts settings. delivery.batching.mode \"multiplier\" sends restocked-quantity x multiplier per batch; \"fixed\" sends batch_size per batch. delivery.stock_threshold must be >= 1. delivery.locations.location_ids and delivery.any_variant.product_ids REPLACE the stored list wholesale; any_variant.all_products true ignores product_ids. Enabling SMS for the first time puts sends on a verification hold until the shop is approved.", "tags": [ "Back In Stock · Copilot" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "turn on back in stock email", "enable back in stock sms", "set stock threshold", "set batching", "back in stock alert settings" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channels": {}, "delivery": {}, "compliance": {}, "tagging": {}, "alerts": {} } }, "example": { "channels": "string", "delivery": "string", "compliance": "string", "tagging": "string", "alerts": "string" } } } } } }, "/back_in_stock/copilot/signups/{id}": { "get": { "operationId": "get_back_in_stock_copilot_signups_id", "summary": "Get signups", "description": "Read one back-in-stock signup for a Copilot preview.", "tags": [ "Back In Stock · Copilot" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/back_in_stock/copilot/signups/{id}/create": { "post": { "operationId": "post_back_in_stock_copilot_signups_id_create", "summary": "Create signups create", "description": "Create one back-in-stock signup for the selected variant. channel must be \"email\" or \"sms\"; pass email for the email channel or phone for sms.", "tags": [ "Back In Stock · Copilot" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "add a customer to the waitlist", "sign someone up for back in stock", "manually add signup", "add email to restock list" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": {}, "quantity": { "type": "integer" }, "email": {}, "phone": {}, "name": {} }, "required": [ "channel" ] }, "example": { "channel": "string", "quantity": 5, "email": "shopper@example.com", "phone": "+15551234567", "name": "Summer Sneaker Drop" } } } } } }, "/back_in_stock/copilot/signups/{id}/delete": { "post": { "operationId": "post_back_in_stock_copilot_signups_id_delete", "summary": "Create signups delete", "description": "Delete one pending back-in-stock signup.", "tags": [ "Back In Stock · Copilot" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "remove this signup", "delete waitlist entry", "take customer off the waitlist", "remove from back in stock list" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/back_in_stock/copilot/signups/{id}/notify": { "post": { "operationId": "post_back_in_stock_copilot_signups_id_notify", "summary": "Create signups notify", "description": "Queue a notification for one back-in-stock signup.", "tags": [ "Back In Stock · Copilot" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "notify this customer", "send the restock alert now", "manually notify signup", "resend back in stock alert" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "allow_resend": {} } }, "example": { "allow_resend": true } } } } } }, "/back_in_stock/copilot/signups/{id}/transfer": { "post": { "operationId": "post_back_in_stock_copilot_signups_id_transfer", "summary": "Create signups transfer", "description": "Transfer one pending back-in-stock signup to another variant. to_shopify_variant_id is the target Shopify variant ID (obtainable from get_offer_variants).", "tags": [ "Back In Stock · Copilot" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "move this signup to another variant", "transfer waitlist entry", "switch the variant on a signup", "move customer to a different size" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to_shopify_variant_id": {}, "to_shopify_product_id": {} }, "required": [ "to_shopify_variant_id" ] }, "example": { "to_shopify_variant_id": "45000000001", "to_shopify_product_id": "78000000001" } } } } } }, "/back_in_stock/notifications": { "get": { "operationId": "get_back_in_stock_notifications", "summary": "List notifications", "description": "List back-in-stock notifications (the send log) in this shop, paginated.\n\n**Note:** status=blocked surfaces sends that did not go out, with blocked_reason (the stored text), blocked_reason_code and blocked_reason_label. Every response has a summary (total, sent, blocked, blocked_by_reason) that counts every row matching the filters, not only this page. group_by=product returns counts per product (sent, blocked, and blocked by reason code) instead of rows, paginated by product. A bare from/to date is that whole day in the shop's time zone.", "tags": [ "Back In Stock · Notifications" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "list notifications", "back in stock send log", "restock notifications sent", "who got notified", "notification history", "show sent restock alerts" ], "parameters": [ { "name": "channel", "in": "query", "required": false, "schema": { "enum": [ "email", "sms", "push" ] }, "example": "email" }, { "name": "status", "in": "query", "required": false, "schema": { "enum": [ "sent", "blocked" ] }, "example": "sent" }, { "name": "group_by", "in": "query", "required": false, "schema": { "enum": [ "product" ] }, "example": "product" }, { "name": "variant_id", "in": "query", "required": false, "schema": {}, "example": "45000000001" }, { "name": "product_id", "in": "query", "required": false, "schema": {}, "example": "78000000001" }, { "name": "from", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "to", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "page", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "per_page", "in": "query", "required": false, "schema": {}, "example": "string" } ] } }, "/back_in_stock/notifications/{id}": { "get": { "operationId": "get_back_in_stock_notifications_id", "summary": "Get notifications", "description": "Read one back-in-stock notification (a single send-log entry).", "tags": [ "Back In Stock · Notifications" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "show notification", "get notification", "look up sent restock alert", "notification details" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/back_in_stock/orders": { "get": { "operationId": "get_back_in_stock_orders", "summary": "List orders", "description": "List orders placed after a back-in-stock alert, paginated. search matches order number/name, customer name, email, a Shopify order id (10+ digits), an order gid (gid://shopify/Order/), or a Shopify admin order URL.", "tags": [ "Back In Stock · Orders" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "list back in stock orders", "restock alert orders", "notification orders", "orders from restock alerts" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "per_page", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "search", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "customer_id", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "from", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "to", "in": "query", "required": false, "schema": {}, "example": "string" } ] } }, "/back_in_stock/products": { "get": { "operationId": "get_back_in_stock_products", "summary": "Get products", "description": "Read per-product back-in-stock configuration: notify-me button visibility (always_show / when_out_of_stock / never_show), restock message and assigned template for each variant, plus whether the shop-level per-product customization toggle is on. Each row also has the variant's pending and total signups and its lifetime back-in-stock units sold and revenue. Without search, rows are the variants STOQ has activity for (signups, per-product settings, offers), sorted by pending signups, most first. search (product name, variant title, SKU, product URL or id) also looks the term up in the Shopify catalog: matching variants STOQ has no row for come after the STOQ rows, with default settings and zero counts. Every row has has_stoq_activity; a search response has catalog_searched (false when the catalog was skipped or could not be reached). Filter with shopify_product_id, shopify_variant_id, overrides_only=true or has_waitlist=true; the last two only match STOQ rows, so they skip the catalog.", "tags": [ "Back In Stock · Products" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "which products have custom notify me settings", "per product back in stock config", "product button visibility", "products tab settings" ], "parameters": [ { "name": "shopify_product_id", "in": "query", "required": false, "schema": {}, "example": "78000000001" }, { "name": "shopify_variant_id", "in": "query", "required": false, "schema": {}, "example": "45000000001" }, { "name": "overrides_only", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "has_waitlist", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "limit", "in": "query", "required": false, "schema": {}, "example": 5 }, { "name": "search", "in": "query", "required": false, "schema": {}, "example": "string" } ] }, "patch": { "operationId": "patch_back_in_stock_products", "summary": "Update products", "description": "Update per-product back-in-stock configuration for one or more products or variants (the \"Back in stock alerts -> Products\" tab). `targets` is a list; a target with shopify_variant_id changes just that VARIANT, a target with only shopify_product_id changes EVERY variant of that product. The same field values are applied to every target, so send one call per distinct set of values. button_visibility is one of \"always_show\" (notify-me button shown even while the item is IN stock -- WARNING: this also DISABLES automatic back-in-stock alerts for that variant, so the merchant has to notify signups manually), \"when_out_of_stock\" (the default: button appears only when out of stock and alerts send automatically) or \"never_show\" (button hidden on the storefront). restock_message is the free-text note shown under the button (e.g. \"Back in stock March 15\"); send an empty string to clear it. template is a back-in-stock template name or id, or \"default\" to fall back to the global widget design. automatic_alerts_enabled (true/false) directly sets whether this variant receives an automatic back-in-stock alert on restock -- the same control as the variant's own \"Enable/Disable alerts\" button, independent of button_visibility. Use this to fix a variant showing \"Disabled\" for automatic alerts in get_bis_products (get_bis_products.automatic_alerts_enabled), not button_visibility. If both button_visibility: \"always_show\" and automatic_alerts_enabled are sent in the same call, automatic_alerts_enabled wins. Per-product visibility/message/template values only take effect while the shop-level toggle configure_notify_me_enabled is on; when it is off this action refuses rather than store values that would not apply, unless enable_customization: true is passed, which turns the toggle on as part of this change (a no-op when already on). automatic_alerts_enabled is NOT gated by configure_notify_me_enabled -- it applies regardless. per_product_customization_enabled (true/false), sent on its own with no targets, turns that shop-level toggle on or off (off = the tab's \"Disable per-product overrides\").\n\n**Note:** Bulk-safe: a single call may address up to 100 targets and writes them in one transaction with the Shopify metafield syncs fired once for the whole batch. A target STOQ has no product_variants row for is looked up in the shop's Shopify catalog; when it is there, its rows are created (one per variant for a product target) and the change is applied to them. Ids in neither are reported in `unmatched`. Deleting a back-in-stock template clears it from every product/variant it was assigned to (they fall back to the global design); template CRUD lives on the templates capability.", "tags": [ "Back In Stock · Products" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "hide the notify me button on these products", "always show the notify me button", "show the notify me button even when in stock", "hide notify me on discontinued products", "add a restock message to a product", "set a back in stock date on a product", "clear the restock note", "use a custom back in stock template on this product", "assign a template to a product", "per product notify me settings", "per product back in stock settings", "button visibility for a product", "disable per product overrides", "turn off per product customization" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "targets": {}, "button_visibility": {}, "restock_message": {}, "template": {}, "enable_customization": {}, "automatic_alerts_enabled": {}, "per_product_customization_enabled": {} } }, "example": { "targets": "string", "button_visibility": "string", "restock_message": "string", "template": "string", "enable_customization": "string", "automatic_alerts_enabled": true, "per_product_customization_enabled": true } } } } } }, "/back_in_stock/products/{variant_id}/notification_status": { "get": { "operationId": "get_back_in_stock_products_variant_id_notification_status", "summary": "Get notification status", "description": "Notification/waitlist status for one product variant: pending signups, total alerts sent, the 5 most recent send batches (each with what triggered it), and the shop's delivery settings -- the usual reason a restock produced no send yet.", "tags": [ "Back In Stock · Products" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "notification status", "restock alert status", "has this been notified", "waitlist status for a variant" ], "parameters": [ { "name": "variant_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/back_in_stock/reports": { "get": { "operationId": "get_back_in_stock_reports", "summary": "List reports", "description": "List every available back-in-stock report (name, description, aliases, url).", "tags": [ "Back In Stock · Reports" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "reports", "list reports", "available reports", "what reports are there", "report catalog" ] } }, "/back_in_stock/reports/conversions": { "get": { "operationId": "get_back_in_stock_reports_conversions", "summary": "Get conversions", "description": "Time-series of orders attributed to back-in-stock alerts, the revenue recovered, and the distinct customers who placed them.\n\n**Note:** Unscoped requests read the daily rollups plus today, as the Overview chart does; there unique_customers is summed per day, so a customer who bought on two days counts twice. range=all_time starts at the install date.", "tags": [ "Back In Stock · Reports" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "did the alerts convert", "recovered revenue", "conversion trend", "orders from alerts", "revenue recovered over time" ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "to", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "range", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "variant_id", "in": "query", "required": false, "schema": {}, "example": "45000000001" }, { "name": "product_id", "in": "query", "required": false, "schema": {}, "example": "78000000001" }, { "name": "channel", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "market_id", "in": "query", "required": false, "schema": {}, "example": "gid://shopify/Market/12345" }, { "name": "granularity", "in": "query", "required": false, "schema": {}, "example": "string" } ] } }, "/back_in_stock/reports/conversions/export": { "post": { "operationId": "post_back_in_stock_reports_conversions_export", "summary": "Create conversions export", "description": "Async CSV export of the back-in-stock conversions time series.", "tags": [ "Back In Stock · Reports" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "export conversions", "download conversions", "conversions csv", "recovered revenue csv" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": {}, "to": {}, "variant_id": {}, "product_id": {}, "channel": {}, "granularity": {}, "sort_by": {}, "direction": {}, "page": {}, "per_page": {} } }, "example": { "from": "string", "to": "string", "variant_id": "45000000001", "product_id": "78000000001", "channel": "string", "granularity": "string", "sort_by": "string", "direction": "string", "page": "string", "per_page": "string" } } } } } }, "/back_in_stock/reports/engagement": { "get": { "operationId": "get_back_in_stock_reports_engagement", "summary": "Get engagement", "description": "Back-in-stock \"Notify me\" button engagement/funnel analytics: impressions, clicks, click rate, signups, and signup rate — the same numbers on the merchant's back-in-stock Engagement dashboard. Rates use unique shoppers. This is button engagement, not conversion — for orders placed by notified customers use /back_in_stock/reports/summary.", "tags": [ "Back In Stock · Reports" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "notify me engagement", "back in stock funnel", "click rate", "signup rate", "back in stock button engagement" ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "to", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "market_id", "in": "query", "required": false, "schema": {}, "example": "gid://shopify/Market/12345" }, { "name": "variant_ids", "in": "query", "required": false, "schema": {}, "example": [ "45000000001" ] } ] } }, "/back_in_stock/reports/exports/{job_id}": { "get": { "operationId": "get_back_in_stock_reports_exports_job_id", "summary": "Get exports", "description": "Check the status of an async report export and get the download URL when ready.", "tags": [ "Back In Stock · Reports" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "check export status", "get export", "poll export", "download url for export", "export status" ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/back_in_stock/reports/notifications": { "get": { "operationId": "get_back_in_stock_reports_notifications", "summary": "Get notifications", "description": "Time-series of back-in-stock notifications sent, split by channel (email/sms/push), with blocked sends and the emails and delivered SMS messages behind them.\n\n**Note:** sent counts notifications by when they were sent; blocked by when they were attempted. emails_sent and sms_delivered count the messages behind them; unscoped requests read those two from the daily rollups, as the Overview chart does. range=all_time starts at the install date.", "tags": [ "Back In Stock · Reports" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "notification trend", "alerts sent", "sends by channel", "how many alerts went out", "blocked notifications" ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "to", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "range", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "variant_id", "in": "query", "required": false, "schema": {}, "example": "45000000001" }, { "name": "product_id", "in": "query", "required": false, "schema": {}, "example": "78000000001" }, { "name": "channel", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "market_id", "in": "query", "required": false, "schema": {}, "example": "gid://shopify/Market/12345" }, { "name": "granularity", "in": "query", "required": false, "schema": {}, "example": "string" } ] } }, "/back_in_stock/reports/notifications/export": { "post": { "operationId": "post_back_in_stock_reports_notifications_export", "summary": "Create notifications export", "description": "Async CSV export of the back-in-stock notifications time series.", "tags": [ "Back In Stock · Reports" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "export notifications", "download notifications", "notifications csv", "alerts csv" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": {}, "to": {}, "variant_id": {}, "product_id": {}, "channel": {}, "granularity": {}, "sort_by": {}, "direction": {}, "page": {}, "per_page": {} } }, "example": { "from": "string", "to": "string", "variant_id": "45000000001", "product_id": "78000000001", "channel": "string", "granularity": "string", "sort_by": "string", "direction": "string", "page": "string", "per_page": "string" } } } } } }, "/back_in_stock/reports/products_in_demand": { "get": { "operationId": "get_back_in_stock_reports_products_in_demand", "summary": "Get products in demand", "description": "Ranked variants (or products) by back-in-stock demand: signups waiting now, signups created in the window, last requested.\n\n**Note:** pending counts the waitlist now and ignores the window; total counts signups created in the window. group_by=product ranks products instead of variants.", "tags": [ "Back In Stock · Reports" ], "responses": { "200": { "description": "Success — example response shown.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "window": { "from": "2026-05-26T00:00:00Z", "to": "2026-06-25T23:59:59Z" }, "sort_by": "pending", "direction": "desc", "rows": [ { "shopify_variant_id": 47284734423096, "shopify_product_id": 8784906035384, "variant_title": "Blue / Medium", "product_title": "Classic Sneaker", "pending": 47, "total": 89, "last_requested_at": "2026-06-25T11:30:00Z" }, { "shopify_variant_id": 47284734455864, "shopify_product_id": 8784906035384, "variant_title": "Red / Large", "product_title": "Classic Sneaker", "pending": 23, "total": 56, "last_requested_at": "2026-06-25T09:15:00Z" } ], "meta": { "total_count": 287, "page": 1, "per_page": 50, "total_pages": 6 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "demand report", "what should I restock", "most wanted products", "top requested variants", "products in demand", "restock priorities" ], "parameters": [ { "name": "group_by", "in": "query", "required": false, "schema": { "enum": [ "variant", "product" ] }, "example": "variant" }, { "name": "from", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "to", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "range", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "variant_id", "in": "query", "required": false, "schema": {}, "example": "45000000001" }, { "name": "product_id", "in": "query", "required": false, "schema": {}, "example": "78000000001" }, { "name": "channel", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "market_id", "in": "query", "required": false, "schema": {}, "example": "gid://shopify/Market/12345" }, { "name": "sort_by", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "direction", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "page", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "per_page", "in": "query", "required": false, "schema": {}, "example": "string" } ] } }, "/back_in_stock/reports/products_in_demand/export": { "post": { "operationId": "post_back_in_stock_reports_products_in_demand_export", "summary": "Create products in demand export", "description": "Async CSV export of the back-in-stock products-in-demand report.", "tags": [ "Back In Stock · Reports" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "export demand report", "download products in demand", "demand csv", "restock list csv" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": {}, "to": {}, "variant_id": {}, "product_id": {}, "channel": {}, "granularity": {}, "sort_by": {}, "direction": {}, "page": {}, "per_page": {} } }, "example": { "from": "string", "to": "string", "variant_id": "45000000001", "product_id": "78000000001", "channel": "string", "granularity": "string", "sort_by": "string", "direction": "string", "page": "string", "per_page": "string" } } } } } }, "/back_in_stock/reports/signups": { "get": { "operationId": "get_back_in_stock_reports_signups", "summary": "Get signups", "description": "Time-series of back-in-stock signups created (day/week/month), with how many of them are still waiting and how many signups were notified in each bucket.\n\n**Note:** signups counts signups created in the bucket; pending is how many of those are waiting now; notified counts signups notified in the bucket. Unscoped requests read signups from the daily rollups, as the Overview chart does. range=all_time starts at the shop's install date.", "tags": [ "Back In Stock · Reports" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "signup trend", "signups over time", "waitlist growth", "new signups", "daily signups" ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "to", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "range", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "variant_id", "in": "query", "required": false, "schema": {}, "example": "45000000001" }, { "name": "product_id", "in": "query", "required": false, "schema": {}, "example": "78000000001" }, { "name": "channel", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "market_id", "in": "query", "required": false, "schema": {}, "example": "gid://shopify/Market/12345" }, { "name": "granularity", "in": "query", "required": false, "schema": {}, "example": "string" } ] } }, "/back_in_stock/reports/signups/export": { "post": { "operationId": "post_back_in_stock_reports_signups_export", "summary": "Create signups export", "description": "Async CSV export of the back-in-stock signups time series.", "tags": [ "Back In Stock · Reports" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "export signups", "download signups", "signups csv", "waitlist csv" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": {}, "to": {}, "variant_id": {}, "product_id": {}, "channel": {}, "granularity": {}, "sort_by": {}, "direction": {}, "page": {}, "per_page": {} } }, "example": { "from": "string", "to": "string", "variant_id": "45000000001", "product_id": "78000000001", "channel": "string", "granularity": "string", "sort_by": "string", "direction": "string", "page": "string", "per_page": "string" } } } } } }, "/back_in_stock/reports/summary": { "get": { "operationId": "get_back_in_stock_reports_summary", "summary": "Get summary", "description": "Back-in-stock totals over a window: signups created, signups waiting now, signups and distinct customers notified in the window, attributed orders, conversion rate and recovered revenue. range=all_time covers the shop's whole history.\n\n**Note:** Unscoped requests match the Back in Stock Overview: all-time signups, orders and revenue come from the shop's lifetime counters, a window's from the daily rollups plus today (source says which). pending and pending_by_channel are the waitlist now and ignore the window. last_notified_at is the latest send for the scope, whatever the window.", "tags": [ "Back In Stock · Reports" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "summary", "overview", "how is back in stock doing", "how many people are waiting", "waitlist size", "dashboard stats" ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "to", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "range", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "variant_id", "in": "query", "required": false, "schema": {}, "example": "45000000001" }, { "name": "product_id", "in": "query", "required": false, "schema": {}, "example": "78000000001" }, { "name": "channel", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "market_id", "in": "query", "required": false, "schema": {}, "example": "gid://shopify/Market/12345" } ] } }, "/back_in_stock/reports/summary/export": { "post": { "operationId": "post_back_in_stock_reports_summary_export", "summary": "Create summary export", "description": "Async CSV export of the back-in-stock summary report.", "tags": [ "Back In Stock · Reports" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "export summary", "download summary", "summary csv", "export overview" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": {}, "to": {}, "variant_id": {}, "product_id": {}, "channel": {}, "granularity": {}, "sort_by": {}, "direction": {}, "page": {}, "per_page": {} } }, "example": { "from": "string", "to": "string", "variant_id": "45000000001", "product_id": "78000000001", "channel": "string", "granularity": "string", "sort_by": "string", "direction": "string", "page": "string", "per_page": "string" } } } } } }, "/back_in_stock/reports/wait_duration": { "get": { "operationId": "get_back_in_stock_reports_wait_duration", "summary": "Get wait duration", "description": "How long back-in-stock shoppers have been waiting: median wait days, the longest wait, and a binned wait-time histogram (paid plans only). Also returns total_waiting, the current pending/opted-in signup count.", "tags": [ "Back In Stock · Reports" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "wait duration", "wait time", "how long are people waiting", "wait time histogram", "how long have customers waited" ], "parameters": [ { "name": "variant_id", "in": "query", "required": false, "schema": {}, "example": "45000000001" }, { "name": "product_id", "in": "query", "required": false, "schema": {}, "example": "78000000001" }, { "name": "market_id", "in": "query", "required": false, "schema": {}, "example": "gid://shopify/Market/12345" }, { "name": "from", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "to", "in": "query", "required": false, "schema": {}, "example": "string" } ] } }, "/back_in_stock/settings": { "get": { "operationId": "get_back_in_stock_settings", "summary": "Get settings", "description": "Read all back-in-stock settings for the shop.", "tags": [ "Back In Stock · Settings" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "get settings", "show settings", "view settings", "back in stock settings", "notification settings", "settings" ] }, "patch": { "operationId": "patch_back_in_stock_settings", "summary": "Update settings", "description": "Update back-in-stock settings for the shop.\n\n**Note:** Accepts any combination of capability blobs: channels, delivery, compliance, tagging, alerts, widget — deep partial, delegated to the capability PATCHes, errors accumulated. Boolean toggles are set via this PATCH (or the capability PATCH): channels.email.enabled, channels.sms.enabled, channels.push.enabled, delivery.batching.enabled, delivery.locations.filter_enabled, delivery.any_variant.enabled, compliance.optin_required, tagging.order_tags.enabled, alerts.signups_threshold.notify, alerts.scheduled_reports.daily, alerts.scheduled_reports.weekly, alerts.scheduled_reports.monthly, widget.placement.enabled — e.g. { channels: { sms: { enabled: true } } }.", "tags": [ "Back In Stock · Settings" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "edit settings", "change settings", "modify settings", "update back in stock settings", "configure notifications" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channels": {}, "delivery": {}, "compliance": {}, "tagging": {}, "alerts": {}, "widget": {} } }, "example": { "channels": "string", "delivery": "string", "compliance": "string", "tagging": "string", "alerts": "string", "widget": "string" } } } } } }, "/back_in_stock/settings/alerts": { "get": { "operationId": "get_back_in_stock_settings_alerts", "summary": "Get alerts", "description": "Read back-in-stock merchant alert and scheduled report settings.", "tags": [ "Back In Stock · Settings" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "get alert settings", "show alerts", "view signup threshold", "view scheduled reports", "alerts" ] }, "patch": { "operationId": "patch_back_in_stock_settings_alerts", "summary": "Update alerts", "description": "Update back-in-stock merchant alert and scheduled report settings.\n\n**Note:** Toggles set via this PATCH: signups_threshold.notify, signup_alerts.enabled, scheduled_reports.daily, scheduled_reports.weekly, scheduled_reports.monthly, notify_on_alert_sent — e.g. { scheduled_reports: { weekly: true } }. signups_threshold.count is the per-variant signup count that triggers the high-demand merchant alert email. signup_alerts.enabled turns on an immediate email to the merchant for every individual signup, sent to signup_alerts.email. scheduled_reports.email is the address that receives the daily/weekly/monthly summary reports. notify_on_alert_sent emails the merchant whenever back-in-stock alerts are sent to customers. merchant_emails.product_updates and merchant_emails.theme_published turn STOQ's own emails to the merchant on or off.", "tags": [ "Back In Stock · Settings" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "edit alert settings", "change alert settings", "set signup threshold", "notify me on high demand", "enable signup threshold alerts", "disable signup threshold alerts", "alert me when a product gets lots of signups", "enable daily report", "enable weekly report", "enable monthly report", "disable daily report", "disable weekly report", "disable monthly report", "schedule reports", "turn off report emails", "stop feature update emails", "notify me when a theme is published" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signups_threshold": {}, "signup_alerts": {}, "scheduled_reports": {}, "notify_on_alert_sent": {}, "merchant_emails": {} } }, "example": { "signups_threshold": "string", "signup_alerts": "string", "scheduled_reports": "string", "notify_on_alert_sent": "string", "merchant_emails": "string" } } } } } }, "/back_in_stock/settings/channels": { "get": { "operationId": "get_back_in_stock_settings_channels", "summary": "Get channels", "description": "Read back-in-stock notification channel settings.", "tags": [ "Back In Stock · Settings" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "get channels", "show channels", "view notification channels", "which channels are enabled", "channels" ] }, "patch": { "operationId": "patch_back_in_stock_settings_channels", "summary": "Update channels", "description": "Update back-in-stock notification channel toggles, and the master switch for automatic back-in-stock alerts.\n\n**Note:** Channel toggles are set via this PATCH: email.enabled, sms.enabled, push.enabled — e.g. { sms: { enabled: true } }. alerts_enabled false stops automatic back-in-stock alerts on every channel, whatever the channel switches say. Enabling SMS for the first time triggers a restricted-content verification check; sends may be held until the shop is verified.", "tags": [ "Back In Stock · Settings" ], "responses": { "200": { "description": "Success — example response shown.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "channels": { "email": { "enabled": true }, "sms": { "enabled": true }, "push": { "enabled": false } }, "delivery": { "batching": { "enabled": false }, "stock_threshold": 1, "locations": { "filter_enabled": false, "location_ids": [] } }, "compliance": { "optin_required": false, "optin_method": "single" }, "tagging": { "order_tags": { "enabled": false, "tags": [] } }, "alerts": { "scheduled_reports": { "weekly": true, "email": "merchant@example.com" } } } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "edit channels", "change channels", "modify channels", "turn off automatic alerts", "turn on automatic alerts", "pause back in stock alerts", "resume back in stock alerts", "send automatic notification", "enable email notifications", "turn on email alerts", "disable email notifications", "turn off email alerts", "enable sms", "turn on SMS alerts", "enable text notifications", "disable sms", "turn off SMS alerts", "stop text notifications", "enable push notifications", "turn on web push", "disable push notifications", "turn off web push" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "alerts_enabled": {}, "email": {}, "sms": {}, "push": {} } }, "example": { "channels": { "email": { "enabled": true }, "sms": { "enabled": true }, "push": { "enabled": false } } } } } } } }, "/back_in_stock/settings/compliance": { "get": { "operationId": "get_back_in_stock_settings_compliance", "summary": "Get compliance", "description": "Read back-in-stock compliance settings (double opt-in).", "tags": [ "Back In Stock · Settings" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "get compliance settings", "show compliance", "view opt-in settings", "is double opt-in enabled", "compliance" ] }, "patch": { "operationId": "patch_back_in_stock_settings_compliance", "summary": "Update compliance", "description": "Update back-in-stock compliance settings (double opt-in).\n\n**Note:** The double-opt-in toggle is set via this PATCH: optin_required — e.g. { optin_required: true }. When enabled, signups must confirm via email before they are eligible for notifications (GDPR double opt-in).", "tags": [ "Back In Stock · Settings" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "edit compliance settings", "change compliance settings", "require double opt-in", "enable double opt-in", "turn on double opt-in", "require opt-in confirmation", "gdpr opt-in", "disable double opt-in", "turn off double opt-in", "remove opt-in confirmation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "optin_required": {} } }, "example": { "optin_required": "string" } } } } } }, "/back_in_stock/settings/delivery": { "get": { "operationId": "get_back_in_stock_settings_delivery", "summary": "Get delivery", "description": "Read back-in-stock delivery settings (batching, stock threshold, locations, any-variant).", "tags": [ "Back In Stock · Settings" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "get delivery settings", "show delivery settings", "view batching", "view stock threshold", "view location filter", "delivery" ] }, "patch": { "operationId": "patch_back_in_stock_settings_delivery", "summary": "Update delivery", "description": "Update back-in-stock delivery settings (batching, stock threshold, locations, any-variant, password-protected sending, market setup, market-based alerts, alerts on publish).\n\n**Note:** Deep partial. Toggles set via this PATCH: batching.enabled, locations.filter_enabled, any_variant.enabled — e.g. { batching: { enabled: true } }. batching.mode is an enum: 'multiplier' (batch size = restocked quantity x batching.multiplier) or 'fixed' (batch size = batching.batch_size); batching.wait_hours is the wait between batches. stock_threshold is the minimum restocked quantity before notifications send (>= 1). any_variant.all_products is a boolean: when true, any-variant alerts apply to every product and any_variant.product_ids is ignored; when false, only the listed products qualify. locations.location_ids and any_variant.product_ids are arrays of Shopify numeric ids and are replaced wholesale when present. send_while_password_protected is a boolean: false (default) holds back-in-stock alerts while the storefront password is on (signups stay pending for the next restock); true sends anyway. market_setup is \"single_market\" or \"multiple_markets\"; market_locations_enabled turns on market-based alerts; alert_on_publish also alerts when a product is published.", "tags": [ "Back In Stock · Settings" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "edit delivery settings", "change delivery settings", "batch notifications", "enable batching", "turn on batching", "disable batching", "turn off batching", "send all at once", "set batch size", "set batching multiplier", "set batching mode", "set wait between batches", "set stock threshold", "set minimum stock to notify", "only notify when 5 in stock", "require minimum quantity before notifying", "filter by location", "enable location filter", "disable location filter", "set notification locations", "only count inventory at locations", "notify for any variant", "enable any variant notifications", "disable any variant notifications", "notify when any variant restocks", "send alerts while store is password protected", "hold alerts while store is password protected", "switch to multiple markets", "switch to single market", "enable market based alerts", "alert when a product is published", "notify customers when a product is published" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "batching": {}, "stock_threshold": {}, "locations": {}, "any_variant": {}, "send_while_password_protected": {}, "market_setup": {}, "market_locations_enabled": {}, "alert_on_publish": {} } }, "example": { "batching": "string", "stock_threshold": "string", "locations": "string", "any_variant": "string", "send_while_password_protected": "string", "market_setup": "gid://shopify/Market/12345", "market_locations_enabled": "gid://shopify/Market/12345", "alert_on_publish": "string" } } } } } }, "/back_in_stock/settings/tagging": { "get": { "operationId": "get_back_in_stock_settings_tagging", "summary": "Get tagging", "description": "Read back-in-stock order tagging settings.", "tags": [ "Back In Stock · Settings" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "get tagging settings", "show order tagging", "view order tag", "what tag is applied to recovered orders", "tagging" ] }, "patch": { "operationId": "patch_back_in_stock_settings_tagging", "summary": "Update tagging", "description": "Update back-in-stock order tagging settings.\n\n**Note:** The toggle is set via this PATCH: order_tags.enabled — e.g. { order_tags: { enabled: true } }. order_tags.tag is the single tag applied to Shopify orders attributed to a back-in-stock notification (default 'STOQ-back-in-stock').", "tags": [ "Back In Stock · Settings" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "edit tagging settings", "change tagging settings", "tag recovered orders", "enable order tagging", "turn on order tagging", "disable order tagging", "turn off order tagging", "set back in stock order tag", "change order tag", "rename order tag" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "order_tags": {} } }, "example": { "order_tags": "string" } } } } } }, "/back_in_stock/settings/widget": { "get": { "operationId": "get_back_in_stock_settings_widget", "summary": "Get widget", "description": "Read the storefront back-in-stock signup widget configuration: the notify-me button, where it appears, and the signup form's copy, styling and inputs.", "tags": [ "Back In Stock · Settings" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "get widget", "show signup widget", "view notify me button", "notify me button settings", "signup form settings", "widget" ], "parameters": [ { "name": "locale", "in": "query", "required": false, "schema": {}, "example": "fr" } ] }, "patch": { "operationId": "patch_back_in_stock_settings_widget", "summary": "Update widget", "description": "Update the storefront back-in-stock signup widget: the notify-me button (text, colors, corner radius, font, position), where the button appears (product, collection, home, search, preorder pages, and whether the whole widget is enabled), and the signup form's copy, success/error messages, colors, which inputs are collected and the double opt-in email text. button.position is \"auto\" (in-flow, directly below the sold-out add-to-cart button), \"float-right\" or \"float-left\" (a floating tab pinned to that edge of the page) or \"specific\" (after the element placement.selectors.product finds). placement.selectors holds the CSS selectors that place the button on product, collection, home and search pages; placement.hide_by_tag limits the widget by product tag; form.inline shows the form on the page instead of a popup; custom.css and custom.javascript run on every storefront page. form.fields.sms_first is a boolean: true shows the SMS field before email. form.fields.sms_default_country is a lowercase ISO 3166-1 alpha-2 code (e.g. \"us\", \"gb\", \"ca\", \"au\"). form.fields.sms_allowed_countries takes { add: [...], remove: [...] } of those same codes and edits the stored list in place — it never replaces it, so one country can be added or dropped without resending the rest; an empty allowed list means every country is allowed. Colors must be hex (#RRGGBB); radii are integers in pixels. Pass an optional top-level `locale` (e.g. \"fr\") to write the text fields for that language only.\n\n**Note:** Deep partial. Groups: button, placement (with selectors and hide_by_tag), form.copy, form.messages, form.style, form.fields, form.inline, optin, branding, custom. Selectors, the on-page form, custom CSS/JavaScript and the app proxy path change what every shopper sees; a wrong value can hide the widget. Channel enables (email/sms/push), optin_required and the merchant signup alert live on the other settings capabilities.", "tags": [ "Back In Stock · Settings" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "edit signup widget", "change notify me button", "move the notify me button", "put the notify me button below the sold out button", "change button text", "rename the notify me button", "change button color", "change button colour", "round the button corners", "change the widget font", "show the notify me button on collection pages", "show button on search results", "hide the notify me button", "turn off the signup widget", "turn on the signup widget", "change the signup form heading", "change the signup form wording", "change the signup success message", "change the signup error message", "change form colors", "collect customer name", "ask for quantity", "ask for marketing consent", "show the channel selector", "restrict sms signups to certain countries", "allow sms from another country", "set the default phone country", "change double opt in email", "hide powered by", "translate the signup form" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "locale": {}, "button": {}, "placement": {}, "form": {}, "optin": {}, "branding": {}, "custom": {} } }, "example": { "locale": "fr", "button": "string", "placement": "string", "form": "string", "optin": "string", "branding": "string", "custom": "string" } } } } } }, "/back_in_stock/signups": { "post": { "operationId": "post_back_in_stock_signups", "summary": "Create signups", "description": "Create a back-in-stock signup (add a customer to the waitlist for a variant).\n\n**Note:** email is required for the email channel, phone for sms. shopify_product_id is resolved from the variant when omitted. Returns 409 when a pending signup already exists for the same contact + variant + channel.", "tags": [ "Back In Stock · Signups" ], "responses": { "200": { "description": "Success — example response shown.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": 5847392, "status": "pending", "channel": "email", "contact": "john@example.com", "quantity": 2, "variant": { "shopify_variant_id": 47284734423096, "shopify_product_id": 8784906035384, "title": "Blue / Medium" }, "customer": { "id": 9284756, "email": "john@example.com", "name": "John Doe" }, "optin": { "required": false, "confirmed": null }, "notifications_sent": 0, "last_notified_at": null, "created_at": "2026-06-25T13:45:30Z" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "create signup", "add to waitlist", "add customer to the notify me list", "register a restock alert", "sign someone up for back in stock" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": { "enum": [ "email", "sms" ] }, "shopify_variant_id": {}, "quantity": { "type": "integer" }, "shopify_product_id": {}, "email": {}, "phone": {}, "name": {} }, "required": [ "channel", "shopify_variant_id" ] }, "example": { "channel": "email", "shopify_variant_id": 47284734423096, "shopify_product_id": 8784906035384, "email": "john@example.com", "quantity": 2, "name": "John Doe" } } } } }, "get": { "operationId": "get_back_in_stock_signups", "summary": "List signups", "description": "List back-in-stock signups (the waitlist) in this shop, paginated.\n\n**Note:** status compiles notified_at / unsubscribed_at / blocked_at into one lifecycle value; email and phone filters match partial values on the signup or its customer; query matches the customer's name, email or phone with one term (use email/phone instead to match only one). summary counts every signup matching the filters by status (total, pending, notified, blocked, unsubscribed), not only this page. A bare from/to date is that whole day in the shop's time zone.", "tags": [ "Back In Stock · Signups" ], "responses": { "200": { "description": "Success — example response shown.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "signups": [ { "id": 5847392, "status": "pending", "channel": "email", "contact": "john@example.com", "quantity": 2, "variant": { "shopify_variant_id": 47284734423096, "shopify_product_id": 8784906035384, "title": "Blue / Medium" }, "customer": { "id": 9284756, "email": "john@example.com", "name": "John Doe" }, "notifications_sent": 0, "last_notified_at": null, "created_at": "2026-06-25T13:45:30Z" }, { "id": 5847393, "status": "notified", "channel": "sms", "contact": "+14155552671", "quantity": 1, "variant": { "shopify_variant_id": 47284734455864, "shopify_product_id": 8784906035384, "title": "Red / Large" }, "customer": { "id": 9284757, "email": "jane@example.com", "name": "Jane Smith" }, "notifications_sent": 1, "last_notified_at": "2026-06-24T10:30:00Z", "created_at": "2026-06-20T15:20:15Z" } ], "meta": { "total_count": 147, "page": 1, "per_page": 50, "total_pages": 3 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "list signups", "waitlist", "show the waitlist", "notify me list", "who's waiting", "back in stock signups", "list waitlist entries", "restock signups", "customers waiting for restock" ], "parameters": [ { "name": "channel", "in": "query", "required": false, "schema": { "enum": [ "email", "sms", "push" ] }, "example": "email" }, { "name": "status", "in": "query", "required": false, "schema": { "enum": [ "pending", "notified", "blocked", "unsubscribed" ] }, "example": "pending" }, { "name": "variant_id", "in": "query", "required": false, "schema": {}, "example": "45000000001" }, { "name": "product_id", "in": "query", "required": false, "schema": {}, "example": "78000000001" }, { "name": "query", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "email", "in": "query", "required": false, "schema": {}, "example": "shopper@example.com" }, { "name": "phone", "in": "query", "required": false, "schema": {}, "example": "+15551234567" }, { "name": "from", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "to", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "page", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "per_page", "in": "query", "required": false, "schema": {}, "example": "string" } ] } }, "/back_in_stock/signups/{id}": { "delete": { "operationId": "delete_back_in_stock_signups_id", "summary": "Delete signups", "description": "Delete a pending back-in-stock signup (remove the customer from the waitlist).\n\n**Note:** Pending signups only; deleting an already-notified signup returns 409.", "tags": [ "Back In Stock · Signups" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "delete signup", "remove from waitlist", "remove waitlist entry", "cancel restock alert", "take customer off the notify me list" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "get": { "operationId": "get_back_in_stock_signups_id", "summary": "Get signups", "description": "Read one back-in-stock signup's full representation.", "tags": [ "Back In Stock · Signups" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "show signup", "get signup", "look up waitlist entry", "view restock signup", "signup details" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/back_in_stock/signups/{id}/notify": { "post": { "operationId": "post_back_in_stock_signups_id_notify", "summary": "Notify", "description": "Send the back-in-stock notification for one signup now, regardless of stock state.\n\n**Note:** 409 when the signup was already notified and allow_resend is not set.", "tags": [ "Back In Stock · Signups" ], "responses": { "200": { "description": "Success — example response shown.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "signup_id": 5847392, "queued": true } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "notify signup", "send the restock email", "notify this customer", "send back in stock notification", "resend restock notification" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "allow_resend": {} } }, "example": { "allow_resend": false } } } } } }, "/back_in_stock/signups/bulk_delete": { "post": { "operationId": "post_back_in_stock_signups_bulk_delete", "summary": "Bulk Delete", "description": "Delete up to 1000 pending back-in-stock signups in one request.\n\n**Note:** Pending-only: 422 listing the offending ids when any signup was already notified.", "tags": [ "Back In Stock · Signups" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "bulk delete signups", "clear the waitlist", "delete waitlist entries", "remove signups in bulk", "purge pending restock signups" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signup_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "signup_ids" ] }, "example": { "signup_ids": [ "sgn_a1b2c3" ] } } } } } }, "/back_in_stock/signups/bulk_notify": { "post": { "operationId": "post_back_in_stock_signups_bulk_notify", "summary": "Bulk Notify", "description": "Send back-in-stock notifications for up to 1000 signups in one request.\n\n**Note:** Responds 200 when all succeed, 207 with { success, failed } on partial failure. Already-notified signups fail unless allow_resend is set.", "tags": [ "Back In Stock · Signups" ], "responses": { "200": { "description": "Success — example response shown.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": [ 5847392, 5847393 ], "failed": [ { "signup_id": "5847394", "error": "Already notified — pass allow_resend to send again" } ] } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "bulk notify signups", "notify the waitlist", "notify everyone waiting", "send restock emails to the whole waitlist", "bulk send back in stock notifications" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signup_ids": { "type": "array", "items": { "type": "string" } }, "allow_resend": {} }, "required": [ "signup_ids" ] }, "example": { "signup_ids": [ "5847392", "5847393", "5847394" ], "allow_resend": false } } } } } }, "/back_in_stock/signups/transfer": { "post": { "operationId": "post_back_in_stock_signups_transfer", "summary": "Transfer", "description": "Move back-in-stock signups from one variant to another (variant merges or replacements).\n\n**Note:** scope picks which signups move: pending (default), notified, or all. Signups that would duplicate a pending signup on the target variant are dropped. from_shopify_product_id is resolved from the source variant when omitted.", "tags": [ "Back In Stock · Signups" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "transfer signups", "move the waitlist", "move signups to another variant", "merge waitlists", "shift restock signups to a new variant" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from_shopify_variant_id": {}, "to_shopify_variant_id": {}, "to_shopify_product_id": {}, "scope": { "enum": [ "pending", "notified", "all" ] }, "from_shopify_product_id": {} }, "required": [ "from_shopify_variant_id", "to_shopify_variant_id", "to_shopify_product_id" ] }, "example": { "from_shopify_variant_id": "45000000001", "to_shopify_variant_id": "45000000001", "to_shopify_product_id": "78000000001", "scope": "pending", "from_shopify_product_id": "78000000001" } } } } } }, "/back_in_stock/templates/{stage}/{locale}": { "get": { "operationId": "get_back_in_stock_templates_stage_locale", "summary": "Get templates", "description": "Read a localized back-in-stock notification template. stage is \"initial\" (the back-in-stock alert), \"reminder\" (the follow-up reminder) or \"signup_thank_you\" (the email/SMS sent right after a customer signs up). The numbers 0 and 1 are accepted as aliases for initial and reminder. Includes `enabled`, the stage's on/off switch.", "tags": [ "Back In Stock · Templates" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "get back in stock template", "show restock email", "back in stock notification", "restock reminder template", "localized back in stock template", "signup thank you email", "thank you for signing up template" ], "parameters": [ { "name": "stage", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "locale", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch_back_in_stock_templates_stage_locale", "summary": "Update templates", "description": "Update a localized back-in-stock notification template. stage is \"initial\" (the back-in-stock alert), \"reminder\" (the follow-up reminder) or \"signup_thank_you\" (the email/SMS sent right after a customer signs up); 0 and 1 are aliases for initial and reminder. `enabled` (true/false) turns the reminder or the signup thank-you on or off; the initial alert cannot be disabled here. email_button_destination and sms_link_destination each accept only \"checkout\" or \"product\". Social links (email_facebook_link, email_instagram_link, email_pinterest_link, email_twitter_link, email_tiktok_link, email_whatsapp_link, email_youtube_link) take the profile URL without https:// and show as icons in the email; they are the ONLY place for social links — never put links in the footer. Colours (email_background_color, email_text_color, email_button_background_color, email_button_text_color) are flat hex fields — there is no nested style object. email_template_enabled (true/false) is the \"Use HTML template\" switch: false goes back to the standard STOQ email, true uses the custom HTML email template (email_template). Colours, corner radii and the Judge.me reviews block are shared by every stage of the alert; social links, the social icon colour and email_unsubscribe_text by every template of the shop.\n\n**Note:** Deep partial over the template fields plus the stage's `enabled` switch. Rejects HTML except in email_template and email_css_config, and runs Template validations and callbacks. email_button_destination and sms_link_destination each accept only \"checkout\" or \"product\" (product page).", "tags": [ "Back In Stock · Templates" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "edit back in stock template", "change restock email", "change restock sms", "update back in stock reminder", "localize back in stock template", "add social links to email", "social media icons in restock email", "enable signup thank you email", "edit thank you for signing up email", "turn off restock reminder", "disable custom html template", "use standard email template", "turn off html email template" ], "parameters": [ { "name": "stage", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "locale", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "email_template_enabled": { "type": "boolean" }, "email_reviews_enabled": { "type": "boolean" }, "email_button_text": { "type": "string", "minLength": 1 }, "email_button_destination": { "type": "string", "minLength": 1 }, "email_description": { "type": "string", "minLength": 1 }, "email_footer": { "type": "string", "minLength": 1 }, "email_preheader": { "type": "string" }, "email_header": { "type": "string", "minLength": 1 }, "email_subject": { "type": "string", "minLength": 1 }, "push_body": { "type": "string", "minLength": 1 }, "push_button_text": { "type": "string", "minLength": 1 }, "push_title": { "type": "string", "minLength": 1 }, "sms_body": { "type": "string", "minLength": 1 }, "sms_link_destination": { "type": "string", "minLength": 1 }, "klaviyo_flow_name": { "type": "string" }, "klaviyo_sms_flow_name": { "type": "string" }, "email_background_color": { "type": "string", "minLength": 1 }, "email_text_color": { "type": "string", "minLength": 1 }, "email_button_background_color": { "type": "string", "minLength": 1 }, "email_button_text_color": { "type": "string", "minLength": 1 }, "email_facebook_link": { "type": "string" }, "email_instagram_link": { "type": "string" }, "email_pinterest_link": { "type": "string" }, "email_twitter_link": { "type": "string" }, "email_tiktok_link": { "type": "string" }, "email_whatsapp_link": { "type": "string" }, "email_youtube_link": { "type": "string" }, "email_social_icon_color": { "type": "string", "minLength": 1 }, "email_section_color": { "type": "string", "minLength": 1 }, "email_border_radius": {}, "email_button_border_radius": {}, "email_unsubscribe_text": { "type": "string", "minLength": 1 }, "email_reviews_title": { "type": "string", "minLength": 1 }, "email_reviews_count": {}, "email_reviews_min_rating": {}, "email_css_config": { "type": "string" }, "email_template": { "type": "string" } } }, "example": { "enabled": true, "email_template_enabled": true, "email_reviews_enabled": true, "email_button_text": "Preorder now", "email_button_destination": "string", "email_description": "string", "email_footer": "string", "email_preheader": "string", "email_header": "string", "email_subject": "string", "push_body": "string", "push_button_text": "Preorder now", "push_title": "string", "sms_body": "string", "sms_link_destination": "string", "klaviyo_flow_name": "Summer Sneaker Drop", "klaviyo_sms_flow_name": "Summer Sneaker Drop", "email_background_color": "#1A1A1A", "email_text_color": "#1A1A1A", "email_button_background_color": "#1A1A1A", "email_button_text_color": "#1A1A1A", "email_facebook_link": "string", "email_instagram_link": "string", "email_pinterest_link": "string", "email_twitter_link": "string", "email_tiktok_link": "string", "email_whatsapp_link": "string", "email_youtube_link": "string", "email_social_icon_color": "#1A1A1A", "email_section_color": "#1A1A1A", "email_border_radius": "string", "email_button_border_radius": "string", "email_unsubscribe_text": "Preorder now", "email_reviews_title": "string", "email_reviews_count": 5, "email_reviews_min_rating": "string", "email_css_config": "string", "email_template": "string" } } } } } }, "/preorders/developer_settings": { "get": { "operationId": "get_preorders_developer_settings", "summary": "Get developer settings", "description": "The preorder Developer settings: whether dev mode is on, and the custom CSS selectors that place the Preorder button and each preorder element on product pages. Shop-wide, not per offer. The selectors are used only while dev_mode_enabled is true.", "tags": [ "Preorders · Developer Settings" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "developer settings", "dev mode", "preorder selectors", "placement selectors", "insertion points" ] } }, "/preorders/notifications/{locale}": { "get": { "operationId": "get_preorders_notifications_locale", "summary": "Get notifications", "description": "Read shop-level preorder notification settings for a locale. `email_account` and `sms_account` say whose account sends: \"stoq\" or \"merchant\" (see GET /account/sending).", "tags": [ "Preorders · Notifications" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "get preorder notification settings", "show preorder notifications", "preorder email settings", "preorder sms settings", "shipping update email", "payment collection email" ], "parameters": [ { "name": "locale", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch_preorders_notifications_locale", "summary": "Update notifications", "description": "Update shop-level preorder notification settings for a locale. This edits shop-level toggles, provider (email_provider/sms_provider), sender name, and shipping-update / payment-collection copy — NOT the confirmation email body (use update_preorder_template for that). email_provider and sms_provider accept only the shop's enabled provider keys.\n\n**Note:** Deep partial. Validates booleans, provider enums, locale, length, and plain-text content; then runs Setting validations and provider/SMS verification callbacks.", "tags": [ "Preorders · Notifications" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "edit preorder notifications", "enable preorder email", "disable preorder sms", "change shipping update email", "change payment collection email", "change preorder notification provider" ], "parameters": [ { "name": "locale", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preorder_email_enabled": { "type": "boolean" }, "preorder_sms_enabled": { "type": "boolean" }, "preorder_cancellation_enabled": { "type": "boolean" }, "notify_payment_collection_enabled": { "type": "boolean" }, "email_provider": { "enum": [ "stoq", "klaviyo", "flow" ] }, "sms_provider": { "enum": [ "twilio", "telnyx", "infobip", "klaviyo", "postscript" ] }, "email_from_name": { "type": "string", "minLength": 1 }, "shipping_update_subject": { "type": "string", "minLength": 1 }, "shipping_update_header": { "type": "string", "minLength": 1 }, "shipping_update_description": { "type": "string", "minLength": 1 }, "payment_collection_email_subject": { "type": "string", "minLength": 1 }, "payment_collection_email_header": { "type": "string", "minLength": 1 }, "payment_collection_email_description": { "type": "string", "minLength": 1 }, "payment_collection_email_button_text": { "type": "string", "minLength": 1 }, "klaviyo_shipping_update_flow_name": { "type": "string", "minLength": 1 }, "klaviyo_payment_failed_flow_name": { "type": "string", "minLength": 1 } } }, "example": { "preorder_email_enabled": true, "preorder_sms_enabled": true, "preorder_cancellation_enabled": true, "notify_payment_collection_enabled": true, "email_provider": "stoq", "sms_provider": "twilio", "email_from_name": "Summer Sneaker Drop", "shipping_update_subject": "2026-07-01T00:00:00Z", "shipping_update_header": "2026-07-01T00:00:00Z", "shipping_update_description": "2026-07-01T00:00:00Z", "payment_collection_email_subject": "string", "payment_collection_email_header": "string", "payment_collection_email_description": "string", "payment_collection_email_button_text": "Preorder now", "klaviyo_shipping_update_flow_name": "Summer Sneaker Drop", "klaviyo_payment_failed_flow_name": "Summer Sneaker Drop" } } } } } }, "/preorders/offer_lookup": { "get": { "operationId": "get_preorders_offer_lookup", "summary": "Find", "description": "Resolve one preorder offer from an exact id or a fuzzy name match. Returns the full offer (same shape as GET /preorders/offers/:id) on a unique match. If `name` matches more than one offer, returns {ambiguous: true, candidates: [...]} instead of guessing -- re-call with the chosen id. Omit both id and name for the most recently created offer.", "tags": [ "Preorders · Offer Lookup" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "find offer", "resolve offer", "look up offer by name", "which offer", "the offer" ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "name", "in": "query", "required": false, "schema": {}, "example": "Summer Sneaker Drop" } ] } }, "/preorders/offers": { "post": { "operationId": "post_preorders_offers", "summary": "Create offers", "description": "Create a new preorder offer.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — example response shown.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "gid://shopify/SellingPlan/1", "name": "Summer Sneaker Drop", "internal_name": "summer-2026", "status": "draft", "created_at": "2026-06-25T10:30:45Z", "updated_at": "2026-06-25T10:30:45Z", "variants": { "count": 0, "url": "/api/v2/external/preorders/offers/1/products/variants" } } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "new offer", "make a preorder", "create preorder offer" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": {}, "internal_name": {} } }, "example": { "name": "Summer Sneaker Drop", "internal_name": "summer-2026" } } } } }, "get": { "operationId": "get_preorders_offers", "summary": "List offers", "description": "List preorder offers in this shop, paginated. search matches offer name, internal name, or an attached product's title. status filters by enabled/disabled/scheduled. market_ids narrows to offers restricted to those Shopify markets. sort orders by created date, name, or revenue.\n\n**Note:** expand adds capability blocks to each row, in the same shape as their own reads: inventory, shipping, payments, markets, products (comma-separated or an array). summary counts every offer matching the filters by state (total, active, scheduled, paused, ended), not only this page.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — example response shown.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "offers": [ { "id": "gid://shopify/SellingPlan/1", "name": "Summer Sneaker Drop", "internal_name": "summer-2026", "status": "draft", "created_at": "2026-06-25T10:30:45Z", "updated_at": "2026-06-25T10:30:45Z" }, { "id": "gid://shopify/SellingPlan/2", "name": "Winter Collection", "internal_name": "winter-2026", "status": "active", "created_at": "2026-06-20T14:15:30Z", "updated_at": "2026-06-22T09:45:12Z" } ], "meta": { "total_count": 2, "page": 1, "per_page": 50, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "list offers", "show all offers", "preorder offers", "all preorders" ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "enum": [ "all", "enabled", "disabled", "scheduled" ] }, "example": "all" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "created_at desc", "created_at asc", "internal_name asc", "internal_name desc", "preorder_revenue desc", "preorder_revenue asc" ] }, "example": "created_at desc" }, { "name": "page", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "per_page", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "search", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "market_ids", "in": "query", "required": false, "schema": {}, "example": [ "gid://shopify/Market/12345" ] }, { "name": "expand", "in": "query", "required": false, "schema": {}, "example": "string" } ] } }, "/preorders/offers/{id}": { "get": { "operationId": "get_preorders_offers_id", "summary": "Get offers", "description": "Read a preorder offer's full representation.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — example response shown.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "gid://shopify/SellingPlan/1", "name": "Summer Sneaker Drop", "internal_name": "summer-2026", "status": "active", "created_at": "2026-06-25T10:30:45Z", "updated_at": "2026-06-25T11:45:30Z", "variants": { "count": 3, "url": "/api/v2/external/preorders/offers/1/products/variants" }, "products": { "source": "custom", "custom": { "variant_ids_sample": [ 47284734423096, 47284734455864, 47284734488632 ] } }, "widget": { "button": { "text": "Preorder Now", "colors": { "enabled": true, "text_color": "#FFFFFF", "background_color": "#1a1a1a" } }, "disclaimer": { "enabled": true, "text": "Expected to ship by August 2026", "text_color": "#666666", "background_color": "#F5F5F5", "border_radius": "4px" }, "badge": { "enabled": true, "text": "Pre-Order", "text_color": "#FFFFFF", "background_color": "#FF6B35" } }, "shipping": { "delivery": { "applies_to_all_products": true, "type": "on_date", "days": null, "date": "2026-08-15T00:00:00Z" }, "display": { "show_details": true, "shipping_text": "Ships in August 2026", "shipping_line_item_property_enabled": true } }, "payments": { "mode": "full", "discount": { "type": null, "value": null }, "options": [ { "type": "full", "deposit_percent": null } ] }, "limits": { "per_order": { "min": 1, "max": 5 }, "per_customer": { "max": 2 }, "total": { "max": 500, "current_count": null }, "display": { "show_remaining": true, "quantity_limit_text": "Only 500 available" } }, "checkout": { "terms": { "enabled": true, "text": "I understand this is a pre-order and will ship in August", "disable_button_until_acknowledged": true }, "mixed_cart": { "allowed": false, "error_message": "Pre-orders cannot be mixed with regular items" }, "order_tags": { "tags": [ "preorder", "summer-2026" ] } }, "inventory": { "provider": "stoq", "reservation": { "timing": "on_sale" }, "continue_selling": { "enabled": true, "auto_apply_to_new_variants": true } }, "markets": { "enabled": false, "applies_to_all_markets": false, "market_ids": [] }, "countdown": { "enabled": true, "mode": "to_schedule_end", "format": "d:h:m:s", "text": "Offer ends in" }, "integrations": { "pos": { "enabled": true, "skip_inventory_check": false }, "b2b": { "enabled": false } }, "translations": { "default_locale": "en", "locales": [ "en", "fr" ], "fields": [ "widget.button.text" ], "translations": { "fr": { "widget.button.text": "Pré-commander" } } }, "advanced": { "use_shopify_selling_plan": false, "custom_css": ".preorder-badge { font-weight: bold; }" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "show offer", "get preorder offer", "look up offer", "view offer" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch_preorders_offers_id", "summary": "Update offers", "description": "Update top-level fields of a preorder offer.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "edit offer", "modify offer", "change offer settings" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": {}, "internal_name": {} } }, "example": { "name": "Summer Sneaker Drop", "internal_name": "summer-2026" } } } } } }, "/preorders/offers/{id}/advanced": { "get": { "operationId": "get_preorders_offers_id_advanced", "summary": "Get advanced", "description": "Read power-user settings for a preorder offer (line item properties, button text overrides, Shopify selling plan attachment).", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "get advanced", "show advanced settings", "view advanced settings", "view line item properties", "view advanced" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch_preorders_offers_id_advanced", "summary": "Update advanced", "description": "Update advanced (power-user) settings on a preorder offer.\n\n**Note:** Deep partial. Toggles and clears are done via this PATCH: the line-item-property toggles are `line_item_properties.include_shipping_text`, `.include_payment_breakdown`, and `.include_acknowledgement` (true/false each). `button_text_overrides` is deep-partial per state — send null to clear an override for one state, e.g. `{ \"button_text_overrides\": { \"out_of_stock\": null } }` removes that override (the read shape still emits all three states, with null for unset). sending an empty string or null.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "edit advanced", "change advanced settings", "modify advanced", "enable line item property", "include in line item properties", "add cart property", "show on cart line", "disable line item property", "exclude from line item properties", "remove cart property", "hide from cart line", "clear button text override", "remove button text override", "reset button text for state", "use default button text" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "line_item_properties": {}, "button_text_overrides": {}, "use_shopify_selling_plan": {} } }, "example": { "line_item_properties": "string", "button_text_overrides": "Preorder now", "use_shopify_selling_plan": "string" } } } } } }, "/preorders/offers/{id}/advanced/attach_to_shopify_selling_plan": { "post": { "operationId": "post_preorders_offers_id_advanced_attach_to_shopify_selling_plan", "summary": "Create advanced attach to shopify selling plan", "description": "Re-attach the offer to a Shopify selling plan group (resume syncing).\n\n**Note:** Refused while \"Move preorder items to a separate order\" is on (shipping fulfillment.split.type 'orders'): the Shopify purchase option can't be used with separate orders. Turn that off first.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "attach to shopify selling plan", "use shopify selling plans", "resume shopify sync", "reattach to shopify" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/preorders/offers/{id}/advanced/detach_from_shopify_selling_plan": { "post": { "operationId": "post_preorders_offers_id_advanced_detach_from_shopify_selling_plan", "summary": "Create advanced detach from shopify selling plan", "description": "Detach the offer from Shopify selling plan groups; Stoq continues to manage it via the storefront integration.\n\n**Note:** Strongly discouraged for most merchants. Breaks Shopify-native integrations like checkout selling plan display and third-party subscription apps. Does not delete the existing Shopify selling plan group — it just stops syncing. Also resets what needs the purchase option: partial payment to full payment, the discount to none, and a Scheduled fulfillment status to On hold. The response lists them in also_changed.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "detach from shopify selling plan", "stop using shopify selling plans", "manage selling plan internally", "bypass shopify selling plan" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/preorders/offers/{id}/advanced/set_button_text_override": { "post": { "operationId": "post_preorders_offers_id_advanced_set_button_text_override", "summary": "Create advanced set button text override", "description": "Override the widget button text for one state (before_launch, after_launch, or out_of_stock).", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set button text override", "override button text", "change button text for state", "set state button text" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "enum": [ "before_launch", "after_launch", "out_of_stock" ] }, "text": {} }, "required": [ "state", "text" ] }, "example": { "state": "before_launch", "text": "Preorder now" } } } } } }, "/preorders/offers/{id}/advanced/set_custom_line_item_property": { "post": { "operationId": "post_preorders_offers_id_advanced_set_custom_line_item_property", "summary": "Create advanced set custom line item property", "description": "Set a free-text custom line item property added to every preorder cart line.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set custom line item property", "set custom cart property", "set custom cart text", "add custom cart text" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": {} } }, "example": { "text": "Preorder now" } } } } } }, "/preorders/offers/{id}/checkout": { "get": { "operationId": "get_preorders_offers_id_checkout", "summary": "Get checkout", "description": "Read checkout settings for a preorder offer.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "get checkout settings", "show checkout", "view terms", "view mixed cart", "view order tags", "checkout" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch_preorders_offers_id_checkout", "summary": "Update checkout", "description": "Update checkout settings on a preorder offer.\n\n**Note:** Boolean toggles are set via this PATCH: terms.enabled, terms.disable_button_until_acknowledged, terms.include_in_line_item_properties, mixed_cart.allowed — this PATCH is how you turn these on/off, e.g. { terms: { enabled: true } } or { mixed_cart: { allowed: false } }.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "edit checkout", "change checkout settings", "modify checkout", "enable terms", "require terms", "require acknowledgement", "show terms checkbox", "turn on terms", "disable terms", "hide terms checkbox", "remove terms requirement", "turn off terms", "enable disable until acknowledged", "require acknowledgement before buying", "lock button until terms accepted", "grey out button until terms checked", "disable disable until acknowledged", "don't lock button on terms", "allow buying without acknowledging first", "keep button enabled before terms", "include terms in line item properties", "record terms acceptance on order", "add acknowledgement to line items", "show terms accepted on order", "allow mixed cart", "permit mixed cart", "enable mixed cart", "let preorders mix with regular items", "block mixed cart", "disable mixed cart", "prevent mixed cart", "force separate checkout" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "terms": {}, "mixed_cart": {}, "order_tags": {} } }, "example": { "terms": "string", "mixed_cart": "string", "order_tags": "string" } } } } } }, "/preorders/offers/{id}/checkout/add_order_tag": { "post": { "operationId": "post_preorders_offers_id_checkout_add_order_tag", "summary": "Create checkout add order tag", "description": "Add a tag to the set applied to orders containing this offer.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "add order tag", "add tag to preorder orders", "append order tag" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tag": {} }, "required": [ "tag" ] }, "example": { "tag": "string" } } } } } }, "/preorders/offers/{id}/checkout/remove_order_tag": { "post": { "operationId": "post_preorders_offers_id_checkout_remove_order_tag", "summary": "Create checkout remove order tag", "description": "Remove a tag from the set applied to orders containing this offer.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "remove order tag", "delete order tag", "drop order tag" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tag": {} }, "required": [ "tag" ] }, "example": { "tag": "string" } } } } } }, "/preorders/offers/{id}/checkout/set_mixed_cart_allowed": { "post": { "operationId": "post_preorders_offers_id_checkout_set_mixed_cart_allowed", "summary": "Create checkout set mixed cart allowed", "description": "Allow or block carts that mix preorder and regular items.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "allow mixed cart", "disable mixed cart", "block mixed carts", "dont allow mixed carts", "mixed cart orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "allowed": { "type": "boolean" } }, "required": [ "allowed" ] }, "example": { "allowed": true } } } } } }, "/preorders/offers/{id}/checkout/set_mixed_cart_error_message": { "post": { "operationId": "post_preorders_offers_id_checkout_set_mixed_cart_error_message", "summary": "Create checkout set mixed cart error message", "description": "Set the error message shown when a blocked mixed cart reaches checkout.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set mixed cart error message", "change mixed cart message", "set mixed cart warning", "customize mixed cart error" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": {} }, "required": [ "message" ] }, "example": { "message": "string" } } } } } }, "/preorders/offers/{id}/checkout/set_order_tags": { "post": { "operationId": "post_preorders_offers_id_checkout_set_order_tags", "summary": "Create checkout set order tags", "description": "Replace the set of tags applied to orders containing this offer.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set order tags", "replace order tags", "change order tags", "set tags on preorder orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": {} } }, "example": { "tags": "string" } } } } } }, "/preorders/offers/{id}/checkout/set_terms_settings": { "post": { "operationId": "post_preorders_offers_id_checkout_set_terms_settings", "summary": "Create checkout set terms settings", "description": "Require (or stop requiring) customers to accept preorder terms, with optional button-lock and acceptance-timestamp recording.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "require terms", "accept terms", "terms checkbox", "stop requiring terms", "record terms acceptance", "disable button until terms" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "disable_button_until": {}, "record_timestamp": {}, "timestamp_label": {} }, "required": [ "enabled" ] }, "example": { "enabled": true, "disable_button_until": "string", "record_timestamp": "string", "timestamp_label": "Preorder now" } } } } } }, "/preorders/offers/{id}/checkout/set_terms_text": { "post": { "operationId": "post_preorders_offers_id_checkout_set_terms_text", "summary": "Create checkout set terms text", "description": "Set the terms-acceptance text shown next to the checkbox.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set terms text", "change terms text", "update terms", "change acknowledgement text", "set fine print" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": {} }, "required": [ "text" ] }, "example": { "text": "Preorder now" } } } } } }, "/preorders/offers/{id}/countdown": { "get": { "operationId": "get_preorders_offers_id_countdown", "summary": "Get countdown", "description": "Read the countdown timer configuration for a preorder offer.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "get countdown", "show timer", "view countdown timer", "view timer settings", "countdown settings" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch_preorders_offers_id_countdown", "summary": "Update countdown", "description": "Update countdown timer settings on a preorder offer.\n\n**Note:** Deep partial. `countdown.enabled` is toggled via this PATCH (`enabled` true/false); `text` is an alias for `ends_text` — both write the same column, and an explicit `ends_text` wins when both are sent.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "edit countdown", "change timer", "modify countdown settings", "enable countdown", "show timer", "turn on countdown", "enable countdown timer", "disable countdown", "hide timer", "turn off countdown", "disable countdown timer", "set countdown text", "set timer text", "change countdown label", "set timer label" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": {}, "mode": {}, "custom_end_date": {}, "custom_start_date": {}, "format": {}, "text": {}, "starts_text": {}, "ends_text": {}, "unit_labels": {}, "style": {} } }, "example": { "enabled": true, "mode": "string", "custom_end_date": "2026-07-01T00:00:00Z", "custom_start_date": "2026-07-01T00:00:00Z", "format": "string", "text": "Preorder now", "starts_text": "Preorder now", "ends_text": "Preorder now", "unit_labels": "Preorder now", "style": "string" } } } } } }, "/preorders/offers/{id}/countdown/set_custom_end_date": { "post": { "operationId": "post_preorders_offers_id_countdown_set_custom_end_date", "summary": "Create countdown set custom end date", "description": "Set the custom end date for the countdown timer.\n\n**Note:** Has no visible effect unless mode is `to_custom_date`.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set custom end date", "set timer end date", "change timer deadline" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": {} }, "required": [ "date" ] }, "example": { "date": "2026-07-01T00:00:00Z" } } } } } }, "/preorders/offers/{id}/countdown/set_ends_text": { "post": { "operationId": "post_preorders_offers_id_countdown_set_ends_text", "summary": "Create countdown set ends text", "description": "Set the text shown next to the countdown timer when the offer is closing.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set ends text", "set timer end text", "set 'ends in' text" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": {} }, "required": [ "text" ] }, "example": { "text": "Preorder now" } } } } } }, "/preorders/offers/{id}/countdown/set_mode": { "post": { "operationId": "post_preorders_offers_id_countdown_set_mode", "summary": "Create countdown set mode", "description": "Set the countdown source: 'to_schedule_end' (count down to the offer's scheduled end) or 'to_custom_date' (count down to a fixed date set via set_custom_end_date).", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set countdown mode", "change timer mode", "use schedule for timer", "use custom date for timer" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "enum": [ "to_schedule_end", "to_custom_date" ] } }, "required": [ "mode" ] }, "example": { "mode": "to_schedule_end" } } } } } }, "/preorders/offers/{id}/countdown/set_starts_text": { "post": { "operationId": "post_preorders_offers_id_countdown_set_starts_text", "summary": "Create countdown set starts text", "description": "Set the text shown before the countdown timer when the offer hasn't started yet.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set starts text", "set timer pre-launch text", "set 'starts in' text" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": {} }, "required": [ "text" ] }, "example": { "text": "Preorder now" } } } } } }, "/preorders/offers/{id}/countdown/set_style": { "post": { "operationId": "post_preorders_offers_id_countdown_set_style", "summary": "Create countdown set style", "description": "Set the countdown timer's visual style (type, colors, border radius).", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set timer style", "change timer style", "set countdown style", "change timer colors" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": {}, "text_color": {}, "background_color": {}, "border_radius": {} } }, "example": { "type": "string", "text_color": "#1A1A1A", "background_color": "#1A1A1A", "border_radius": "string" } } } } } }, "/preorders/offers/{id}/countdown/set_unit_labels": { "post": { "operationId": "post_preorders_offers_id_countdown_set_unit_labels", "summary": "Create countdown set unit labels", "description": "Set the countdown timer unit labels (days, hours, minutes, seconds).", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "countdown labels", "timer labels", "rename days label", "change hours label", "countdown unit names" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "days": {}, "hours": {}, "minutes": {}, "seconds": {} } }, "example": { "days": "string", "hours": "string", "minutes": "string", "seconds": "string" } } } } } }, "/preorders/offers/{id}/disable": { "post": { "operationId": "post_preorders_offers_id_disable", "summary": "Disable", "description": "Disable (pause) a preorder offer. Optionally flip attached variants' inventory policy back to DENY.\n\n**Note:** Variants are left at their existing inventory policy unless `update_inventory_policy: true` is passed.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — example response shown.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "gid://shopify/SellingPlan/1", "name": "Summer Sneaker Drop", "internal_name": "summer-2026", "status": "paused", "updated_at": "2026-06-25T12:15:20Z", "variants": { "count": 3, "url": "/api/v2/external/preorders/offers/1/products/variants" } } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "pause", "turn off", "deactivate", "stop offer", "end preorder", "disable and stop overselling", "close out preorder" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "update_inventory_policy": {}, "variant_ids": {} } }, "example": { "update_inventory_policy": true } } } } } }, "/preorders/offers/{id}/discard": { "post": { "operationId": "post_preorders_offers_id_discard", "summary": "Create discard", "description": "Discard (soft-delete) a preorder offer.\n\n**Note:** Recoverable via restore indefinitely. Discarded offers are never hard-deleted.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "delete", "remove", "archive", "trash", "soft delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/preorders/offers/{id}/enable": { "post": { "operationId": "post_preorders_offers_id_enable", "summary": "Enable", "description": "Enable a preorder offer. On a scheduled offer this starts it now instead of on its start date (the start date is cleared; an end date is kept), as the dashboard does. Optionally flip attached variants' inventory policy to CONTINUE.\n\n**Note:** Variants are left at their existing inventory policy unless `update_inventory_policy: true` is passed. On a `scheduled` offer (start date in the future) enable starts the offer now: `schedule.start` is cleared, `schedule.end` is kept, and with no end date the schedule is removed. To keep the start date, do not call enable; the offer starts on its own.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — example response shown.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "gid://shopify/SellingPlan/1", "name": "Summer Sneaker Drop", "internal_name": "summer-2026", "status": "active", "updated_at": "2026-06-25T11:45:30Z", "variants": { "count": 3, "url": "/api/v2/external/preorders/offers/1/products/variants" } } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "turn on", "activate", "launch", "go live", "start offer" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "update_inventory_policy": {}, "variant_ids": {} } }, "example": { "update_inventory_policy": true } } } } } }, "/preorders/offers/{id}/integrations": { "get": { "operationId": "get_preorders_offers_id_integrations", "summary": "Get integrations", "description": "Read integration settings for a preorder offer (POS, B2B).", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "get integrations", "show integrations", "view pos settings", "view b2b settings", "integration settings" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch_preorders_offers_id_integrations", "summary": "Update integrations", "description": "Update integration settings on a preorder offer.\n\n**Note:** Boolean toggles are set via this PATCH: pos.enabled, pos.skip_inventory_check, b2b.enabled — e.g. { pos: { enabled: false } } or { b2b: { enabled: true } }.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "edit integrations", "change integration settings", "modify integrations", "enable pos", "turn on pos", "allow in pos", "enable point of sale", "disable pos", "turn off pos", "block from pos", "disable point of sale", "enable pos skip inventory check", "skip inventory check on pos", "bypass inventory at pos", "allow pos sale without inventory", "disable pos skip inventory check", "enforce inventory check at pos", "stop bypassing inventory at pos", "enable b2b", "turn on b2b", "allow b2b", "enable wholesale", "disable b2b", "turn off b2b", "block b2b", "disable wholesale" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pos": {}, "b2b": {} } }, "example": { "pos": "string", "b2b": "string" } } } } } }, "/preorders/offers/{id}/integrations/set_b2b_enabled": { "post": { "operationId": "post_preorders_offers_id_integrations_set_b2b_enabled", "summary": "Create integrations set B2b enabled", "description": "Allow or disallow B2B customers to place preorders on this offer.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "enable b2b", "disable b2b", "b2b preorders", "wholesale preorders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] }, "example": { "enabled": true } } } } } }, "/preorders/offers/{id}/integrations/set_pos_enabled": { "post": { "operationId": "post_preorders_offers_id_integrations_set_pos_enabled", "summary": "Create integrations set pos enabled", "description": "Enable or disable selling preorders on Shopify POS, with optional inventory-check skipping.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "sell on pos", "enable pos", "disable pos", "pos preorders", "skip pos inventory check" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "skip_inventory_check": {} }, "required": [ "enabled" ] }, "example": { "enabled": true, "skip_inventory_check": "string" } } } } } }, "/preorders/offers/{id}/inventory": { "get": { "operationId": "get_preorders_offers_id_inventory", "summary": "Get inventory", "description": "Read the inventory configuration for a preorder offer.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "get inventory settings", "show inventory", "view inventory policy", "view reservation timing", "view stock handling" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch_preorders_offers_id_inventory", "summary": "Update inventory", "description": "Update inventory settings on a preorder offer.\n\n**Note:** Deep partial. provider 'stoq' = the offer shows the Preorder button only when the product is OUT OF STOCK (the 'Show Preorder when product is out of stock' mode; needs Shopify's 'Continue selling when out of stock' on the variants). provider 'shopify' = the button shows for IN-STOCK products (the 'Show Preorder for in-stock products' mode). Setting provider to 'shopify' will force product_variants_source to 'custom' via the model callback. Continue-selling is toggled via this PATCH: `continue_selling.enabled` and `continue_selling.auto_apply_to_new_variants` BOTH map to the single underlying `inventory_policy_auto_enable` flag — the auto-flip-on-attach intent (newly-attached variants get their Shopify inventory_policy flipped to CONTINUE). When both fields are present, auto_apply_to_new_variants wins. Neither field flips EXISTING variants — to flip variants that are already attached, use POST .../products/bulk_toggle_inventory_policy, or pass the update_inventory_policy flag to the offer lifecycle enable/disable actions.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — example response shown.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "provider": "stoq", "reservation": { "timing": "on_sale" }, "continue_selling": { "enabled": true, "auto_apply_to_new_variants": true } } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "edit inventory", "change inventory settings", "modify inventory", "enable continue selling for the whole offer", "allow overselling", "enable oversell", "auto continue selling", "auto-apply continue selling on attach", "disable continue selling", "stop auto continue selling", "disable oversell", "prevent overselling on attach", "enable auto apply continue selling", "auto continue selling on attach", "auto-flip new variants to continue", "apply oversell to new variants", "disable auto apply continue selling", "stop auto continue selling on attach", "don't auto-flip new variants", "no oversell on new variants" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "enum": [ "stoq", "shopify" ] }, "reservation": { "type": "object", "properties": { "timing": { "enum": [ "on_sale", "on_fulfillment" ] } }, "required": [] }, "continue_selling": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "auto_apply_to_new_variants": { "type": "boolean" } }, "required": [] } } }, "example": { "continue_selling": { "enabled": true, "auto_apply_to_new_variants": true } } } } } } }, "/preorders/offers/{id}/inventory/set_provider": { "post": { "operationId": "post_preorders_offers_id_inventory_set_provider", "summary": "Create inventory set provider", "description": "Set the inventory provider for a preorder offer (stoq or shopify).", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set inventory provider", "switch inventory provider", "use shopify inventory", "use stoq inventory" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "enum": [ "stoq", "shopify" ] } }, "required": [ "provider" ] }, "example": { "provider": "stoq" } } } } } }, "/preorders/offers/{id}/inventory/set_reservation_timing": { "post": { "operationId": "post_preorders_offers_id_inventory_set_reservation_timing", "summary": "Create inventory set reservation timing", "description": "Set when inventory is reserved: on_sale (held at order time) or on_fulfillment.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set reservation timing", "reserve on sale", "reserve on fulfillment", "change inventory reservation", "set when inventory is held" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "timing": { "enum": [ "on_sale", "on_fulfillment" ] } }, "required": [ "timing" ] }, "example": { "timing": "on_sale" } } } } } }, "/preorders/offers/{id}/limits": { "get": { "operationId": "get_preorders_offers_id_limits", "summary": "Get limits", "description": "Read order quantity limits for a preorder offer.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "get limits", "show limits", "view quantity limits", "view order min max", "limits" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch_preorders_offers_id_limits", "summary": "Update limits", "description": "Update quantity limits on a preorder offer.\n\n**Note:** Deep partial. limit_per_product is copied onto every variant in the offer when it changes, replacing their own limits, as the editor does after its confirmation. Toggles and clears are done via this PATCH: clear a limit by sending null — `per_order.max: null` removes the per-order cap; `display.show_remaining` (true/false) toggles the remaining-units display on the storefront. Order tags, the terms-acceptance requirement, and mixed-cart behavior live on the `checkout` capability instead (PATCH .../checkout), not here.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "edit limits", "change limits", "modify quantity limits", "enable show remaining", "show remaining units", "show stock left", "display quantity remaining", "disable show remaining", "hide remaining units", "hide stock left", "stop showing quantity" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit_per_product": {}, "per_order": {}, "display": {} } }, "example": { "limit_per_product": 5, "per_order": "string", "display": "string" } } } } } }, "/preorders/offers/{id}/limits/set_icons_enabled": { "post": { "operationId": "post_preorders_offers_id_limits_set_icons_enabled", "summary": "Create limits set icons enabled", "description": "Show or hide icons next to the quantity and shipping details on the widget.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "show icons", "hide icons", "enable icons", "disable icons", "icons for details" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] }, "example": { "enabled": true } } } } } }, "/preorders/offers/{id}/limits/set_max_per_order": { "post": { "operationId": "post_preorders_offers_id_limits_set_max_per_order", "summary": "Create limits set max per order", "description": "Set the maximum quantity a customer can preorder per order.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set maximum per order", "set max quantity", "maximum order quantity", "set order limit" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "max": {} } }, "example": { "max": 5 } } } } } }, "/preorders/offers/{id}/limits/set_min_per_order": { "post": { "operationId": "post_preorders_offers_id_limits_set_min_per_order", "summary": "Create limits set min per order", "description": "Set the minimum quantity a customer must preorder per order.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set minimum per order", "set min quantity", "minimum order quantity", "set order minimum" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "min": {} } }, "example": { "min": "string" } } } } } }, "/preorders/offers/{id}/limits/set_progress_bar": { "post": { "operationId": "post_preorders_offers_id_limits_set_progress_bar", "summary": "Create limits set progress bar", "description": "Show or hide the preorder limit as a progress bar / counter on the widget, with optional text and colors.\n\n**Note:** Enabling switches the limit display to the bar (disclaimer display off, like the editor radio). Colors are hex strings; `show_percentage` adds the percent label.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "progress bar", "show counter", "stock counter", "show limit as counter", "crowdfunding bar", "hide progress bar", "units left bar" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "text": {}, "show_percentage": {}, "fill_color": {}, "background_color": {}, "box_background_color": {}, "text_color": {} }, "required": [ "enabled" ] }, "example": { "enabled": true, "text": "Preorder now", "show_percentage": 25, "fill_color": "#1A1A1A", "background_color": "#1A1A1A", "box_background_color": "#1A1A1A", "text_color": "#1A1A1A" } } } } } }, "/preorders/offers/{id}/limits/set_quantity_limit_text": { "post": { "operationId": "post_preorders_offers_id_limits_set_quantity_limit_text", "summary": "Create limits set quantity limit text", "description": "Set the text shown with the preorder quantity limit on the widget.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "quantity limit text", "limit text", "units left text", "change limit message" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": {} }, "required": [ "text" ] }, "example": { "text": "Preorder now" } } } } } }, "/preorders/offers/{id}/markets": { "get": { "operationId": "get_preorders_offers_id_markets", "summary": "Get markets", "description": "Read market scoping for a preorder offer.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "get markets", "show market scoping", "view markets", "what markets", "which countries", "market settings" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch_preorders_offers_id_markets", "summary": "Update markets", "description": "Update market scoping on a preorder offer.\n\n**Note:** Deep partial. Scoping is toggled via this PATCH: `enabled` (true/false). The offer applies to ALL markets when scoping is off (`{ \"enabled\": false }`) or when scoping is on with an empty market list — the serializer compiles applies_to_all_markets from exactly that state. PATCH bodies: all markets → `{ \"enabled\": true, \"market_ids\": [] }` (or `{ \"enabled\": true, \"applies_to_all_markets\": true }`, which also clears the list); specific markets → `{ \"enabled\": true, \"market_ids\": [\"gid://shopify/Market/1\", ...] }` (GIDs or numeric IDs). For incremental edits keep using add_market / remove_market / set_markets.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "edit markets", "change market scoping", "modify markets", "enable market scoping", "turn on market scoping", "scope to markets", "enable markets", "disable market scoping", "turn off market scoping", "remove market restrictions", "global preorder", "enable all markets", "apply to all markets", "all countries", "available everywhere" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": {}, "applies_to_all_markets": {}, "market_ids": {} } }, "example": { "enabled": true, "applies_to_all_markets": "gid://shopify/Market/12345", "market_ids": [ "gid://shopify/Market/12345" ] } } } } } }, "/preorders/offers/{id}/markets/add_market": { "post": { "operationId": "post_preorders_offers_id_markets_add_market", "summary": "Create markets add market", "description": "Add a market to the preorder offer's scope.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "add market", "include market", "add country", "extend to market" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "market_id": {} }, "required": [ "market_id" ] }, "example": { "market_id": "gid://shopify/Market/12345" } } } } } }, "/preorders/offers/{id}/markets/remove_market": { "post": { "operationId": "post_preorders_offers_id_markets_remove_market", "summary": "Create markets remove market", "description": "Remove a market from the preorder offer's scope.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "remove market", "exclude market", "drop market", "remove country" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "market_id": {} }, "required": [ "market_id" ] }, "example": { "market_id": "gid://shopify/Market/12345" } } } } } }, "/preorders/offers/{id}/markets/set_markets": { "post": { "operationId": "post_preorders_offers_id_markets_set_markets", "summary": "Create markets set markets", "description": "Replace the set of markets a preorder offer applies to.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set markets", "change markets", "restrict to markets", "set countries", "set regions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "market_ids": {} } }, "example": { "market_ids": [ "gid://shopify/Market/12345" ] } } } } } }, "/preorders/offers/{id}/payments": { "get": { "operationId": "get_preorders_offers_id_payments", "summary": "Get payments", "description": "Read the payment configuration for a preorder offer.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "get payment settings", "show payments", "view billing", "view deposit", "view discount", "payment options" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch_preorders_offers_id_payments", "summary": "Update payments", "description": "Update payment settings on a preorder offer.\n\n**Note:** Use SetOptionCopy / EnableOption / DisableOption to edit individual payment options. Boolean toggles are set via this PATCH: remaining_balance.auto_collect, remaining_balance.auto_collect_on_fulfillment — mutually exclusive, e.g. { remaining_balance: { auto_collect: false } }. Clear the discount via { discount: { type: \"no_discount\" } } (the stored value is nulled automatically).", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "edit payments", "change payment settings", "modify billing", "change discount", "update remaining balance settings", "clear discount", "remove discount", "no discount", "stop discount", "remove preorder discount", "enable auto collect", "enable auto charge", "auto-charge balance", "automatically charge balance", "turn on auto collect", "disable auto collect", "disable auto charge", "stop auto charge", "turn off auto collect", "manual balance collection", "enable auto collect on fulfillment", "charge on fulfillment", "auto charge at ship time", "collect balance on ship", "disable auto collect on fulfillment", "don't charge on fulfillment", "turn off charge at ship time", "stop collecting on ship", "show partial payment option first", "preselect deposit option", "default to full payment" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "discount": {}, "remaining_balance": {}, "show_partial_first": {} } }, "example": { "discount": 5, "remaining_balance": "string", "show_partial_first": "string" } } } } } }, "/preorders/offers/{id}/payments/disable_option": { "post": { "operationId": "post_preorders_offers_id_payments_disable_option", "summary": "Create payments disable option", "description": "Remove a payment option (full or partial) from the offer.\n\n**Note:** Only valid on full_and_partial offers — an offer must keep at least one payment option. Use set_mode to switch a single-mode offer.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "disable payment option", "remove full payment option", "remove partial payment option", "stop offering deposit", "stop offering full payment" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "option_type": { "enum": [ "full", "partial" ] } }, "required": [ "option_type" ] }, "example": { "option_type": "full" } } } } } }, "/preorders/offers/{id}/payments/enable_option": { "post": { "operationId": "post_preorders_offers_id_payments_enable_option", "summary": "Create payments enable option", "description": "Add a payment option (full or partial) to the offer.\n\n**Note:** Idempotent. Newly added options start from the dashboard defaults — use set_deposit_percent / set_option_copy to fine-tune. Disable with disable_option.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "enable payment option", "add full payment option", "add partial payment option", "offer both payment options", "let customers choose how to pay" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "option_type": { "enum": [ "full", "partial" ] } }, "required": [ "option_type" ] }, "example": { "option_type": "full" } } } } } }, "/preorders/offers/{id}/payments/set_balance_due_days": { "post": { "operationId": "post_preorders_offers_id_payments_set_balance_due_days", "summary": "Create payments set balance due days", "description": "Charge the remaining preorder balance a number of days after checkout.\n\n**Note:** Switches the offer to the 'time after checkout' remaining-balance mode and charges the balance `days` days after checkout. days must be a whole number >= 1. Use set_payment_date instead to charge on a specific calendar date, or the payments PATCH to toggle auto-collect.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set balance due days", "charge balance after n days", "collect balance days after checkout", "balance due in days", "charge remaining balance later", "set days after checkout", "collect balance a week after checkout" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "days": { "type": "integer", "minimum": 1 } }, "required": [ "days" ] }, "example": { "days": 1 } } } } } }, "/preorders/offers/{id}/payments/set_billing_widget": { "post": { "operationId": "post_preorders_offers_id_payments_set_billing_widget", "summary": "Create payments set billing widget", "description": "Show or hide the payment & discount savings widget in the purchase flow.\n\n**Note:** Toggles the storefront widget that shows the customer their payment schedule and discount savings at every step of the purchase flow. enabled must be true or false.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "show payment widget", "hide payment widget", "show payment and savings", "hide payment and savings", "enable billing widget", "disable billing widget", "show savings breakdown", "hide savings breakdown", "show payment schedule to customers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] }, "example": { "enabled": true } } } } } }, "/preorders/offers/{id}/payments/set_deposit_amount": { "post": { "operationId": "post_preorders_offers_id_payments_set_deposit_amount", "summary": "Create payments set deposit amount", "description": "Set a fixed deposit amount charged at checkout on the partial payment option.\n\n**Note:** Requires a partial payment option (mode partial or full_and_partial) -- use set_mode first. amount is in the store currency and must be more than 0. For a percent deposit use set_deposit_percent.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set deposit amount", "set a fixed deposit", "charge a fixed amount upfront", "set upfront payment amount", "change down payment amount" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "amount" ] }, "example": { "amount": 1 } } } } } }, "/preorders/offers/{id}/payments/set_deposit_percent": { "post": { "operationId": "post_preorders_offers_id_payments_set_deposit_percent", "summary": "Create payments set deposit percent", "description": "Set the deposit percentage charged at checkout on the partial payment option.\n\n**Note:** Requires a partial payment option (mode partial or full_and_partial) — use set_mode first. Percent must be between 1 and 99; 100% upfront is the full payment mode.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set deposit percent", "set deposit percentage", "change deposit amount", "set upfront payment percent", "change down payment" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "percent": { "type": "integer", "minimum": 1, "maximum": 99 } }, "required": [ "percent" ] }, "example": { "percent": 25 } } } } } }, "/preorders/offers/{id}/payments/set_discount": { "post": { "operationId": "post_preorders_offers_id_payments_set_discount", "summary": "Create payments set discount", "description": "Set the preorder discount. type is one of: percentage, price, fixed_amount, no_discount; value is the amount (omit for no_discount).", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set discount", "apply discount", "change discount", "set percentage off", "set amount off" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "enum": [ "percentage", "price", "fixed_amount", "no_discount" ] }, "value": {} }, "required": [ "type" ] }, "example": { "type": "percentage", "value": "string" } } } } } }, "/preorders/offers/{id}/payments/set_discount_text": { "post": { "operationId": "post_preorders_offers_id_payments_set_discount_text", "summary": "Create payments set discount text", "description": "Set the discount blurb shown on the offer's payment options. option_type (optional) must be either full or partial.\n\n**Note:** Pass option_type (full | partial) to target one payment option; omit it to apply the text to every option. Supports the {{ discount }} placeholder.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set discount text", "change discount blurb", "set discount message", "change discount copy", "set savings text" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": {}, "option_type": { "enum": [ "full", "partial" ] } }, "required": [ "text" ] }, "example": { "text": "Preorder now", "option_type": "full" } } } } } }, "/preorders/offers/{id}/payments/set_mode": { "post": { "operationId": "post_preorders_offers_id_payments_set_mode", "summary": "Create payments set mode", "description": "Switch the offer's payment mode. mode must be exactly one of: full, partial, full_and_partial.\n\n**Note:** Idempotent. Collapsing from full_and_partial keeps the surviving option's copy; newly enabled modes start from the dashboard defaults. Use set_deposit_percent and set_option_copy afterwards to fine-tune. partial and full_and_partial need the Shopify purchase option and are refused while it is off.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set payment mode", "full payment only", "partial payment only", "deposit only", "offer both full and partial payment", "change payment options" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "enum": [ "full", "partial", "full_and_partial" ] } }, "required": [ "mode" ] }, "example": { "mode": "full" } } } } } }, "/preorders/offers/{id}/payments/set_option_copy": { "post": { "operationId": "post_preorders_offers_id_payments_set_option_copy", "summary": "Create payments set option copy", "description": "Set the merchant-facing copy on a payment option (title, description, discount text). option_type must be either full or partial.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set option copy", "set partial option copy", "set full option copy", "change billing title", "set payment option text", "set deposit option text" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "option_type": { "enum": [ "full", "partial" ] }, "billing_title": {}, "billing_description": {}, "discount_text": {} }, "required": [ "option_type" ] }, "example": { "option_type": "full", "billing_title": "string", "billing_description": "string", "discount_text": "Preorder now" } } } } } }, "/preorders/offers/{id}/payments/set_payment_date": { "post": { "operationId": "post_preorders_offers_id_payments_set_payment_date", "summary": "Create payments set payment date", "description": "Set the exact date the remaining preorder balance is charged.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set payment date", "balance due date", "charge on a specific date", "final payment date", "collect balance on date" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": {} }, "required": [ "date" ] }, "example": { "date": "2026-07-01T00:00:00Z" } } } } } }, "/preorders/offers/{id}/payments/set_show_discounted_price": { "post": { "operationId": "post_preorders_offers_id_payments_set_show_discounted_price", "summary": "Create payments set show discounted price", "description": "Show or hide the discounted preorder price on the widget.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "show discounted price", "hide discounted price", "display sale price", "show discount price" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] }, "example": { "enabled": true } } } } } }, "/preorders/offers/{id}/products": { "get": { "operationId": "get_preorders_offers_id_products", "summary": "Get products", "description": "Read the products configuration for a preorder offer (source rule + variant summary).", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "get products", "show linked products", "view variants on offer", "view product source", "what's on this offer" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch_preorders_offers_id_products", "summary": "Update products", "description": "Update the product selection on a preorder offer — set the source rule plus its matching sub-block. source must be exactly one of: all, collection, custom, tags.\n\n**Note:** Delegates to the set_source_to_* actions; switching source resets the variant set. source 'all' requires confirm: true. Only the sub-block matching `source` may be provided.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "edit products", "change product selection", "change variant source", "set products", "modify products on offer" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "enum": [ "all", "collection", "custom", "tags" ] }, "custom": { "type": [ "null", "object" ] }, "collection": { "type": [ "null", "object" ] }, "all": { "type": [ "null", "object" ] }, "tags": { "type": [ "null", "object" ] }, "confirm": {} }, "required": [ "source" ] }, "example": { "source": "all", "custom": "string", "collection": "string", "all": "string", "tags": "string", "confirm": "string" } } } } } }, "/preorders/offers/{id}/products/add_variants": { "post": { "operationId": "post_preorders_offers_id_products_add_variants", "summary": "Create products add variants", "description": "Attach variants to a custom-source preorder offer.\n\n**Note:** Custom source only. Idempotent: already-attached variants are skipped and reported under already_present. Runs through BulkVariantAdditionService (async).", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — example response shown.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "source": "custom", "variants": { "count": 6, "url": "/api/v2/external/preorders/offers/1/products/variants" }, "custom": { "variant_ids_sample": [ 47284734423096, 47284734455864, 47284734488632, 47284734521400, 47284734554168, 47284734586936 ] } } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "add variants", "attach variants", "add products to offer", "link variants", "include variants" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variant_ids": {} } }, "example": { "variant_ids": [ 47284734423096, 47284734455864, 47284734488632 ] } } } } } }, "/preorders/offers/{id}/products/bulk_toggle_inventory_policy": { "post": { "operationId": "post_preorders_offers_id_products_bulk_toggle_inventory_policy", "summary": "Create products bulk toggle inventory policy", "description": "Flip the Shopify inventory policy on variants attached to a preorder offer (CONTINUE or DENY). Pass the explicit variant_ids for a partial change; omitting variant_ids applies the policy to EVERY attached variant, so only omit it when the merchant asked for all of them.\n\n**Note:** Async via SellingPlans::BulkInventoryPolicyUpdateJob. Omit variant_ids to apply to all attached variants. variant_ids must be attached to this offer: unattached ones are skipped and returned in `skipped_variant_ids`, and the call fails with 422 if none of them are attached.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "flip inventory policy", "toggle continue selling on variants", "set inventory policy for variants", "enable oversell on these variants", "disable oversell on these variants" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "enum": [ "CONTINUE", "DENY" ] }, "variant_ids": {} }, "required": [ "policy" ] }, "example": { "policy": "CONTINUE", "variant_ids": [ "45000000001" ] } } } } } }, "/preorders/offers/{id}/products/remove_variants": { "post": { "operationId": "post_preorders_offers_id_products_remove_variants", "summary": "Create products remove variants", "description": "Remove variants from a custom-source preorder offer.\n\n**Note:** Custom source only. Resets per-variant metafields on Shopify.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "remove variants", "detach variants", "remove products from offer", "unlink variants", "exclude variants" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variant_ids": {} } }, "example": { "variant_ids": [ "45000000001" ] } } } } } }, "/preorders/offers/{id}/products/set_collection": { "post": { "operationId": "post_preorders_offers_id_products_set_collection", "summary": "Create products set collection", "description": "Change the collection driving a collection-sourced preorder offer.\n\n**Note:** Collection-sourced offers only — returns 409 Conflict otherwise. Use set_source_to_collection to switch a non-collection offer to collection source.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "change collection", "swap collection", "use a different collection", "update the collection on the offer" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "collection_id": {} }, "required": [ "collection_id" ] }, "example": { "collection_id": "string" } } } } } }, "/preorders/offers/{id}/products/set_excluded_variants": { "post": { "operationId": "post_preorders_offers_id_products_set_excluded_variants", "summary": "Create products set excluded variants", "description": "Replace the explicit excluded-variant list for an all-source preorder offer.\n\n**Note:** All-source offers only.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set excluded variants", "exclude variants list", "block variants from offer" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variant_ids": {} } }, "example": { "variant_ids": [ "45000000001" ] } } } } } }, "/preorders/offers/{id}/products/set_exclusion_tag": { "post": { "operationId": "post_preorders_offers_id_products_set_exclusion_tag", "summary": "Create products set exclusion tag", "description": "Set the exclusion tag for an all-source preorder offer (variants with this tag are excluded).\n\n**Note:** All-source offers only.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set exclusion tag", "exclude by tag", "set exclude tag" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tag": {} } }, "example": { "tag": "string" } } } } } }, "/preorders/offers/{id}/products/set_source_to_all": { "post": { "operationId": "post_preorders_offers_id_products_set_source_to_all", "summary": "Create products set source to all", "description": "Switch the offer to apply to every variant in the shop, minus exclusions. Requires confirm: true.\n\n**Note:** Requires `confirm: true` in the body. Resolution runs async over the entire catalog.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set source to all", "apply to all products", "auto-source", "every variant", "shop-wide preorder" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirm": {}, "exclusion_tag": {}, "excluded_variant_ids": {} } }, "example": { "confirm": "string", "exclusion_tag": "string", "excluded_variant_ids": [ "string" ] } } } } } }, "/preorders/offers/{id}/products/set_source_to_collection": { "post": { "operationId": "post_preorders_offers_id_products_set_source_to_collection", "summary": "Create products set source to collection", "description": "Switch the offer to a collection-driven variant source.\n\n**Note:** Resolution runs asynchronously. New variants added to the collection in Shopify are NOT auto-picked-up — call this action again to refresh.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set source to collection", "use a collection", "link to collection", "set products from collection", "drive variants from collection" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "collection_id": {} }, "required": [ "collection_id" ] }, "example": { "collection_id": "string" } } } } } }, "/preorders/offers/{id}/products/set_source_to_custom": { "post": { "operationId": "post_preorders_offers_id_products_set_source_to_custom", "summary": "Create products set source to custom", "description": "Switch the offer to a custom variant list. Optionally seed it with variant IDs.\n\n**Note:** Variant attachment runs through BulkVariantAdditionService and is async (202 + job_id).", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set source to custom", "use custom variants", "custom product list", "switch to custom" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variant_ids": {} } }, "example": { "variant_ids": [ "45000000001" ] } } } } } }, "/preorders/offers/{id}/products/set_source_to_tags": { "post": { "operationId": "post_preorders_offers_id_products_set_source_to_tags", "summary": "Create products set source to tags", "description": "Switch the offer to a tag-driven variant source.\n\n**Note:** A product matches when it carries one of the tags as a whole tag (case-insensitive; 'sale' does not match 'summer-sale'). Tags are OR'd together. Resolution runs asynchronously and then refreshes on the 15-minute sync, so tagging or untagging a product in Shopify is picked up automatically.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set source to tags", "use product tags", "link to tags", "set products from tags", "drive variants from tags" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": {} }, "required": [ "tags" ] }, "example": { "tags": "string" } } } } } }, "/preorders/offers/{id}/products/variants": { "get": { "operationId": "get_preorders_offers_id_products_variants", "summary": "Get products variants", "description": "List the variants attached to a preorder offer with their per-variant settings, paginated.\n\n**Note:** sort=title orders by product then variant title (default: attach order). exclude_discarded=true leaves out variants deleted from the catalog. include_inventory=true adds each row's live Shopify inventory, continue-selling policy, product tags and whether the preorder button shows under this offer now. The filters inventory (zero_or_below | positive), inventory_policy (deny | continue), product_tag and exclude_product_tag imply include_inventory and apply to each page after the read, so a page can hold fewer rows than per_page; keep paging while meta.page < meta.total_pages.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "list variants on offer", "variants attached to offer", "show offer variants", "attached variants", "offer variant list" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "attached", "title" ] }, "example": "attached" }, { "name": "inventory", "in": "query", "required": false, "schema": { "enum": [ "zero_or_below", "positive" ] }, "example": "zero_or_below" }, { "name": "inventory_policy", "in": "query", "required": false, "schema": { "enum": [ "deny", "continue" ] }, "example": "deny" }, { "name": "page", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "per_page", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "exclude_discarded", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "include_inventory", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "product_tag", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "exclude_product_tag", "in": "query", "required": false, "schema": {}, "example": "string" } ] } }, "/preorders/offers/{id}/products/variants/{variant_id}": { "get": { "operationId": "get_preorders_offers_id_products_variants_variant_id", "summary": "Get products variants", "description": "Read the per-offer settings of a single variant attached to a preorder offer.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "show variant settings on offer", "view per-variant overrides", "get variant on offer", "variant settings" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "variant_id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch_preorders_offers_id_products_variants_variant_id", "summary": "Update products variants", "description": "Set per-offer overrides on an attached variant — shipping text and max preorder count.\n\n**Note:** null clears an override; the variant falls back to the offer-level value. market_overrides is no longer accepted; set per-market values on the offer instead.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "override variant settings", "set shipping text for variant", "set max count for variant", "per-variant overrides" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "variant_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shipping_text": { "type": [ "null", "string" ] }, "max_count": { "type": [ "null", "integer" ] } } }, "example": { "shipping_text": "Preorder now", "max_count": 5 } } } } } }, "/preorders/offers/{id}/products/variants/{variant_id}/toggle_inventory_policy": { "post": { "operationId": "post_preorders_offers_id_products_variants_variant_id_toggle_inventory_policy", "summary": "Create products variants toggle inventory policy", "description": "Set whether Shopify continues selling one attached preorder variant when it is out of stock (CONTINUE or DENY).\n\n**Note:** Delegates asynchronously to BulkToggleInventoryPolicy with this single variant ID.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "toggle continue selling on variant", "enable oversell on variant", "disable oversell on variant", "set variant inventory policy" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "variant_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "enum": [ "CONTINUE", "DENY" ] } }, "required": [ "policy" ] }, "example": { "policy": "CONTINUE" } } } } } }, "/preorders/offers/{id}/rename": { "post": { "operationId": "post_preorders_offers_id_rename", "summary": "Create rename", "description": "Rename a preorder offer (customer-facing name and/or internal label).", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "rename offer", "change offer name", "rename preorder", "change internal name", "relabel offer" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": {}, "internal_name": {} } }, "example": { "name": "Summer Sneaker Drop", "internal_name": "summer-2026" } } } } } }, "/preorders/offers/{id}/restore": { "post": { "operationId": "post_preorders_offers_id_restore", "summary": "Restore", "description": "Restore a discarded preorder offer.\n\n**Note:** Variant attachments and metafields are not auto-restored. Re-attach via the products capability.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "undelete", "undiscard", "undo delete", "bring back" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/preorders/offers/{id}/schedule": { "post": { "operationId": "post_preorders_offers_id_schedule", "summary": "Schedule", "description": "Set the schedule window for a preorder offer.\n\n**Note:** Does not auto-enable. Storefront reads the schedule live.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set schedule", "schedule launch", "set start date", "set end date", "schedule offer" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "start": {}, "end": {} } }, "example": { "start": "2026-07-01T00:00:00Z", "end": "2026-07-01T00:00:00Z" } } } } } }, "/preorders/offers/{id}/shipping": { "get": { "operationId": "get_preorders_offers_id_shipping", "summary": "Get shipping", "description": "Read shipping settings for a preorder offer.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "get shipping", "show shipping", "view delivery", "view fulfillment", "view shipping text", "shipping settings" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch_preorders_offers_id_shipping", "summary": "Update shipping", "description": "Update shipping settings on a preorder offer.\n\n**Note:** Deep partial. Prefer the intent-bearing actions (set_delivery_*, set_shipping_text, set_split_order_tag, set_split_order_suffix, set_split_transaction_gateway) for narrow edits. Toggles are done via this PATCH: `fulfillment.hold` (true/false) holds/releases fulfillment orders containing preorder items -- mutually exclusive with fulfillment.split, cannot both be on; `fulfillment.split.type` ('fulfillments' or 'orders') picks which split behavior is on -- these are two distinct settings, not one, and mutually exclusive with fulfillment.hold; 'fulfillments' also requires delivery.type to be (or become, in the same request) 'asap'; `fulfillment.split.enabled` (true/false) is a legacy toggle: true requires type to also be set, false clears both; `fulfillment.split.hold_fulfillments` (true/false) holds the split order's fulfillments; `fulfillment.split.sequential_number` (true/false) gives split orders a sequential order name; `fulfillment.split.per_variant` (true/false) creates one split order per variant instead of one per offer.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "edit shipping", "change shipping settings", "change delivery", "change fulfillment", "modify shipping", "enable fulfillment hold", "hold fulfillments", "hold preorder fulfillments", "turn on fulfillment hold", "prevent shipping until released", "disable fulfillment hold", "release fulfillments", "stop holding fulfillments", "turn off fulfillment hold", "let preorder ship immediately", "enable split", "enable split orders", "enable split fulfillments", "turn on order splitting", "separate preorder from regular", "disable split", "disable split orders", "disable split fulfillments", "turn off order splitting", "stop separating preorders", "enable split hold fulfillments", "hold split order fulfillments", "hold fulfillments on split order", "don't ship split order immediately", "disable split hold fulfillments", "release split order fulfillments", "ship split order immediately", "stop holding split order", "enable split sequential number", "sequential split order numbers", "number split orders sequentially", "sequential order name for split", "disable split sequential number", "no sequential split order numbers", "stop numbering split orders sequentially" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "delivery": {}, "display": {}, "fulfillment": {} } }, "example": { "delivery": "string", "display": "string", "fulfillment": "string" } } } } } }, "/preorders/offers/{id}/shipping/set_auto_release_holds": { "post": { "operationId": "post_preorders_offers_id_shipping_set_auto_release_holds", "summary": "Create shipping set auto release holds", "description": "Enable or disable automatic release of fulfillment holds, with an optional release date and pay-first requirement.\n\n**Note:** `date` sets when holds release; `require_payment: true` waits for the balance to be collected first. Disabling clears the stored release date.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "auto release holds", "automatically release holds", "release holds on a date", "stop releasing holds automatically", "release holds after payment" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "date": {}, "require_payment": {} }, "required": [ "enabled" ] }, "example": { "enabled": true, "date": "2026-07-01T00:00:00Z", "require_payment": "string" } } } } } }, "/preorders/offers/{id}/shipping/set_delivery_asap": { "post": { "operationId": "post_preorders_offers_id_shipping_set_delivery_asap", "summary": "Create shipping set delivery asap", "description": "Set delivery to 'as soon as possible' (no specific date or window).", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set delivery asap", "ship asap", "set delivery to asap", "ship as soon as possible" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/preorders/offers/{id}/shipping/set_delivery_date": { "post": { "operationId": "post_preorders_offers_id_shipping_set_delivery_date", "summary": "Create shipping set delivery date", "description": "Set an exact delivery date for the preorder.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set delivery date", "ship on date", "set ship date", "set exact delivery date" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": {} }, "required": [ "date" ] }, "example": { "date": "2026-07-01T00:00:00Z" } } } } } }, "/preorders/offers/{id}/shipping/set_delivery_window": { "post": { "operationId": "post_preorders_offers_id_shipping_set_delivery_window", "summary": "Create shipping set delivery window", "description": "Set a delivery window in days from checkout (e.g. 'ships within 14 days').", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set delivery window", "ship within days", "set delivery in days", "set ship window" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "days": {} } }, "example": { "days": "string" } } } } } }, "/preorders/offers/{id}/shipping/set_hold_fulfillments": { "post": { "operationId": "post_preorders_offers_id_shipping_set_hold_fulfillments", "summary": "Create shipping set hold fulfillments", "description": "Hold (or release) all fulfillments for preorders on this offer, with an optional reason note.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "hold fulfillments", "hold all fulfillments", "stop holding fulfillments", "release fulfillment hold", "hold orders", "fulfillment hold reason" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "reason_note": {} }, "required": [ "enabled" ] }, "example": { "enabled": true, "reason_note": "string" } } } } } }, "/preorders/offers/{id}/shipping/set_shipping_text": { "post": { "operationId": "post_preorders_offers_id_shipping_set_shipping_text", "summary": "Create shipping set shipping text", "description": "Set the customer-facing shipping text shown on the PDP.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set shipping text", "change shipping text", "update shipping message", "set delivery text", "change PDP shipping line" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": {} }, "required": [ "text" ] }, "example": { "text": "Preorder now" } } } } } }, "/preorders/offers/{id}/shipping/set_split_order_suffix": { "post": { "operationId": "post_preorders_offers_id_shipping_set_split_order_suffix", "summary": "Create shipping set split order suffix", "description": "Set the suffix appended to the original order name for split orders (e.g. #1001-SPLIT).", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set split order suffix", "change split suffix", "set split order name suffix", "rename split order suffix", "change split order label text" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "suffix": {} }, "required": [ "suffix" ] }, "example": { "suffix": "string" } } } } } }, "/preorders/offers/{id}/shipping/set_split_order_tag": { "post": { "operationId": "post_preorders_offers_id_shipping_set_split_order_tag", "summary": "Create shipping set split order tag", "description": "Set the tag applied to split orders on Shopify.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set split order tag", "change split tag", "set split order label" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tag": {} }, "required": [ "tag" ] }, "example": { "tag": "string" } } } } } }, "/preorders/offers/{id}/shipping/set_split_transaction_gateway": { "post": { "operationId": "post_preorders_offers_id_shipping_set_split_transaction_gateway", "summary": "Create shipping set split transaction gateway", "description": "Set the payment gateway used for the split order transaction (e.g. 'Prepaid').", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set split transaction gateway", "set split payment gateway", "change split order gateway" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "gateway": {} }, "required": [ "gateway" ] }, "example": { "gateway": "string" } } } } } }, "/preorders/offers/{id}/translations": { "get": { "operationId": "get_preorders_offers_id_translations", "summary": "Get translations", "description": "Read every translation override on a preorder offer, plus the full enumeration of translatable field paths, each field's default-locale source text, and every locale the shop has actually published (not just ones with an override already).", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "get translations", "show translations", "view translations", "list translations", "view localized text", "i18n", "localization" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/preorders/offers/{id}/translations/clear_locale": { "post": { "operationId": "post_preorders_offers_id_translations_clear_locale", "summary": "Create translations clear locale", "description": "Remove all translation overrides for one locale on a preorder offer.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "clear locale", "remove locale", "wipe locale", "drop translations for locale", "remove all translations for a language" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "locale": {} }, "required": [ "locale" ] }, "example": { "locale": "fr" } } } } } }, "/preorders/offers/{id}/translations/set": { "post": { "operationId": "post_preorders_offers_id_translations_set", "summary": "Create translations set", "description": "Set a single translation override (one locale, one field) on a preorder offer.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set translation", "add translation", "translate field", "localize a field", "set localized text" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "locale": {}, "field": {}, "value": {} }, "required": [ "locale", "field" ] }, "example": { "locale": "fr", "field": "string", "value": "string" } } } } } }, "/preorders/offers/{id}/translations/set_many": { "post": { "operationId": "post_preorders_offers_id_translations_set_many", "summary": "Create translations set many", "description": "Set many translation overrides for one locale on a preorder offer, atomically.\n\n**Note:** All-or-nothing. Pre-validates every field path before writing.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set many translations", "translate offer", "bulk translate", "localize offer", "translate to french", "add translations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "locale": {}, "translations": {} }, "required": [ "locale", "translations" ] }, "example": { "locale": "fr", "translations": "string" } } } } } }, "/preorders/offers/{id}/translations/unset": { "post": { "operationId": "post_preorders_offers_id_translations_unset", "summary": "Create translations unset", "description": "Remove a translation override (one locale, one field) from a preorder offer.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "unset translation", "remove translation", "clear translation", "delete localized text", "remove localized override" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "locale": {}, "field": {} }, "required": [ "locale", "field" ] }, "example": { "locale": "fr", "field": "string" } } } } } }, "/preorders/offers/{id}/unschedule": { "post": { "operationId": "post_preorders_offers_id_unschedule", "summary": "Create unschedule", "description": "Clear the schedule window on a preorder offer.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "clear schedule", "remove schedule", "no schedule", "unschedule offer" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/preorders/offers/{id}/widget": { "get": { "operationId": "get_preorders_offers_id_widget", "summary": "Get widget", "description": "Read the widget configuration for a preorder offer.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "get widget", "show widget", "view button settings", "view badge settings", "view disclaimer settings", "preorder ui" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch_preorders_offers_id_widget", "summary": "Update widget", "description": "Update any subset of the widget configuration on a preorder offer.\n\n**Note:** Deep partial. Use the intent-bearing widget actions for narrow edits. Boolean toggles are set via this PATCH: badge.enabled, disclaimer.enabled, button.colors.enabled, billing_widget.enabled — e.g. { badge: { enabled: false } }. Clearing a value: send null.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "edit widget", "change widget settings", "modify widget", "update preorder ui", "enable badge", "show badge", "turn on badge", "make badge visible", "disable badge", "hide badge", "turn off badge", "remove badge", "enable disclaimer", "show disclaimer", "turn on disclaimer", "show fine print", "show shipping notice", "disable disclaimer", "hide disclaimer", "turn off disclaimer", "hide fine print", "remove shipping notice", "enable custom button colors", "use custom button colors", "turn on button colors", "apply custom colors", "disable custom button colors", "use theme button colors", "turn off button colors", "revert to theme colors", "enable billing widget", "show payment breakdown", "show payment widget", "turn on billing widget", "disable billing widget", "hide payment breakdown", "hide payment widget", "turn off billing widget" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "button": {}, "disclaimer": {}, "badge": {}, "billing_widget": {} } }, "example": { "button": "string", "disclaimer": "string", "badge": "string", "billing_widget": "string" } } } } } }, "/preorders/offers/{id}/widget/set_badge_colors": { "post": { "operationId": "post_preorders_offers_id_widget_set_badge_colors", "summary": "Create widget set badge colors", "description": "Set the preorder badge's text and background colors.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "change badge colors", "set badge color", "customize badge colors", "change badge background" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text_color": {}, "background_color": {} } }, "example": { "text_color": "#1A1A1A", "background_color": "#1A1A1A" } } } } } }, "/preorders/offers/{id}/widget/set_badge_enabled": { "post": { "operationId": "post_preorders_offers_id_widget_set_badge_enabled", "summary": "Create widget set badge enabled", "description": "Show or hide the preorder badge on the widget.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "show badge", "hide badge", "enable badge", "disable badge", "turn on badge", "turn off badge", "remove badge" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] }, "example": { "enabled": true } } } } } }, "/preorders/offers/{id}/widget/set_badge_text": { "post": { "operationId": "post_preorders_offers_id_widget_set_badge_text", "summary": "Create widget set badge text", "description": "Set the preorder badge text.\n\n**Note:** Use set_badge_enabled to control visibility.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "change badge text", "set badge label", "rename badge", "change preorder badge text", "update badge text" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": {} }, "required": [ "text" ] }, "example": { "text": "Preorder now" } } } } } }, "/preorders/offers/{id}/widget/set_billing_widget_text": { "post": { "operationId": "post_preorders_offers_id_widget_set_billing_widget_text", "summary": "Create widget set billing widget text", "description": "Set the billing widget's title and description (the PDP payment-breakdown block).\n\n**Note:** These fields are shared with the first payment option's copy (see payments/set_option_copy). Use enable_billing_widget / disable_billing_widget to control visibility.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set billing widget title", "set billing widget description", "change payment breakdown text", "edit billing widget copy" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": {}, "description": {} } }, "example": { "title": "string", "description": "string" } } } } } }, "/preorders/offers/{id}/widget/set_button_colors": { "post": { "operationId": "post_preorders_offers_id_widget_set_button_colors", "summary": "Create widget set button colors", "description": "Set the preorder button's text and background colors (implicitly enables custom colors).\n\n**Note:** Setting either color implicitly enables custom colors. Use disable_button_colors to revert to the theme's defaults.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "change button colors", "set button color", "customize button colors" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text_color": {}, "background_color": {} } }, "example": { "text_color": "#1A1A1A", "background_color": "#1A1A1A" } } } } } }, "/preorders/offers/{id}/widget/set_button_text": { "post": { "operationId": "post_preorders_offers_id_widget_set_button_text", "summary": "Create widget set button text", "description": "Set the preorder button's call-to-action label.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — example response shown.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "button": { "text": "Reserve Now", "colors": { "enabled": true, "text_color": "#FFFFFF", "background_color": "#1a1a1a" } }, "disclaimer": { "enabled": true, "text": "Expected to ship by August 2026" }, "badge": { "enabled": true, "text": "Pre-Order" } } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "change button text", "rename button", "set button label", "change preorder button label", "update button text" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": {} }, "required": [ "text" ] }, "example": { "text": "Reserve Now" } } } } } }, "/preorders/offers/{id}/widget/set_disclaimer_enabled": { "post": { "operationId": "post_preorders_offers_id_widget_set_disclaimer_enabled", "summary": "Create widget set disclaimer enabled", "description": "Show or hide the disclaimer line under the preorder button.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "show disclaimer", "hide disclaimer", "enable disclaimer", "disable disclaimer", "turn on disclaimer", "turn off disclaimer", "remove disclaimer" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] }, "example": { "enabled": true } } } } } }, "/preorders/offers/{id}/widget/set_disclaimer_style": { "post": { "operationId": "post_preorders_offers_id_widget_set_disclaimer_style", "summary": "Create widget set disclaimer style", "description": "Set the disclaimer banner's colors and border radius.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "change disclaimer colors", "set disclaimer style", "style the disclaimer", "set disclaimer border radius", "change disclaimer background" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text_color": {}, "background_color": {}, "border_radius": { "type": "integer", "minimum": 0 } } }, "example": { "text_color": "#1A1A1A", "background_color": "#1A1A1A", "border_radius": 0 } } } } } }, "/preorders/offers/{id}/widget/set_disclaimer_text": { "post": { "operationId": "post_preorders_offers_id_widget_set_disclaimer_text", "summary": "Create widget set disclaimer text", "description": "Set the disclaimer banner text shown under the preorder button.\n\n**Note:** Use enable_disclaimer / disable_disclaimer to control visibility.", "tags": [ "Preorders · Offers" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "change disclaimer text", "set disclaimer text", "edit disclaimer", "change disclaimer message", "set shipping disclaimer" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": {} }, "required": [ "text" ] }, "example": { "text": "Preorder now" } } } } } }, "/preorders/orders": { "get": { "operationId": "get_preorders_orders", "summary": "List orders", "description": "List preorder orders in this shop, paginated. search matches order number/name, customer name, email, a Shopify order id (10+ digits), an order gid (gid://shopify/Order/), or a Shopify admin order URL.", "tags": [ "Preorders · Orders" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "list preorder orders", "show all preorder orders", "preorder orders", "list orders" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "per_page", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "search", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "state", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "offer_id", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "variant_id", "in": "query", "required": false, "schema": {}, "example": "45000000001" }, { "name": "customer_id", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "from", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "to", "in": "query", "required": false, "schema": {}, "example": "string" } ] } }, "/preorders/orders/{id}": { "get": { "operationId": "get_preorders_orders_id", "summary": "Get orders", "description": "Read an order's full representation: status, payments with the last charge attempt, per-line fulfillment, and the linked offers' fulfillment settings.", "tags": [ "Preorders · Orders" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "show preorder order", "get order", "look up order", "view preorder order" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/preorders/orders/{id}/cancel": { "post": { "operationId": "post_preorders_orders_id_cancel", "summary": "Cancel", "description": "Cancel a preorder. Optionally refund deposit / balance and notify the customer.\n\n**Note:** Does not cancel the Shopify order; sets cancelled_at on the preorder attribution. Use the refund flags for refunds.", "tags": [ "Preorders · Orders" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "cancel order", "cancel preorder", "void preorder", "stop this preorder" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refund_deposit": {}, "refund_balance": {}, "notify_customer": {}, "reason": {} } }, "example": { "refund_deposit": "string", "refund_balance": "string", "notify_customer": "string", "reason": "string" } } } } } }, "/preorders/orders/{id}/collect_payment": { "post": { "operationId": "post_preorders_orders_id_collect_payment", "summary": "Create collect payment", "description": "Collect the order's outstanding balance now by charging the customer's saved payment method.\n\n**Note:** Matches the merchant dashboard action Collect payment. Charges the customer immediately; may fail when there is no saved payment method or the charge is declined — check the response. Set send_notifications false to suppress the customer email sent when a charge fails.", "tags": [ "Preorders · Orders" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "collect payment", "capture payment", "charge the balance now", "take the remaining payment", "collect outstanding balance" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "send_notifications": {} } }, "example": { "send_notifications": "string" } } } } } }, "/preorders/orders/{id}/fulfillment": { "get": { "operationId": "get_preorders_orders_id_fulfillment", "summary": "Get fulfillment", "description": "Read the fulfillment hold state and fulfillment-order summary of a preorder order.", "tags": [ "Preorders · Orders" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "order fulfillment", "shipping", "hold state", "fulfillment hold" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch_preorders_orders_id_fulfillment", "summary": "Update fulfillment", "description": "Update fulfillment attributes on a preorder order. Only `hold_reason_note` is writable.\n\n**Note:** Hold state changes go through release_holds / apply_holds. `all_held`, `any_held`, and `fulfillment_orders` are read-only. Delegates to SetHoldReason; existing holds on Shopify aren't re-written.", "tags": [ "Preorders · Orders" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "update fulfillment", "edit fulfillment", "change hold reason", "update hold note" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "hold_reason_note": { "type": [ "null", "string" ] } } }, "example": { "hold_reason_note": "string" } } } } } }, "/preorders/orders/{id}/fulfillment/apply_holds": { "post": { "operationId": "post_preorders_orders_id_fulfillment_apply_holds", "summary": "Create fulfillment apply holds", "description": "Apply fulfillment holds on the order's fulfillment orders. Idempotent.", "tags": [ "Preorders · Orders" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "apply holds", "add holds to fulfillments", "place fulfillments on hold" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason_note": { "type": [ "null", "string" ] } } }, "example": { "reason_note": "string" } } } } } }, "/preorders/orders/{id}/fulfillment/release_holds": { "post": { "operationId": "post_preorders_orders_id_fulfillment_release_holds", "summary": "Create fulfillment release holds", "description": "Release fulfillment holds on the order without applying offer-configured tags.\n\n**Note:** Use the top-level `release` action when you want tags applied too.", "tags": [ "Preorders · Orders" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "release holds", "release fulfillments without tags", "remove fulfillment hold only" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/preorders/orders/{id}/fulfillment/set_hold_reason": { "post": { "operationId": "post_preorders_orders_id_fulfillment_set_hold_reason", "summary": "Create fulfillment set hold reason", "description": "Set the hold-reason note that will be used the next time the order is held.\n\n**Note:** Updates the note on the first attributed preorder offer. Existing holds on Shopify aren't re-written.", "tags": [ "Preorders · Orders" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set hold reason", "change hold note", "update fulfillment hold note" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason_note": {} }, "required": [ "reason_note" ] }, "example": { "reason_note": "string" } } } } } }, "/preorders/orders/{id}/hold_fulfillments": { "post": { "operationId": "post_preorders_orders_id_hold_fulfillments", "summary": "Create hold fulfillments", "description": "Apply fulfillment holds on the preorder order's fulfillment orders.", "tags": [ "Preorders · Orders" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "hold order", "hold fulfillments", "re-hold fulfillments", "pause fulfillment", "stop the order from shipping" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/preorders/orders/{id}/open_scheduled_fulfillments": { "post": { "operationId": "post_preorders_orders_id_open_scheduled_fulfillments", "summary": "Create open scheduled fulfillments", "description": "Open the order's scheduled fulfillment orders for immediate fulfillment.\n\n**Note:** Matches the merchant dashboard action Open scheduled fulfillments.", "tags": [ "Preorders · Orders" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "open scheduled fulfillments", "open order" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/preorders/orders/{id}/payments": { "get": { "operationId": "get_preorders_orders_id_payments", "summary": "Get payments", "description": "Read the deposit, remaining balance, and refund state of a preorder order.", "tags": [ "Preorders · Orders" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "order payments", "deposit", "balance", "remaining balance", "refund" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/preorders/orders/{id}/payments/charge_balance": { "post": { "operationId": "post_preorders_orders_id_payments_charge_balance", "summary": "Create payments charge balance", "description": "Charge the remaining balance. `auto` uses the customer's saved payment method; `manual` just marks balance collected.\n\n**Note:** `auto` may fail if no saved payment method or declined; check the response or poll status.", "tags": [ "Preorders · Orders" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "charge remaining balance", "collect balance", "auto-charge balance", "take the balance now" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": {} } }, "example": { "mode": "string" } } } } } }, "/preorders/orders/{id}/payments/refund": { "post": { "operationId": "post_preorders_orders_id_payments_refund", "summary": "Create payments refund", "description": "Refund the entire preorder (deposit + balance).", "tags": [ "Preorders · Orders" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "refund order", "refund preorder", "full refund", "give the customer their money back" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "notify_customer": {}, "note": {} } }, "example": { "notify_customer": "string", "note": "string" } } } } } }, "/preorders/orders/{id}/payments/refund_balance": { "post": { "operationId": "post_preorders_orders_id_payments_refund_balance", "summary": "Create payments refund balance", "description": "Refund the remaining-balance portion of a preorder (only valid after the balance was collected).", "tags": [ "Preorders · Orders" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "refund balance", "refund remaining balance", "refund the rest" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "notify_customer": {}, "note": {} } }, "example": { "notify_customer": "string", "note": "string" } } } } } }, "/preorders/orders/{id}/payments/refund_deposit": { "post": { "operationId": "post_preorders_orders_id_payments_refund_deposit", "summary": "Create payments refund deposit", "description": "Refund the deposit portion of a preorder.", "tags": [ "Preorders · Orders" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "refund deposit", "give the deposit back", "refund up-front payment" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "notify_customer": {}, "note": {} } }, "example": { "notify_customer": "string", "note": "string" } } } } } }, "/preorders/orders/{id}/payments/send_collection_url": { "post": { "operationId": "post_preorders_orders_id_payments_send_collection_url", "summary": "Create payments send collection url", "description": "Send the remaining-balance payment-collection URL to the customer.\n\n**Note:** Idempotent — calling twice resends the email with a fresh URL.", "tags": [ "Preorders · Orders" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "send payment link", "request balance payment", "send payment collection url", "ask customer for balance", "send collection email" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/preorders/orders/{id}/release": { "post": { "operationId": "post_preorders_orders_id_release", "summary": "Release", "description": "Release the order's fulfillment holds without applying offer-configured order tags.\n\n**Note:** Matches the merchant dashboard action Release \"On hold\" fulfillments.", "tags": [ "Preorders · Orders" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "release order", "release fulfillments", "let it ship", "unhold order", "open fulfillments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/preorders/orders/{id}/reschedule_fulfillment": { "post": { "operationId": "post_preorders_orders_id_reschedule_fulfillment", "summary": "Create reschedule fulfillment", "description": "Change the fulfillment date for the order's scheduled fulfillment orders.\n\n**Note:** Accepts the same ISO 8601 timestamp as the merchant dashboard.", "tags": [ "Preorders · Orders" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "reschedule fulfillment", "change fulfillment date" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fulfill_at": { "type": "string", "minLength": 1 } }, "required": [ "fulfill_at" ] }, "example": { "fulfill_at": "2026-07-01T00:00:00Z" } } } } } }, "/preorders/orders/{id}/reschedule_payment": { "post": { "operationId": "post_preorders_orders_id_reschedule_payment", "summary": "Create reschedule payment", "description": "Change the due date for the order's remaining-balance payment schedule.\n\n**Note:** Accepts a calendar date (YYYY-MM-DD) and changes the payment schedule only; it does not charge or refund money.", "tags": [ "Preorders · Orders" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "reschedule payment", "change payment due date" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "due_at": { "type": "string", "minLength": 1 } }, "required": [ "due_at" ] }, "example": { "due_at": "2026-07-01T00:00:00Z" } } } } } }, "/preorders/orders/{id}/split_fulfillment_orders": { "post": { "operationId": "post_preorders_orders_id_split_fulfillment_orders", "summary": "Create split fulfillment orders", "description": "Split the order's fulfillment orders so preorder items ship separately from regular items.", "tags": [ "Preorders · Orders" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "split order", "separate preorder lines", "split fulfillments", "separate preorder from regular" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/preorders/orders/{id}/tags": { "get": { "operationId": "get_preorders_orders_id_tags", "summary": "Get tags", "description": "Read the order tags applied by Stoq.", "tags": [ "Preorders · Orders" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "order tags", "order labels", "tag the order" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch_preorders_orders_id_tags", "summary": "Update tags", "description": "Replace the order's tag set. PATCH form of tags/set.\n\n**Note:** `tags` is replaced wholesale (delegates to tags/set). `applied_by_stoq` and `applied_by_merchant` are read-only.", "tags": [ "Preorders · Orders" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "update order tags", "edit order tags", "replace order tags" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": { "type": [ "null", "array" ] } } }, "example": { "tags": "string" } } } } } }, "/preorders/orders/{id}/tags/add": { "post": { "operationId": "post_preorders_orders_id_tags_add", "summary": "Create tags add", "description": "Add one or more tags to the Shopify order.", "tags": [ "Preorders · Orders" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "add order tag", "add tag", "tag the order", "append order tag" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": {} } }, "example": { "tags": "string" } } } } } }, "/preorders/orders/{id}/tags/remove": { "post": { "operationId": "post_preorders_orders_id_tags_remove", "summary": "Create tags remove", "description": "Remove one or more tags from the Shopify order.", "tags": [ "Preorders · Orders" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "remove order tag", "remove tag", "untag the order", "drop order tag" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": {} } }, "example": { "tags": "string" } } } } } }, "/preorders/orders/{id}/tags/set": { "post": { "operationId": "post_preorders_orders_id_tags_set", "summary": "Create tags set", "description": "Replace every tag on the Shopify order with the supplied list.\n\n**Note:** Pass an empty list to clear all tags. Implemented as fetch-current + remove stale + add new on the Shopify side.", "tags": [ "Preorders · Orders" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "set order tags", "replace order tags", "overwrite order tags", "reset tags on order" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": {} } }, "example": { "tags": "string" } } } } } }, "/preorders/orders/{id}/timeline": { "get": { "operationId": "get_preorders_orders_id_timeline", "summary": "Get timeline", "description": "Order history / activity log for a preorder order: every notification sent, payment attempt, fulfillment hold, and order split, in order, with timestamps.\n\n**Note:** `:id` is any order reference, as for GET /preorders/orders/:id; covers back-in-stock orders and orders not yet synced from Shopify.", "tags": [ "Preorders · Orders" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "order timeline", "order history", "order activity log", "what happened to this order" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/preorders/orders/bulk_cancel": { "post": { "operationId": "post_preorders_orders_bulk_cancel", "summary": "Bulk Cancel", "description": "Cancel many preorder orders (max 1000), with optional refund flags.", "tags": [ "Preorders · Orders" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "bulk cancel", "cancel many orders", "batch cancel preorders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "order_ids": {}, "refund_deposit": {}, "refund_balance": {}, "notify_customer": {}, "reason": {} } }, "example": { "order_ids": [ "string" ], "refund_deposit": "string", "refund_balance": "string", "notify_customer": "string", "reason": "string" } } } } } }, "/preorders/orders/bulk_release": { "post": { "operationId": "post_preorders_orders_bulk_release", "summary": "Bulk Release", "description": "Release fulfillments on many preorder orders (max 1000).", "tags": [ "Preorders · Orders" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "bulk release", "release many orders", "batch release", "release these orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "order_ids": {} } }, "example": { "order_ids": [ "string" ] } } } } } }, "/preorders/orders/bulk_send_payment_collection_url": { "post": { "operationId": "post_preorders_orders_bulk_send_payment_collection_url", "summary": "Bulk Send Payment Collection Url", "description": "Send payment-collection URLs to many preorder customers (max 1000).", "tags": [ "Preorders · Orders" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "bulk send payment collection url", "request balance from many customers", "send payment links in bulk", "ask many customers for balance" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "order_ids": {} } }, "example": { "order_ids": [ "string" ] } } } } } }, "/preorders/orders/bulk_set_tags": { "post": { "operationId": "post_preorders_orders_bulk_set_tags", "summary": "Bulk Set Tags", "description": "Apply tags to many preorder orders in one job (max 1000).\n\n**Note:** `mode` is one of add | remove | replace (default add). `replace` overwrites each order's full tag set.", "tags": [ "Preorders · Orders" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "bulk set tags", "tag many orders", "batch tag orders", "add tags to many orders", "remove tags from many orders", "replace tags on many orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "order_ids": {}, "tags": {}, "mode": { "type": [ "null", "string" ] } } }, "example": { "order_ids": [ "string" ], "tags": "string", "mode": "string" } } } } } }, "/preorders/orders/jobs/{job_id}": { "get": { "operationId": "get_preorders_orders_jobs_job_id", "summary": "Get jobs", "description": "Check the status of a bulk-order job.", "tags": [ "Preorders · Orders" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "check bulk order job", "poll bulk order job", "get order job status" ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/preorders/product_variants": { "get": { "operationId": "get_preorders_product_variants", "summary": "List product variants", "description": "List Shopify variants attached to any preorder offer in this shop.", "tags": [ "Preorders · Product Variants" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "list preorder variants", "variants in preorder", "find variants in preorder offers", "preorder variants", "all preorder variants" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "per_page", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "offer_id", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "product_id", "in": "query", "required": false, "schema": {}, "example": "78000000001" }, { "name": "variant_ids", "in": "query", "required": false, "schema": {}, "example": [ "45000000001" ] } ] } }, "/preorders/product_variants/{variant_id}": { "get": { "operationId": "get_preorders_product_variants_variant_id", "summary": "Get product variants", "description": "Read a Shopify variant's preorder context: every offer it's in, aggregate counts, and current metafield state.", "tags": [ "Preorders · Product Variants" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "show preorder context for variant", "look up variant preorders", "variant preorder state", "get preorder variant", "show variant in preorders" ], "parameters": [ { "name": "variant_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/preorders/product_variants/{variant_id}/detach_from_all_offers": { "post": { "operationId": "post_preorders_product_variants_variant_id_detach_from_all_offers", "summary": "Detach From All Offers", "description": "Remove a variant from every preorder offer it's attached to. Customer orders are unaffected.\n\n**Note:** Destructive. Same effect as calling Offer::Products::RemoveVariants against every offer the variant is in.", "tags": [ "Preorders · Product Variants" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "remove variant from all preorders", "detach from preorder", "kick variant out of offers", "remove from all offers" ], "parameters": [ { "name": "variant_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/preorders/product_variants/{variant_id}/offers": { "get": { "operationId": "get_preorders_product_variants_variant_id_offers", "summary": "Get offers", "description": "List the preorder offers a Shopify variant is attached to.", "tags": [ "Preorders · Product Variants" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "which offers is this variant in", "find offers for variant", "variant's preorder offers", "what offers contain this variant" ], "parameters": [ { "name": "variant_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "schema": {}, "example": "string" } ] } }, "/preorders/product_variants/{variant_id}/recalculate_preorder_count": { "post": { "operationId": "post_preorders_product_variants_variant_id_recalculate_preorder_count", "summary": "Create recalculate preorder count", "description": "Recompute preorder_count for a variant from active order line items, then push to Shopify.", "tags": [ "Preorders · Product Variants" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "recalculate preorder count from orders", "fix preorder count", "rebuild count", "recompute preorder count", "fix variant count drift" ], "parameters": [ { "name": "variant_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/preorders/product_variants/{variant_id}/reset_metafields": { "post": { "operationId": "post_preorders_product_variants_variant_id_reset_metafields", "summary": "Reset Metafields", "description": "Reset a variant's preorder counts (its preorder orders stop counting, the recounted count of its live offer is republished, and the count is cleared when it has none) and rebuild its shipping text and limit metafields from its live offers. Keeps the variant attached to its offers.\n\n**Note:** Doesn't detach. Shipping text and limit are cleared only where no live offer sets them.", "tags": [ "Preorders · Product Variants" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "clear preorder metafields", "wipe variant preorder data", "reset variant metafields", "clear variant metafields" ], "parameters": [ { "name": "variant_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/preorders/product_variants/{variant_id}/reset_preorder_count": { "post": { "operationId": "post_preorders_product_variants_variant_id_reset_preorder_count", "summary": "Reset Preorder Count", "description": "Hard-reset the preorder_count metafield + DB columns on a variant to zero.\n\n**Note:** Use recalculate_preorder_count for a recompute from real orders; this is a destructive zero.", "tags": [ "Preorders · Product Variants" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "zero out preorder count", "clear preorder count", "reset count to zero" ], "parameters": [ { "name": "variant_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/preorders/product_variants/{variant_id}/sync_metafields": { "post": { "operationId": "post_preorders_product_variants_variant_id_sync_metafields", "summary": "Sync Metafields", "description": "Force-resync every preorder metafield for a variant from local DB state to Shopify.\n\n**Note:** Idempotent. Useful when a previous metafield write failed.", "tags": [ "Preorders · Product Variants" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "force resync to shopify", "push metafields to shopify", "refresh shopify metafields", "fix shopify metafield drift" ], "parameters": [ { "name": "variant_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/preorders/product_variants/availability": { "get": { "operationId": "get_preorders_product_variants_availability", "summary": "Get availability", "description": "Resolve whether Shopify variants are on preorder for a buyer country: the preorder that applies, remaining allowance and customer-facing shipping text. Beta.\n\n**Note:** country is the buyer's ISO 3166-1 alpha-2 country. `enabled` is true when a preorder applies and has allowance; the caller still checks live inventory per `preorder_type`. Unknown or deleted variants are `not_enrolled`; malformed ids are listed in `errors`.", "tags": [ "Preorders · Product Variants" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "variant availability", "is variant on preorder", "preorder availability by country", "remaining preorder allowance", "resolve preorder for country" ], "parameters": [ { "name": "country", "in": "query", "required": true, "schema": {}, "example": "US" }, { "name": "variant_ids", "in": "query", "required": false, "schema": {}, "example": [ "45000000001" ] } ] } }, "/preorders/product_variants/bulk_recalculate_preorder_counts": { "post": { "operationId": "post_preorders_product_variants_bulk_recalculate_preorder_counts", "summary": "Bulk Recalculate Preorder Counts", "description": "Recompute preorder_count for many variants in one job (max 5000).", "tags": [ "Preorders · Product Variants" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "recalculate counts for variants", "bulk fix preorder counts", "recalculate many variants", "batch recompute counts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variant_ids": {} } }, "example": { "variant_ids": [ "45000000001" ] } } } } } }, "/preorders/product_variants/bulk_reset_metafields": { "post": { "operationId": "post_preorders_product_variants_bulk_reset_metafields", "summary": "Bulk Reset Metafields", "description": "Reset preorder metafields for many variants in one job (max 5000).", "tags": [ "Preorders · Product Variants" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "clear metafields for variants", "bulk reset variant metafields", "wipe metafields for many variants" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variant_ids": {} } }, "example": { "variant_ids": [ "45000000001" ] } } } } } }, "/preorders/product_variants/bulk_sync_metafields": { "post": { "operationId": "post_preorders_product_variants_bulk_sync_metafields", "summary": "Bulk Sync Metafields", "description": "Force-resync preorder metafields for many variants in one job (max 5000).", "tags": [ "Preorders · Product Variants" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "force resync many variants", "bulk refresh metafields", "push many variants to shopify" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variant_ids": {} } }, "example": { "variant_ids": [ "45000000001" ] } } } } } }, "/preorders/product_variants/jobs/{job_id}": { "get": { "operationId": "get_preorders_product_variants_jobs_job_id", "summary": "Get jobs", "description": "Check the status of a bulk variant-admin job.", "tags": [ "Preorders · Product Variants" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "check bulk variant job status", "poll bulk variant job", "get variant job status" ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/preorders/products/inventory_status": { "get": { "operationId": "get_preorders_products_inventory_status", "summary": "Get inventory status", "description": "Live Shopify inventory for a set of variants, plus a per-attached-offer diagnosis of whether the preorder button is eligible to show. Makes a live Shopify API call and may be slow.", "tags": [ "Preorders · Products" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "inventory status", "preorder button eligibility", "why is the preorder button missing", "check inventory", "button eligibility diagnosis" ], "parameters": [ { "name": "variant_ids", "in": "query", "required": true, "schema": {}, "example": [ "45000000001" ] } ] } }, "/preorders/reports": { "get": { "operationId": "get_preorders_reports", "summary": "List reports", "description": "List every available preorder report (name, description, aliases, url).", "tags": [ "Preorders · Reports" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "reports", "list reports", "available reports", "what reports are there", "report catalog" ] } }, "/preorders/reports/balance_collection": { "get": { "operationId": "get_preorders_reports_balance_collection", "summary": "Get balance collection", "description": "Outstanding preorder balances and balance-collection performance metrics.", "tags": [ "Preorders · Reports" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "outstanding balances", "balance collection", "who hasn't paid", "balance status", "payment collection", "outstanding payments" ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "to", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "offer_id", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "offer_ids", "in": "query", "required": false, "schema": {}, "example": [ "string" ] }, { "name": "currency", "in": "query", "required": false, "schema": {}, "example": "string" } ] } }, "/preorders/reports/balance_collection/export": { "post": { "operationId": "post_preorders_reports_balance_collection_export", "summary": "Create balance collection export", "description": "Async CSV export of the balance-collection report.", "tags": [ "Preorders · Reports" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "export balance_collection", "download outstanding balances", "balance collection csv", "export who hasn't paid" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": {}, "to": {}, "offer_id": {}, "offer_ids": {}, "product_id": {}, "variant_id": {}, "market_id": {}, "currency": {}, "granularity": {}, "metrics": {}, "include_deposits": {}, "include_balances": {}, "page": {}, "per_page": {} } }, "example": { "from": "string", "to": "string", "offer_id": "string", "offer_ids": [ "string" ], "product_id": "78000000001", "variant_id": "45000000001", "market_id": "gid://shopify/Market/12345", "currency": "string", "granularity": "string", "metrics": "string", "include_deposits": "string", "include_balances": "string", "page": "string", "per_page": "string" } } } } } }, "/preorders/reports/by_date": { "get": { "operationId": "get_preorders_reports_by_date", "summary": "Get by date", "description": "Time-series of all preorder metrics at the chosen granularity (day/week/month).", "tags": [ "Preorders · Reports" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "time series", "daily breakdown", "trend", "over time", "preorder trend", "show trend" ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "to", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "offer_id", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "offer_ids", "in": "query", "required": false, "schema": {}, "example": [ "string" ] }, { "name": "product_id", "in": "query", "required": false, "schema": {}, "example": "78000000001" }, { "name": "variant_id", "in": "query", "required": false, "schema": {}, "example": "45000000001" }, { "name": "market_id", "in": "query", "required": false, "schema": {}, "example": "gid://shopify/Market/12345" }, { "name": "currency", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "granularity", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "metrics", "in": "query", "required": false, "schema": {}, "example": "string" } ] } }, "/preorders/reports/by_date/export": { "post": { "operationId": "post_preorders_reports_by_date_export", "summary": "Create by date export", "description": "Async CSV export of the time-series preorder report.", "tags": [ "Preorders · Reports" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "export by_date", "download time series", "trend csv" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": {}, "to": {}, "offer_id": {}, "offer_ids": {}, "product_id": {}, "variant_id": {}, "market_id": {}, "currency": {}, "granularity": {}, "metrics": {}, "include_deposits": {}, "include_balances": {}, "page": {}, "per_page": {} } }, "example": { "from": "string", "to": "string", "offer_id": "string", "offer_ids": [ "string" ], "product_id": "78000000001", "variant_id": "45000000001", "market_id": "gid://shopify/Market/12345", "currency": "string", "granularity": "string", "metrics": "string", "include_deposits": "string", "include_balances": "string", "page": "string", "per_page": "string" } } } } } }, "/preorders/reports/by_offer": { "get": { "operationId": "get_preorders_reports_by_offer", "summary": "Get by offer", "description": "Per-offer breakdown of preorder activity (orders, units, revenue, customers).", "tags": [ "Preorders · Reports" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "per-offer report", "offer performance", "which offers are working", "compare offers", "report by offer" ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "to", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "offer_ids", "in": "query", "required": false, "schema": {}, "example": [ "string" ] }, { "name": "market_id", "in": "query", "required": false, "schema": {}, "example": "gid://shopify/Market/12345" }, { "name": "currency", "in": "query", "required": false, "schema": {}, "example": "string" } ] } }, "/preorders/reports/by_offer/export": { "post": { "operationId": "post_preorders_reports_by_offer_export", "summary": "Create by offer export", "description": "Async CSV export of the per-offer preorder report.", "tags": [ "Preorders · Reports" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "export by_offer", "download by_offer", "by offer csv" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": {}, "to": {}, "offer_id": {}, "offer_ids": {}, "product_id": {}, "variant_id": {}, "market_id": {}, "currency": {}, "granularity": {}, "metrics": {}, "include_deposits": {}, "include_balances": {}, "page": {}, "per_page": {} } }, "example": { "from": "string", "to": "string", "offer_id": "string", "offer_ids": [ "string" ], "product_id": "78000000001", "variant_id": "45000000001", "market_id": "gid://shopify/Market/12345", "currency": "string", "granularity": "string", "metrics": "string", "include_deposits": "string", "include_balances": "string", "page": "string", "per_page": "string" } } } } } }, "/preorders/reports/by_product": { "get": { "operationId": "get_preorders_reports_by_product", "summary": "Get by product", "description": "Per-product preorder performance, rolled up across variants.", "tags": [ "Preorders · Reports" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "per-product report", "product performance", "which products are preordering", "report by product" ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "to", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "offer_id", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "offer_ids", "in": "query", "required": false, "schema": {}, "example": [ "string" ] }, { "name": "product_id", "in": "query", "required": false, "schema": {}, "example": "78000000001" }, { "name": "currency", "in": "query", "required": false, "schema": {}, "example": "string" } ] } }, "/preorders/reports/by_product/export": { "post": { "operationId": "post_preorders_reports_by_product_export", "summary": "Create by product export", "description": "Async CSV export of the per-product preorder report.", "tags": [ "Preorders · Reports" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "export by_product", "download by_product", "by product csv" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": {}, "to": {}, "offer_id": {}, "offer_ids": {}, "product_id": {}, "variant_id": {}, "market_id": {}, "currency": {}, "granularity": {}, "metrics": {}, "include_deposits": {}, "include_balances": {}, "page": {}, "per_page": {} } }, "example": { "from": "string", "to": "string", "offer_id": "string", "offer_ids": [ "string" ], "product_id": "78000000001", "variant_id": "45000000001", "market_id": "gid://shopify/Market/12345", "currency": "string", "granularity": "string", "metrics": "string", "include_deposits": "string", "include_balances": "string", "page": "string", "per_page": "string" } } } } } }, "/preorders/reports/by_variant": { "get": { "operationId": "get_preorders_reports_by_variant", "summary": "Get by variant", "description": "Per-variant preorder performance for a specific offer.\n\n**Note:** Requires offer_id (or offer_ids[]). Variant-level data without an offer scope isn't supported.", "tags": [ "Preorders · Reports" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "per-variant report", "variant performance", "which variants are selling", "variant report" ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "to", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "offer_id", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "offer_ids", "in": "query", "required": false, "schema": {}, "example": [ "string" ] }, { "name": "product_id", "in": "query", "required": false, "schema": {}, "example": "78000000001" }, { "name": "variant_id", "in": "query", "required": false, "schema": {}, "example": "45000000001" }, { "name": "currency", "in": "query", "required": false, "schema": {}, "example": "string" } ] } }, "/preorders/reports/by_variant/export": { "post": { "operationId": "post_preorders_reports_by_variant_export", "summary": "Create by variant export", "description": "Async CSV export of the per-variant preorder report.", "tags": [ "Preorders · Reports" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "export by_variant", "download by_variant", "by variant csv" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": {}, "to": {}, "offer_id": {}, "offer_ids": {}, "product_id": {}, "variant_id": {}, "market_id": {}, "currency": {}, "granularity": {}, "metrics": {}, "include_deposits": {}, "include_balances": {}, "page": {}, "per_page": {} } }, "example": { "from": "string", "to": "string", "offer_id": "string", "offer_ids": [ "string" ], "product_id": "78000000001", "variant_id": "45000000001", "market_id": "gid://shopify/Market/12345", "currency": "string", "granularity": "string", "metrics": "string", "include_deposits": "string", "include_balances": "string", "page": "string", "per_page": "string" } } } } } }, "/preorders/reports/cancellations": { "get": { "operationId": "get_preorders_reports_cancellations", "summary": "Get cancellations", "description": "Preorder cancellation metrics with reason and per-offer breakdowns.\n\n**Note:** Reason breakdown requires the cancel_reason field on OrderAttribution. Reasons not yet captured will appear as 'unknown'.", "tags": [ "Preorders · Reports" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "cancellations", "refunds", "how often do customers cancel", "cancellation rate", "cancellation report" ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "to", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "offer_id", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "offer_ids", "in": "query", "required": false, "schema": {}, "example": [ "string" ] }, { "name": "currency", "in": "query", "required": false, "schema": {}, "example": "string" } ] } }, "/preorders/reports/cancellations/export": { "post": { "operationId": "post_preorders_reports_cancellations_export", "summary": "Create cancellations export", "description": "Async CSV export of the cancellations report.", "tags": [ "Preorders · Reports" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "export cancellations", "download cancellations", "cancellations csv" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": {}, "to": {}, "offer_id": {}, "offer_ids": {}, "product_id": {}, "variant_id": {}, "market_id": {}, "currency": {}, "granularity": {}, "metrics": {}, "include_deposits": {}, "include_balances": {}, "page": {}, "per_page": {} } }, "example": { "from": "string", "to": "string", "offer_id": "string", "offer_ids": [ "string" ], "product_id": "78000000001", "variant_id": "45000000001", "market_id": "gid://shopify/Market/12345", "currency": "string", "granularity": "string", "metrics": "string", "include_deposits": "string", "include_balances": "string", "page": "string", "per_page": "string" } } } } } }, "/preorders/reports/customers": { "get": { "operationId": "get_preorders_reports_customers", "summary": "Get customers", "description": "Paginated list of customers with preorder activity in the window.", "tags": [ "Preorders · Reports" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "customer list", "who preordered", "preorder customers", "customers report", "list customers" ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "to", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "offer_id", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "offer_ids", "in": "query", "required": false, "schema": {}, "example": [ "string" ] }, { "name": "currency", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "page", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "per_page", "in": "query", "required": false, "schema": {}, "example": "string" } ] } }, "/preorders/reports/customers/export": { "post": { "operationId": "post_preorders_reports_customers_export", "summary": "Create customers export", "description": "Async CSV export of the customers report.", "tags": [ "Preorders · Reports" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "export customers", "download customers", "customers csv" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": {}, "to": {}, "offer_id": {}, "offer_ids": {}, "product_id": {}, "variant_id": {}, "market_id": {}, "currency": {}, "granularity": {}, "metrics": {}, "include_deposits": {}, "include_balances": {}, "page": {}, "per_page": {} } }, "example": { "from": "string", "to": "string", "offer_id": "string", "offer_ids": [ "string" ], "product_id": "78000000001", "variant_id": "45000000001", "market_id": "gid://shopify/Market/12345", "currency": "string", "granularity": "string", "metrics": "string", "include_deposits": "string", "include_balances": "string", "page": "string", "per_page": "string" } } } } } }, "/preorders/reports/engagement": { "get": { "operationId": "get_preorders_reports_engagement", "summary": "Get engagement", "description": "Preorder button engagement/funnel analytics: impressions, add-to-carts, add-to-cart rate, orders, and order rate — the same numbers on the merchant's preorder Engagement dashboard. Rates use unique shoppers. order_rate can exceed 1.0 because orders come from placed preorder orders, a different denominator than unique add-to-carts.", "tags": [ "Preorders · Reports" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "preorder engagement", "preorder funnel", "add to cart rate", "button engagement", "preorder performance" ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "to", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "market_id", "in": "query", "required": false, "schema": {}, "example": "gid://shopify/Market/12345" }, { "name": "variant_ids", "in": "query", "required": false, "schema": {}, "example": [ "45000000001" ] } ] } }, "/preorders/reports/exports/{job_id}": { "get": { "operationId": "get_preorders_reports_exports_job_id", "summary": "Get exports", "description": "Check the status of an async report export and get the download URL when ready.", "tags": [ "Preorders · Reports" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "check export status", "get export", "poll export", "download url for export", "export status" ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/preorders/reports/revenue": { "get": { "operationId": "get_preorders_reports_revenue", "summary": "Get revenue", "description": "Preorder revenue over a date window, bucketed by day/week/month.", "tags": [ "Preorders · Reports" ], "responses": { "200": { "description": "Success — example response shown.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "window": { "from": "2026-05-26T00:00:00Z", "to": "2026-06-25T23:59:59Z" }, "granularity": "day", "currency": "USD", "include_deposits": true, "include_balances": true, "total_revenue": "47825.50", "series": [ { "date": "2026-06-25T00:00:00Z", "revenue": "2450.75", "orders": 18 }, { "date": "2026-06-24T00:00:00Z", "revenue": "3180.25", "orders": 24 } ], "by_offer": [ { "offer_id": 1, "offer_name": "Summer Sneaker Drop", "revenue": "28500.00" }, { "offer_id": 2, "offer_name": "Winter Collection", "revenue": "19325.50" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "revenue", "how much money", "sales", "preorder revenue", "how much did we make", "what did we earn" ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "to", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "offer_id", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "offer_ids", "in": "query", "required": false, "schema": {}, "example": [ "string" ] }, { "name": "product_id", "in": "query", "required": false, "schema": {}, "example": "78000000001" }, { "name": "variant_id", "in": "query", "required": false, "schema": {}, "example": "45000000001" }, { "name": "market_id", "in": "query", "required": false, "schema": {}, "example": "gid://shopify/Market/12345" }, { "name": "currency", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "granularity", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "include_deposits", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "include_balances", "in": "query", "required": false, "schema": {}, "example": "string" } ] } }, "/preorders/reports/revenue/export": { "post": { "operationId": "post_preorders_reports_revenue_export", "summary": "Create revenue export", "description": "Async CSV export of the preorder revenue report.", "tags": [ "Preorders · Reports" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "export revenue", "download revenue", "revenue csv" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": {}, "to": {}, "offer_id": {}, "offer_ids": {}, "product_id": {}, "variant_id": {}, "market_id": {}, "currency": {}, "granularity": {}, "metrics": {}, "include_deposits": {}, "include_balances": {}, "page": {}, "per_page": {} } }, "example": { "from": "string", "to": "string", "offer_id": "string", "offer_ids": [ "string" ], "product_id": "78000000001", "variant_id": "45000000001", "market_id": "gid://shopify/Market/12345", "currency": "string", "granularity": "string", "metrics": "string", "include_deposits": "string", "include_balances": "string", "page": "string", "per_page": "string" } } } } } }, "/preorders/reports/summary": { "get": { "operationId": "get_preorders_reports_summary", "summary": "Get summary", "description": "High-level overview of preorder activity over a date window.", "tags": [ "Preorders · Reports" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "summary", "overview", "how is preorder doing", "preorder summary", "dashboard stats", "what's happening with preorders" ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": [ "null", "string" ] }, "example": "string" }, { "name": "from", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "to", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "offer_id", "in": "query", "required": false, "schema": {}, "example": "string" }, { "name": "offer_ids", "in": "query", "required": false, "schema": {}, "example": [ "string" ] }, { "name": "product_id", "in": "query", "required": false, "schema": {}, "example": "78000000001" }, { "name": "variant_id", "in": "query", "required": false, "schema": {}, "example": "45000000001" }, { "name": "market_id", "in": "query", "required": false, "schema": {}, "example": "gid://shopify/Market/12345" }, { "name": "currency", "in": "query", "required": false, "schema": {}, "example": "string" } ] } }, "/preorders/reports/summary/export": { "post": { "operationId": "post_preorders_reports_summary_export", "summary": "Create summary export", "description": "Async CSV export of the preorder summary report.", "tags": [ "Preorders · Reports" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "export summary", "download summary", "summary csv", "export overview" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": {}, "to": {}, "offer_id": {}, "offer_ids": {}, "product_id": {}, "variant_id": {}, "market_id": {}, "currency": {}, "granularity": {}, "metrics": {}, "include_deposits": {}, "include_balances": {}, "page": {}, "per_page": {} } }, "example": { "from": "string", "to": "string", "offer_id": "string", "offer_ids": [ "string" ], "product_id": "78000000001", "variant_id": "45000000001", "market_id": "gid://shopify/Market/12345", "currency": "string", "granularity": "string", "metrics": "string", "include_deposits": "string", "include_balances": "string", "page": "string", "per_page": "string" } } } } } }, "/preorders/settings/pages": { "get": { "operationId": "get_preorders_settings_pages", "summary": "Get pages", "description": "The Preorder pages settings (Preorders > Settings > Pages): whether the Preorder button shows on the home, collection and search pages, whether collection pages show the preorder badge when any variant is a preorder, and the locations and markets those pages count stock at. Shop-wide, not per offer. Product pages always show the button. The page's CSS selectors (Dev mode) are not part of it.", "tags": [ "Preorders · Settings" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "preorder pages", "preorder on collection page", "preorder on home page", "preorder on search page", "preorder button on other pages", "collection page badge", "preorder location filter" ] }, "patch": { "operationId": "patch_preorders_settings_pages", "summary": "Update pages", "description": "Update the Preorder pages settings (Preorders > Settings > Pages): the Preorder button on the home, collection and search pages, the collection-page badge rule, and the locations and markets those pages count stock at. Shop-wide, not per offer. Does not change the page's CSS selectors.\n\n**Note:** Deep partial. home.enabled, collection.enabled and search.enabled switch the Preorder button on those pages. locations.location_ids is replaced wholesale when present. market_setup and market_locations_enabled are the same settings as in the back-in-stock Delivery settings.", "tags": [ "Preorders · Settings" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "show preorder on collection page", "show preorder on home page", "show preorder on search page", "hide preorder on collection page", "turn off preorder on search page", "show preorder badge if any variant is preorder", "preorder location filter", "filter preorder locations", "preorder market setup" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "home": {}, "collection": {}, "search": {}, "locations": {}, "market_setup": {}, "market_locations_enabled": {} } }, "example": { "home": "string", "collection": "string", "search": "string", "locations": "string", "market_setup": "gid://shopify/Market/12345", "market_locations_enabled": "gid://shopify/Market/12345" } } } } } }, "/preorders/settings/storefront_text": { "get": { "operationId": "get_preorders_settings_storefront_text", "summary": "Get storefront text", "description": "The shop-wide preorder storefront text: the currency format, the button's out-of-stock and add-to-cart text, and the preorder modal's continue and cancel buttons and error heading. Shared by every preorder offer. Pass `locale` to read one language's translation.", "tags": [ "Preorders · Settings" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "preorder currency format", "preorder out of stock text", "preorder add to cart text", "preorder modal button text", "preorder error heading", "preorder storefront text" ], "parameters": [ { "name": "locale", "in": "query", "required": false, "schema": {}, "example": "fr" } ] }, "patch": { "operationId": "patch_preorders_settings_storefront_text", "summary": "Update storefront text", "description": "Update the shop-wide preorder storefront text: the currency format, the button's out-of-stock and add-to-cart text, and the preorder modal's continue and cancel buttons and error heading. Shared by every preorder offer, not per offer.\n\n**Note:** Deep partial. Shop-wide: one change applies to every preorder offer. The per-offer Preorder button text and per-state overrides are on the offer's widget and advanced settings. Text fields are written in `locale` (optional); currency_format is not translated.", "tags": [ "Preorders · Settings" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "change preorder currency format", "change preorder out of stock text", "change preorder add to cart text", "change preorder modal continue button", "change preorder modal cancel button", "change preorder error heading", "translate preorder modal buttons" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "locale": {}, "currency_format": {}, "button": {}, "modal": {} } }, "example": { "locale": "fr", "currency_format": "string", "button": "string", "modal": "string" } } } } } }, "/preorders/templates/{locale}": { "get": { "operationId": "get_preorders_templates_locale", "summary": "Get templates", "description": "Read the position-0 preorder confirmation email/SMS template for a locale.", "tags": [ "Preorders · Templates" ], "responses": { "200": { "description": "Success — the requested resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "get preorder template", "show preorder email", "preorder confirmation email", "preorder confirmation sms", "localized preorder notification template" ], "parameters": [ { "name": "locale", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch_preorders_templates_locale", "summary": "Update templates", "description": "Update the position-0 preorder confirmation email/SMS template for a locale.\n\n**Note:** Deep partial over the template fields. Rejects HTML (except in email_css_config) and runs Template validations and callbacks. email_reviews_title is the heading for the Judge.me reviews section that renders on the preorder confirmation email (for example \"What customers are saying\"). Colours are flat hex fields. Social links and the social icon colour are shared: saving one sets it on every notification template of the shop.", "tags": [ "Preorders · Templates" ], "responses": { "200": { "description": "Success — the updated resource.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted — async/bulk work was queued. Poll the returned job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-aliases": [ "edit preorder template", "change preorder email", "change preorder sms", "update preorder confirmation", "localize preorder template" ], "parameters": [ { "name": "locale", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email_subject": { "type": "string", "minLength": 1 }, "email_preheader": { "type": "string" }, "email_header": { "type": "string", "minLength": 1 }, "email_description": { "type": "string", "minLength": 1 }, "email_button_text": { "type": "string", "minLength": 1 }, "email_footer": { "type": "string", "minLength": 1 }, "email_reviews_title": { "type": "string", "minLength": 1 }, "push_title": { "type": "string", "minLength": 1 }, "push_body": { "type": "string", "minLength": 1 }, "push_button_text": { "type": "string", "minLength": 1 }, "sms_body": { "type": "string", "minLength": 1 }, "klaviyo_flow_name": { "type": "string" }, "klaviyo_sms_flow_name": { "type": "string" }, "email_background_color": { "type": "string", "minLength": 1 }, "email_section_color": { "type": "string", "minLength": 1 }, "email_text_color": { "type": "string", "minLength": 1 }, "email_border_radius": {}, "email_button_background_color": { "type": "string", "minLength": 1 }, "email_button_text_color": { "type": "string", "minLength": 1 }, "email_button_border_radius": {}, "email_css_config": { "type": "string" }, "email_facebook_link": { "type": "string" }, "email_instagram_link": { "type": "string" }, "email_pinterest_link": { "type": "string" }, "email_twitter_link": { "type": "string" }, "email_tiktok_link": { "type": "string" }, "email_whatsapp_link": { "type": "string" }, "email_youtube_link": { "type": "string" }, "email_social_icon_color": { "type": "string", "minLength": 1 }, "email_reviews_enabled": { "type": "boolean" }, "email_reviews_count": {}, "email_reviews_min_rating": {} } }, "example": { "email_subject": "string", "email_preheader": "string", "email_header": "string", "email_description": "string", "email_button_text": "Preorder now", "email_footer": "string", "email_reviews_title": "string", "push_title": "string", "push_body": "string", "push_button_text": "Preorder now", "sms_body": "string", "klaviyo_flow_name": "Summer Sneaker Drop", "klaviyo_sms_flow_name": "Summer Sneaker Drop", "email_background_color": "#1A1A1A", "email_section_color": "#1A1A1A", "email_text_color": "#1A1A1A", "email_border_radius": "string", "email_button_background_color": "#1A1A1A", "email_button_text_color": "#1A1A1A", "email_button_border_radius": "string", "email_css_config": "string", "email_facebook_link": "string", "email_instagram_link": "string", "email_pinterest_link": "string", "email_twitter_link": "string", "email_tiktok_link": "string", "email_whatsapp_link": "string", "email_youtube_link": "string", "email_social_icon_color": "#1A1A1A", "email_reviews_enabled": true, "email_reviews_count": 5, "email_reviews_min_rating": "string" } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Auth-Token" } }, "schemas": { "Error": { "type": "object", "description": "Error envelope returned by every failed request.", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "errors" ], "example": { "errors": [ "name is required" ] } }, "JobAccepted": { "type": "object", "description": "Returned for async/bulk work — poll the job until it reaches a terminal state.", "properties": { "job_id": { "type": "string" }, "status_url": { "type": "string" } }, "example": { "job_id": "job_a1b2c3", "status_url": "/api/v2/external/jobs/job_a1b2c3" } } }, "responses": { "Unauthorized": { "description": "Missing or invalid `X-Auth-Token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": [ "Unauthorized" ] } } } }, "NotFound": { "description": "The resource does not exist for this shop, or the action path is not registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": [ "Offer not found" ] } } } }, "Conflict": { "description": "Invalid lifecycle transition — read the message; don't retry blindly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": [ "Offer is already disabled" ] } } } }, "ValidationError": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": [ "name is required" ] } } } }, "RateLimited": { "description": "Rate limited — cost-weighted per token (read 1, write 2; 360 points / 60s). Check `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": [ "Rate limit exceeded" ] } } } } } } }