Preorder settings and notifications
Shop-wide preorder settings, and the copy and switches of the emails and SMS STOQ sends preorder customers.
BetaAPI v2 is in public beta: endpoints, fields and behaviour can change before general availability. See the changelog
Last updated
Most preorder behavior lives on an offer. A few things are shared by every offer in the shop and live here instead:
- Settings: the storefront text, the pages that show the Preorder button, the theme selectors, and the merchant’s payment-collection email.
- Templates: the copy of the three notifications STOQ sends preorder customers.
- Notification settings: whether the confirmation email and SMS send at all.
Each is a singleton with no :id: read it with GET, change it with a deep-partial PATCH.
How a PATCH behaves
Section titled “How a PATCH behaves”Every PATCH on this page works the same way:
- Send only the fields you want to change, nested as deep as needed. Absent fields keep their value.
- An unknown or read-only key is rejected with
422invalid_params. Each entry indetailshas thepathof the bad field, for exampletemplate.email.bogus. - A successful write returns
202with the whole section as aGETwould return it, so you don’t need to read it again.
curl -X PATCH https://app.stoqapp.com/api/v2/external/preorders/templates/shipping_update \ -H "X-Auth-Token: $STOQ_API_KEY" \ -H "Content-Type: application/json" \ -d '{"email": {"subject": "An update on your preorder from {{shop.name}}"}}'Settings
Section titled “Settings”Path prefix: /preorders/settings
| Method | Path | What it holds |
|---|---|---|
GET / PATCH |
storefront_ |
Currency format, the Preorder button’s out-of-stock and add-to-cart text, the preorder modal’s buttons and error heading |
GET / PATCH |
pages |
Whether the Preorder button shows on the home, collection and search pages |
GET / PATCH |
developer |
Dev mode, custom CSS and the theme selectors that place each preorder element |
GET / PATCH |
reports |
Whether the merchant gets an email when a remaining balance is collected |
Storefront text
Section titled “Storefront text”{ "currency_format": "{{amount}} {{currency}}", "button": { "out_of_stock_text": "Out of stock", "add_to_cart_text": "Add to cart" }, "modal": { "continue_button_text": "Continue", "cancel_button_text": "Cancel", "error_heading": "Error" }, "locale": "en"}These texts apply to every offer. The Preorder button’s own label, and per-state overrides, are set per offer on its widget.
The text fields are translatable. Add ?locale=fr to the GET, or "locale": "fr" to the PATCH body, to read or write one language. Leave it out to use the shop’s default language. currency_format is the same in every language.
Pages and developer settings
Section titled “Pages and developer settings”Product pages always show the Preorder button. pages turns it on for the home, collection and search pages, and collection.show_badge_if_any_variant_is_preorder shows the preorder badge on a collection card when any of the product’s variants is on preorder. See Common tasks for an example.
developer holds the CSS selectors that tell STOQ where to put the Preorder button, badge, payment options, countdown and other elements in a custom theme. STOQ uses the selectors only while dev_mode_enabled is true. Setting a selector to null or "" goes back to the theme default. dev_mode_enabled and css are shared with the back-in-stock widget, so changing them here changes them there too.
Reports
Section titled “Reports”reports has one field, notify_payment_collection_enabled. When it’s true, STOQ emails the merchant each time the remaining balance of a partially paid preorder is collected, automatically or from the dashboard or API. The email goes to the report address, scheduled_reports.email on GET /back_in_stock/settings/alerts. A failed collection emails the merchant whatever this is set to.
Notification templates
Section titled “Notification templates”STOQ sends preorder customers up to three notifications. Their copy is read and written here:
| Key | Channels | Sent when |
|---|---|---|
confirmation |
email, SMS | A customer places a preorder |
shipping_ |
You send it: POST /preorders/orders/:id/send_, its bulk form, or a fulfillment reschedule with send_. STOQ never sends it on its own |
|
payment_ |
STOQ can’t charge the remaining balance of a partially paid preorder |
Path prefix: /preorders/templates
| Method | Path | Description |
|---|---|---|
GET |
(root) | All three templates in send order, each as its own GET returns it |
GET / PATCH |
confirmation |
Email and SMS copy of the confirmation |
POST |
confirmation/send_ |
Send a test confirmation email |
GET / PATCH |
shipping_ |
Email copy of the shipping update |
GET / PATCH |
payment_ |
Email copy of the payment-failed notice |
A template read looks like this:
{ "key": "payment_failed", "locale": "en", "email": { "subject": "Complete payment | Order #{{order.name}} from {{shop.name}}", "heading": "Complete payment for your order", "body": "We couldn't process the remaining balance for your preorder on order #{{order.name}}. Use the button below to complete your payment.", "button_text": "Complete payment", "klaviyo_flow_name": null, "klaviyo_flow_verified": false, "integration": null }}The confirmation also has an sms object with body and klaviyo_flow_name, and a fuller email: preheader, footer, button and color styling, CSS, a product reviews block and social links.
Things to know when you write a template:
- Language. Copy is stored per language.
?locale=on a read, orlocalein aPATCHbody, picks one. Leave it out for the shop’s default language. The response names the language inlocale. - Liquid. Subjects and bodies are Liquid, with variables such as
{{order.name}}and{{shop.name}}. The confirmation SMS body must keep its required variables, or thePATCHfails with422. - No HTML. The copy is plain text. HTML is rejected everywhere except
email.cssin the confirmation. - Shared parts. Social links and the icon color are shared by all the shop’s notification templates. Saving them on the confirmation changes them on every template.
- Klaviyo. When the shop sends email through Klaviyo,
integrationnames the integration (see Account), and the email goes out through the merchant’s Klaviyo flow.klaviyo_flow_namenames that flow, andklaviyo_flow_verified(read-only) says whether STOQ has confirmed the flow exists.
Whose account and address the emails come from is GET /account/sending.
Sending a test
Section titled “Sending a test”POST /preorders/templates/confirmation/send_test sends the confirmation email to one address, rendered with a real product from one of the shop’s offers:
curl -X POST https://app.stoqapp.com/api/v2/external/preorders/templates/confirmation/send_test \ -H "X-Auth-Token: $STOQ_API_KEY" \ -H "Content-Type: application/json" \ -d '{"email": "merchant@example.com", "locale": "en"}'emaildefaults to the shop’s reply-to address.offer_idandshopify_variant_idchoose which offer and product appear in the email. Leave both out to use the first product of the first enabled offer.- It fails with
422when email sending is off or the shop has no product in any offer, and with404when the offer isn’t found.
A shop gets its confirmation template when STOQ is installed. In the rare case it has none, the confirmation is missing from GET /preorders/templates, and its own read, PATCH and send_test return 404.
Notification settings
Section titled “Notification settings”Template copy and the on/off switches are separate. Only the confirmation has switches:
| Method | Path | Description |
|---|---|---|
GET |
/preorders/notification_ |
Every notification’s switches (today, only the confirmation’s) |
GET / PATCH |
/preorders/notification_ |
The confirmation’s switches |
{ "key": "confirmation", "email_enabled": true, "sms_enabled": false, "customer_cancellation_enabled": true}email_enabledandsms_enabledturn the confirmation email and SMS on or off.customer_cancellation_enabledadds a link to the confirmation email that lets the customer cancel their preorder.- With STOQ’s own SMS sending, the first time SMS is switched on, all the shop’s SMS pause until STOQ has reviewed the message content.
Thanks for letting us know.
Still stuck? Ask Quinn or chat with support