Skip to content

Update confirmation email

API v2 is in public beta: endpoints and fields can change before general availability. See the changelog

PATCH/preorders/templates/confirmation

Costs 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-Keystring

    A 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 (422 idempotency_key_reused); a retry while the first is still running gets 409 idempotency_key_in_progress. Keys are per store. Server errors and rate limits are not kept, so their retry runs.

Request body

  • emailobject

    Copy and design of the preorder confirmation email.

    Show 12 child attributesHide child attributes
    • subjectstring

      Subject of the preorder confirmation email.

    • preheaderstring

      Pre-header -- the preview line after the subject in the inbox.

    • headingstring

      Heading at the top of the email body.

    • bodystring

      Description -- the main body copy of the email.

    • footerstring

      Cancel order link -- the text of the link that lets customers cancel their preorder. Only shown while "Allow customers to cancel preorders" is on.

    • buttonobject
      Show 4 child attributesHide child attributes
      • textstring

        Button text on the email call to action.

      • background_colorstring

        Button -- Background colour of the email button. Hex.

      • text_colorstring

        Button -- Text colour of the email button. Hex.

      • radiusinteger

        Corner radius of the email button, in pixels.

    • colorsobject
      Show 3 child attributesHide child attributes
      • backgroundstring

        Colors -- Background of the email, around the content. Hex, e.g. "#F9F9F9".

      • sectionstring

        Colors -- Background of the content section of the email. Hex.

      • textstring

        Colors -- Text colour of the email. Hex.

    • radiusinteger

      Corner radius of the content section, in pixels.

    • cssstring

      Custom CSS added to the email. Applies to the standard email design. An empty string removes it.

    • reviewsobject
      Show 4 child attributesHide child attributes
      • enabledboolean

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

      • countinteger

        Number of reviews to show in the Judge.me reviews block, 1 to 3.

      • min_ratinginteger

        Only show reviews rated at least this many stars: 5, 4 or 3.

        One of 543
      • titlestring

        Section title for the Judge.me reviews block on the email, e.g. "What customers are saying".

    • socialobject
      Show 8 child attributesHide child attributes
      • facebookstring

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

      • instagramstring

        Instagram profile URL, without the https:// prefix. Saving a social link sets it on every notification template of the shop.

      • pintereststring

        Pinterest profile URL, without the https:// prefix. Saving a social link sets it on every notification template of the shop.

      • twitterstring

        X (Twitter) profile URL, without the https:// prefix. Saving a social link sets it on every notification template of the shop.

      • tiktokstring

        TikTok profile URL, without the https:// prefix. Saving a social link sets it on every notification template of the shop.

      • whatsappstring

        WhatsApp link, without the https:// prefix. Saving a social link sets it on every notification template of the shop.

      • youtubestring

        YouTube channel URL, without the https:// prefix. Saving a social link sets it on every notification template of the shop.

      • icon_colorstring

        Icon Color of the social icons: white (#FFFFFF) or black (#000000). Shared by every template.

        One of #FFFFFF#000000
    • klaviyo_flow_namestring

      Flow name to trigger in Klaviyo instead of sending the email here. Only used while the email platform is Klaviyo.

  • smsobject

    Text of the preorder confirmation SMS.

    Show 2 child attributesHide child attributes
    • bodystring

      SMS Body -- the text message sent instead of the email. Must keep its Liquid variables.

    • klaviyo_flow_namestring

      Flow name to trigger in Klaviyo instead of sending the SMS here. Only used while the SMS platform is Klaviyo.

  • localestring

    Language the translated fields are written in, such as 'fr' or 'pt-BR'. Omitted: the shop's default language. Untranslated fields ignore it.

Returns

  • keystring
    Example: confirmation
  • localestring
    Example: en
  • emailobject
    Show 14 child attributesHide child attributes
    • subjectstring
      Example: Your preorder is confirmed: {{order.name}}
    • preheadernull
    • headingstring
      Example: Thanks for preordering from {{shop.name}}
    • bodystring
      Example: Your recent order {{order.name}} includes at least one pr…
    • footerstring
      Example: Cancel order
    • buttonobject
      Show 4 child attributesHide child attributes
      • textstring
        Example: View order
      • background_colorstring
        Example: #202223
      • text_colorstring
        Example: #ffffff
      • radiusinteger
        Example: 4
    • colorsobject
      Show 3 child attributesHide child attributes
      • backgroundstring
        Example: #f9f9f9
      • sectionstring
        Example: #ffffff
      • textstring
        Example: #202223
    • radiusinteger
      Example: 6
    • cssstring, nullable
    • reviewsobject
      Show 4 child attributesHide child attributes
      • enabledboolean
        Example: false
      • countinteger
        Example: 2
      • min_ratinginteger
        Example: 4
      • titlestring
        Example: What customers are saying
    • socialobject
      Show 8 child attributesHide child attributes
      • facebooknull
      • instagramstring, nullable
        Example: https://instagram.com/example_sneakers
      • pinterestnull
      • twitternull
      • tiktoknull
      • whatsappnull
      • youtubenull
      • icon_colorstring
        Example: #000000
    • klaviyo_flow_namenull
      Example: Preorder confirmed (STOQ)
    • klaviyo_flow_verifiedboolean
      Example: false
    • integrationnull
  • smsobject
    Show 5 child attributesHide child attributes
    • bodystring
      Example: Thanks for shopping with {{shop.name}}! Your preorder for…
    • klaviyo_flow_namestring, nullable
    • klaviyo_flow_verifiedboolean
      Example: false
    • postscript_flow_verifiedboolean
      Example: false
    • integrationnull

Errors

404
not_found

The path is valid but nothing with that id exists in this store.

409
idempotency_key_in_progress

An earlier request with the same Idempotency-Key is still running. Wait, then resend the same request with the same key.

422
invalid_params

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

PATCH/preorders/templates/confirmation
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}}"
    }
  }'
Response
{
  "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
  }
}