Skip to content

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.

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 422 invalid_params. Each entry in details has the path of the bad field, for example template.email.bogus.
  • A successful write returns 202 with the whole section as a GET would 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}}"}}'

Path prefix: /preorders/settings

Method Path What it holds
GET / PATCH storefront_text 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
{
"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.

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 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.

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_update email You send it: POST /preorders/orders/:id/send_shipping_update, its bulk form, or a fulfillment reschedule with send_shipping_update: true. STOQ never sends it on its own
payment_failed email 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_test Send a test confirmation email
GET / PATCH shipping_update Email copy of the shipping update
GET / PATCH payment_failed 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, or locale in a PATCH body, picks one. Leave it out for the shop’s default language. The response names the language in locale.
  • 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 the PATCH fails with 422.
  • No HTML. The copy is plain text. HTML is rejected everywhere except email.css in 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, integration names the integration (see Account), and the email goes out through the merchant’s Klaviyo flow. klaviyo_flow_name names that flow, and klaviyo_flow_verified (read-only) says whether STOQ has confirmed the flow exists.

Whose account and address the emails come from is GET /account/sending.

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"}'
  • email defaults to the shop’s reply-to address.
  • offer_id and shopify_variant_id choose which offer and product appear in the email. Leave both out to use the first product of the first enabled offer.
  • It fails with 422 when email sending is off or the shop has no product in any offer, and with 404 when 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.

Template copy and the on/off switches are separate. Only the confirmation has switches:

Method Path Description
GET /preorders/notification_settings Every notification’s switches (today, only the confirmation’s)
GET / PATCH /preorders/notification_settings/confirmation The confirmation’s switches
{
"key": "confirmation",
"email_enabled": true,
"sms_enabled": false,
"customer_cancellation_enabled": true
}
  • email_enabled and sms_enabled turn the confirmation email and SMS on or off.
  • customer_cancellation_enabled adds 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.
Was this page helpful?

Still stuck? Ask Quinn or chat with support