Skip to content
STOQDevelopers
Open STOQ

Templates

View as Markdown

Update a template

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

PATCH/back_in_stock/templates/{key}

Costs 2 rate-limit points · Rate limits

Update one back-in-stock notification's email and SMS copy. key is "signup_thank_you", "restock_alert" or "reminder". The body is the GET shape: email{subject, preheader, heading, body, footer, button{...}, colors{...}, radius, css, html{enabled, template}, reviews{...}, social{...}, unsubscribe_text, klaviyo_flow_name} and sms{body, link_destination, klaviyo_flow_name}. An optional body locale ("fr", "pt-BR") writes the copy in that language only; omit it for the shop default. Colours, switches and other untranslated fields ignore it. Turning a notification on or off, and its timing, is PATCH /back_in_stock/notification_settings/:key.

Deep partial: absent fields are unchanged; unknown or read-only keys are rejected (signup_thank_you has no email.button.destination or sms.link_destination). Errors are 422 keyed "template.<path>"; nothing is saved when any field fails. Rejects HTML except in email.html.template and email.css, and runs Template validations and callbacks. Colours, corner radii and the Judge.me reviews block are shared by the restock alert and the reminder; social links, the icon colour and email.unsubscribe_text by every template of the shop.

Also searched asedit back in stock templatechange restock emailchange restock smsupdate back in stock reminder copylocalize back in stock templateadd social links to emailsocial media icons in restock emailedit thank you for signing up emaildisable custom html templateuse standard email templateturn off html email template

Path parameters

  • keystringRequired

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
    Show 14 child attributesHide child attributes
    • subjectstring

      Subject of the email. Takes the editor variables, e.g. {{product.title_incl_variant}} or {{shop.name}} (get_bis_template lists them all); a bare {{product}} is not a variable.

    • preheaderstring

      Pre-header -- the preview line after the subject in the inbox. Takes the editor variables, e.g. {{product.title_incl_variant}} or {{shop.name}} (get_bis_template lists them all); a bare {{product}} is not a variable.

    • headingstring

      Heading at the top of the email body. Takes the editor variables, e.g. {{product.title_incl_variant}} or {{shop.name}} (get_bis_template lists them all); a bare {{product}} is not a variable.

    • bodystring

      Description -- the main body copy of the email. Takes the editor variables, e.g. {{product.title_incl_variant}} or {{shop.name}} (get_bis_template lists them all); a bare {{product}} is not a variable.

    • footerstring

      Footer line at the bottom of the email.

    • buttonobject
      Show 5 child attributesHide child attributes
      • textstring

        Button text on the email.

      • destinationstring

        "Take customer to": where the email button lands, the checkout or the product page. Not on signup_thank_you.

        One of checkoutproduct
      • 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. Saving it sets it on the restock alert and the reminder alike.

    • colorsobject
      Show 3 child attributesHide child attributes
      • backgroundstring

        Colors -- Background of the email. Hex, e.g. "#FFFFFF".

      • sectionstring

        Colors -- Background of the content section of the email. Hex. Saving it sets it on the restock alert and the reminder alike.

      • textstring

        Colors -- Text colour of the email. Hex.

    • radiusinteger

      Corner radius of the content section, in pixels. Saving it sets it on the restock alert and the reminder alike.

    • cssstring

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

    • htmlobject
      Show 2 child attributesHide child attributes
      • enabledboolean

        The "Use HTML template" switch: true sends email.html.template, false the standard STOQ email.

      • templatestring

        The custom HTML email (Custom HTML tab). Sent instead of the standard email while email.html.enabled is true. Takes the same {{ }} variables as the editor. Paid plans only.

    • reviewsobject
      Show 4 child attributesHide child attributes
      • enabledboolean

        Show product reviews: adds the product's Judge.me star rating and top reviews to the email. Paid plans only; shows only while Judge.me is connected (Settings > Integrations). Saving it sets it on the restock alert and the reminder alike.

      • countinteger

        Number of reviews to show in the Judge.me reviews block, 1 to 3. Saving it sets it on the restock alert and the reminder alike.

      • min_ratinginteger

        Only show reviews rated at least this many stars: 5, 4 or 3. Saving it sets it on the restock alert and the reminder alike.

        One of 543
      • titlestring

        Section title of the Judge.me reviews block, e.g. "What customers are saying". Saving it sets it on the restock alert and the reminder alike.

    • socialobject
      Show 8 child attributesHide child attributes
      • facebookstring

        Facebook profile URL, without the https:// prefix. Shows as an icon in the email. Saving it sets it on every notification template of the shop.

      • instagramstring

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

      • pintereststring

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

      • twitterstring

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

      • tiktokstring

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

      • whatsappstring

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

      • youtubestring

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

      • icon_colorstring

        Icon Color of the social icons: white (#FFFFFF) or black (#000000). Saving it sets it on every notification template of the shop.

        One of #FFFFFF#000000
    • unsubscribe_textstring

      Text of the unsubscribe link at the bottom of the email. Saving it sets it on every notification template of the shop.

    • klaviyo_flow_namestring

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

  • smsobject
    Show 3 child attributesHide child attributes
    • bodystring

      SMS Body -- the text message sent instead of the email. Takes the editor variables, e.g. {{product.title_incl_variant}} or {{shop.name}} (get_bis_template lists them all); a bare {{product}} is not a variable.

    • link_destinationstring

      "Link takes customer to": where the SMS link lands, the checkout or the product page. Not on signup_thank_you.

      One of checkoutproduct
    • 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.

Errors

401

Missing or invalid X-Auth-Token.

404

The resource does not exist for this shop, or the action path is not registered.

409

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

422

Invalid fields: one details entry per field error, its path the canonical section path. Nothing was saved.

429

Rate limited: cost-weighted per token (read 1, write 2; 360 points / 60s). Check Retry-After.

Every error has the same shape: see Errors.

PATCH/back_in_stock/templates/{key}
curl -X PATCH "https://app.stoqapp.com/api/v2/external/back_in_stock/templates/{key}" \
  -H "X-Auth-Token: $STOQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": {
      "subject": "string",
      "preheader": "string",
      "heading": "string",
      "body": "string",
      "footer": "string",
      "button": {
        "text": "Preorder now",
        "destination": "checkout",
        "background_color": "#1A1A1A",
        "text_color": "#1A1A1A",
        "radius": 0
      },
      "colors": {
        "background": "string",
        "section": "string",
        "text": "Preorder now"
      },
      "radius": 0,
      "css": "string",
      "html": {
        "enabled": true,
        "template": "string"
      },
      "reviews": {
        "enabled": true,
        "count": 5,
        "min_rating": 5,
        "title": "string"
      },
      "social": {
        "facebook": "string",
        "instagram": "string",
        "pinterest": "string",
        "twitter": "string",
        "tiktok": "string",
        "whatsapp": "string",
        "youtube": "string",
        "icon_color": "#FFFFFF"
      },
      "unsubscribe_text": "Preorder now",
      "klaviyo_flow_name": "Summer Sneaker Drop"
    },
    "sms": {
      "body": "string",
      "link_destination": "checkout",
      "klaviyo_flow_name": "Summer Sneaker Drop"
    },
    "locale": "fr"
  }'
Response
No body