Update confirmation email
API v2 is in public beta: endpoints and fields can change before general availability. See the changelog
/preorders/templates/confirmationCosts 2 rate-limit points · Rate limits
Update the preorder confirmation notification's email and SMS copy. The body is the GET shape: email{subject, preheader, heading, body, footer, button{text, background_color, text_color, radius}, colors{background, section, text}, radius, css, reviews{enabled, count, min_rating, title}, social{...}, klaviyo_flow_name} and sms{body, klaviyo_flow_name}. An optional body locale writes the copy in that language only; omit it for the shop default. Turning the email or SMS on or off is PATCH /preorders/notification_settings/confirmation.
Deep partial: absent fields are unchanged, unknown or read-only keys are rejected; errors are 422 keyed "template.<path>". Rejects HTML (except in email.css) and runs Template validations and callbacks, so sms.body must keep its required Liquid variables. Social links and the icon colour are shared: saving one sets it on every notification template of the shop. Returns the template.
Also searched asedit preorder templatechange preorder emailupdate preorder confirmationlocalize preorder templatechange preorder sms
Headers
Idempotency-KeystringA fresh unique key for every write (a new UUID, say); reuse it only to retry that write. Keys are remembered for 1 hour: the same key and the same request within that hour returns the first result, with
Idempotent-Replayed: true, without running again; the same key with a different method, path or body is refused (422idempotency_key_reused); a retry while the first is still running gets 409idempotency_key_in_progress. Keys are per store. Server errors and rate limits are not kept, so their retry runs.
Request body
emailobjectCopy and design of the preorder confirmation email.
Show 12 child attributesHide child attributes
subjectstringSubject of the preorder confirmation email.
preheaderstringPre-header -- the preview line after the subject in the inbox.
headingstringHeading at the top of the email body.
bodystringDescription -- the main body copy of the email.
footerstringCancel order link -- the text of the link that lets customers cancel their preorder. Only shown while "Allow customers to cancel preorders" is on.
buttonobjectShow 4 child attributesHide child attributes
textstringButton text on the email call to action.
background_colorstringButton -- Background colour of the email button. Hex.
text_colorstringButton -- Text colour of the email button. Hex.
radiusintegerCorner radius of the email button, in pixels.
colorsobjectShow 3 child attributesHide child attributes
backgroundstringColors -- Background of the email, around the content. Hex, e.g. "#F9F9F9".
sectionstringColors -- Background of the content section of the email. Hex.
textstringColors -- Text colour of the email. Hex.
radiusintegerCorner radius of the content section, in pixels.
cssstringCustom CSS added to the email. Applies to the standard email design. An empty string removes it.
reviewsobjectShow 4 child attributesHide child attributes
enabledbooleanShow product reviews: adds the product's Judge.me star rating and top reviews to the preorder confirmation and shipping update emails. Paid plans only; shows only while Judge.me is connected (Settings > Integrations).
countintegerNumber of reviews to show in the Judge.me reviews block, 1 to 3.
min_ratingintegerOnly show reviews rated at least this many stars: 5, 4 or 3.
One of543titlestringSection title for the Judge.me reviews block on the email, e.g. "What customers are saying".
socialobjectShow 8 child attributesHide child attributes
facebookstringFacebook profile URL, without the https:// prefix. Shows as an icon in the email. Saving a social link sets it on every notification template of the shop. An empty string removes it.
instagramstringInstagram profile URL, without the https:// prefix. Saving a social link sets it on every notification template of the shop.
pintereststringPinterest profile URL, without the https:// prefix. Saving a social link sets it on every notification template of the shop.
twitterstringX (Twitter) profile URL, without the https:// prefix. Saving a social link sets it on every notification template of the shop.
tiktokstringTikTok profile URL, without the https:// prefix. Saving a social link sets it on every notification template of the shop.
whatsappstringWhatsApp link, without the https:// prefix. Saving a social link sets it on every notification template of the shop.
youtubestringYouTube channel URL, without the https:// prefix. Saving a social link sets it on every notification template of the shop.
icon_colorstringIcon Color of the social icons: white (#FFFFFF) or black (#000000). Shared by every template.
One of#FFFFFF#000000
klaviyo_flow_namestringFlow name to trigger in Klaviyo instead of sending the email here. Only used while the email platform is Klaviyo.
smsobjectText of the preorder confirmation SMS.
Show 2 child attributesHide child attributes
bodystringSMS Body -- the text message sent instead of the email. Must keep its Liquid variables.
klaviyo_flow_namestringFlow name to trigger in Klaviyo instead of sending the SMS here. Only used while the SMS platform is Klaviyo.
localestringLanguage the translated fields are written in, such as 'fr' or 'pt-BR'. Omitted: the shop's default language. Untranslated fields ignore it.
Returns
keystringExample:confirmationlocalestringExample:enemailobjectShow 14 child attributesHide child attributes
subjectstringExample:Your preorder is confirmed: {{order.name}}preheadernullheadingstringExample:Thanks for preordering from {{shop.name}}bodystringExample:Your recent order {{order.name}} includes at least one pr…footerstringExample:Cancel orderbuttonobjectShow 4 child attributesHide child attributes
textstringExample:View orderbackground_colorstringExample:#202223text_colorstringExample:#ffffffradiusintegerExample:4
colorsobjectShow 3 child attributesHide child attributes
backgroundstringExample:#f9f9f9sectionstringExample:#fffffftextstringExample:#202223
radiusintegerExample:6cssstring, nullablereviewsobjectShow 4 child attributesHide child attributes
enabledbooleanExample:falsecountintegerExample:2min_ratingintegerExample:4titlestringExample:What customers are saying
socialobjectShow 8 child attributesHide child attributes
facebooknullinstagramstring, nullableExample:https://instagram.com/example_sneakerspinterestnulltwitternulltiktoknullwhatsappnullyoutubenullicon_colorstringExample:#000000
klaviyo_flow_namenullExample:Preorder confirmed (STOQ)klaviyo_flow_verifiedbooleanExample:falseintegrationnull
smsobjectShow 5 child attributesHide child attributes
bodystringExample:Thanks for shopping with {{shop.name}}! Your preorder for…klaviyo_flow_namestring, nullableklaviyo_flow_verifiedbooleanExample:falsepostscript_flow_verifiedbooleanExample:falseintegrationnull
Errors
not_foundThe path is valid but nothing with that id exists in this store.
idempotency_key_in_progressAn earlier request with the same Idempotency-Key is still running. Wait, then resend the same request with the same key.
invalid_paramsOne or more fields failed the action's schema.
Any request can also fail with auth_invalid (401) or rate_limited (429).
Every error has the same shape: see Errors and the list of error codes.
curl -X PATCH "https://app.stoqapp.com/api/v2/external/preorders/templates/confirmation" \
-H "X-Auth-Token: $STOQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": {
"subject": "Your preorder is confirmed: {{order.name}}"
}
}'const res = await fetch("https://app.stoqapp.com/api/v2/external/preorders/templates/confirmation", {
method: "PATCH",
headers: {
"X-Auth-Token": process.env.STOQ_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"email": {
"subject": "Your preorder is confirmed: {{order.name}}"
}
}),
});
const data = await res.json();import os
import requests
res = requests.patch(
"https://app.stoqapp.com/api/v2/external/preorders/templates/confirmation",
headers={"X-Auth-Token": os.environ["STOQ_API_KEY"]},
json={
"email": {
"subject": "Your preorder is confirmed: {{order.name}}"
}
},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.stoqapp.com/api/v2/external/preorders/templates/confirmation")
req = Net::HTTP::Patch.new(uri, "X-Auth-Token" => ENV["STOQ_API_KEY"], "Content-Type" => "application/json")
req.body = {
email: {
subject: "Your preorder is confirmed: {{order.name}}"
}
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body){
"key": "confirmation",
"locale": "en",
"email": {
"subject": "Your preorder is confirmed: {{order.name}}",
"preheader": "",
"heading": "Thanks for preordering from {{shop.name}}",
"body": "Your recent order {{order.name}} includes at least one preorder item. Please note the payment and shipping information below. Your preorder will be delivered as soon as possible.",
"footer": "Cancel order",
"button": {
"text": "View order",
"background_color": "#202223",
"text_color": "#ffffff",
"radius": 4
},
"colors": {
"background": "#f9f9f9",
"section": "#ffffff",
"text": "#202223"
},
"radius": 6,
"css": null,
"reviews": {
"enabled": false,
"count": 2,
"min_rating": 4,
"title": "What customers are saying"
},
"social": {
"facebook": null,
"instagram": "https://instagram.com/example_sneakers",
"pinterest": null,
"twitter": null,
"tiktok": null,
"whatsapp": null,
"youtube": null,
"icon_color": "#000000"
},
"klaviyo_flow_name": "Preorder confirmed (STOQ)",
"klaviyo_flow_verified": false,
"integration": null
},
"sms": {
"body": "Thanks for shopping with {{shop.name}}! Your preorder for {{first_product}} is confirmed. Est. shipping: {{shipping_timeline}}",
"klaviyo_flow_name": null,
"klaviyo_flow_verified": false,
"postscript_flow_verified": false,
"integration": null
}
}{
"errors": [
"Invalid API key"
],
"code": "auth_invalid",
"details": [
{
"code": "auth_invalid",
"message": "Invalid API key",
"path": null,
"value": null,
"expected": null
}
]
}{
"errors": [
"A request with this Idempotency-Key is still running"
],
"code": "idempotency_key_in_progress",
"details": [
{
"code": "idempotency_key_in_progress",
"message": "A request with this Idempotency-Key is still running",
"path": null,
"value": null,
"expected": null
}
]
}{
"errors": [
"widget.button.text_color must be a hex color"
],
"code": "invalid_params",
"details": [
{
"code": "invalid_params",
"message": "must be a hex color",
"path": "widget.button.text_color",
"value": "blue",
"expected": {
"type": "string"
}
}
]
}{
"errors": [
"Rate limit exceeded"
],
"code": "rate_limited",
"details": [
{
"code": "rate_limited",
"message": "Rate limit exceeded",
"path": null,
"value": null,
"expected": null
}
]
}