🧩Build custom templates

A template is a small recipe that tells Shippified how to read one kind of message. Shippified ships with built-in templates for common Discord monitor bots and for Target, Walmart, Amazon and Best Buy emails. When a message comes from something those don't cover (a new checkout bot, a smaller retailer, a changed email layout), you build your own template from a real sample and Shippified reads it from then on.

You don't need to be a programmer. Most templates only need a few field names copied from the message. For email you'll usually write two or three short patterns, and this page includes cheat sheets for those.

How templates work

Every template has two parts:

• Detection rules answer "is this message one of mine?" Each rule looks at one spot in the message and checks it, for example "the embed footer contains Stellar" or "the email's From line contains @mail.northwind.example". All the rules must pass for the template to be used.

• Field mappings (the Extraction map) answer "where is each order detail?" Each mapping points at one spot in the message and says what it is: the order number, the item name, the total, and so on.

Both use the same three ways of pointing at a spot in a message. These are called selectors:

Which template wins

When a message arrives, Shippified tries templates in this order and uses the first one whose rules all pass:

1. Webhooks only: the template pinned to the bot that received it (its Parser template in Links → Webhooks). A pinned template is always used, whether or not its rules pass.

2. Your custom templates of the same kind (webhook or email), newest first. Your templates on the library page lists them in this order.

3. Built-in templates.

After the chosen template has done its work, a generic pass fills in anything still missing, such as the quantity, a tracking number or the carrier. You only need to map what the generic pass can't find by itself.

For email, an inbox can be limited to chosen templates with Templates this source parses against in its settings (see Connect an email inbox). The inbox then tries only those templates, in the order you set.

Before you start

• Get a real sample of the message you want to read:

  • Discord bot: the JSON the bot posts. You can capture an embed straight from Discord with the embed copier, then load it with Load from Discord. You can also copy the payload from the bot's activity log in Links → Webhooks (see Connect Discord monitor bots).

  • Email: the full raw email. In Gmail, open the email, click the three-dot menu and choose Show original. In other mail apps, look for "View source" or "Show original". At the very least you need the From: and Subject: lines, then an empty line, then the body.

• One sample per template. If a retailer's "order placed" and "order shipped" emails look different, build one template for each.

The Template library

Click Templates in the sidebar.

Below the buttons are two sections:

• Your templates (tagged Workspace): your custom templates of the selected kind, with a count such as 1 custom webhook. Each card shows the template name, its event type, how many rules and mappings it has, and up to six of its mappings (target and selector). If there are more, the card shows +N more. Click the pencil (Edit template) to open it in the builder, or the bin (Delete template) to delete it. With no custom templates yet, you'll see No custom templates yet and a Build your first button.

• Built-in (tagged Ready): the templates Shippified maintains, with a count such as 3 preconfigured, each marked Live. You can't edit these. To change how one of these messages is read, build a custom template for it: custom templates are tried before built-ins.

Tour of the builder

Click Build template. The builder title reads Webhook parser loadout or Email parser loadout, and three step markers at the top right light up as you go: 01 Paste sample, 02 Mark fields, 03 Save. Library (top left) goes back without saving.

The left column holds the template's settings, its detection rules and the sample. The Extraction map column holds the field mappings and the In production panel.

The builder opens with a starter sample and two starter mappings so you can see how everything fits together, and, for a webhook template, one starter rule. A new email template starts with no rules, so it won't match any mail until you add a sender filter or a rule (see Filter by sender). Replace the starters with your own.

Template name

What the template is called in the library, in a bot's Parser template list and on each order it reads. Up to 120 characters. If you leave it empty, it's saved as "Custom Template". Use something you'll recognise, such as "Stellar AIO checkout" or "Northwind: shipped".

Source

• Webhook JSON: for Discord bot messages.

• Email HTML / text: for emails.

The builder starts with the kind selected on the library page.

Event type

What kind of event every message this template reads represents. This decides the order's status.

With Other, Shippified reads the message's wording to decide. For email it looks at the subject first, then the start of the body. It recognises phrases like "canceled", "was delivered", "out for delivery", "shipped", "on its way", "successful checkout" and "thanks for your order". If nothing matches, the event is unknown and the order stays Ordered. You can also map the eventType field (see the Target fields table).

Sample payload

The big text box is the reference message that your rules and mappings are tested against. Everything in the builder updates live as you type in it.

• Webhook: paste the JSON your bot posts. It normally looks like { "embeds": [ { ... } ] }. If what you paste isn't valid JSON, it's treated as plain text, so JSON path selectors won't find anything.

• Email: paste the raw email including its headers. Shippified reads it exactly as it reads real mail.

Load from Discord (webhook templates only) opens a Submitted samples list of embeds you've captured with the embed copier, each with its name, the server it came from and when it was captured. Click one to drop it into the sample. If you haven't captured any yet, the list explains how: add the embed-copier bot in Discord, paste your submission URL with /setshippified, then run /copy <message_link> on an embed.

The sample is saved with the template, so you can come back later and test changes against it.

Detection rules

Click Add rule to add a rule. Each rule is numbered (Rule 1, Rule 2, …) and has these parts:

Remove a rule with its bin icon. A rule with an empty selector is dropped when you save.

Regular expressions are checked as you type. A pattern that isn't valid gets a red border and a "Not a valid regex" error under it, and the template can't be saved until it's fixed (see Troubleshooting).

As you edit, each rule shows a badge: matched when it passes against the sample, no match when it doesn't. Under it, Resolved against sample: shows the exact text the selector found (the first 120 characters). If that's not what you expected, fix the selector before you worry about the operator.

Operators

If the selector finds nothing, the rule fails.

Case sensitivity

Rules made in the builder ignore upper and lower case: stellar, Stellar and STELLAR all match each other. This applies to equals, contains, regex and to regex selectors. Mapping selectors ignore case too, and so do Embed field name lookups. (Rules created through the Templates API can be made case-sensitive. The builder keeps that setting when you edit the rule.)

Scope (email only)

An email has two parts Shippified can look at:

Filter by sender (email only)

Above the rule list, email templates have a Filter by sender box: "The template only applies when the email's From: header contains this, e.g. the retailer's sending domain. Leave empty only if another rule below narrows it down." Type part of the sender's address, such as @mail.northwind.example, and Shippified adds a hidden rule that checks the From line for it. Clear the box to remove it. It isn't shown in the rule list and doesn't take a rule number.

While the box is empty and your sample has a From: line, a button under it offers that sender's domain, for example Use the sample's sender: @oe.target.com. Click it to fill the box.

An email template with no sender filter and no rules shows an amber warning: "No rules yet, so this email template won't match any mail." It goes away once you set Filter by sender or add a rule.

Field mappings (the Extraction map)

The Extraction map heading counts your mappings (for example 2 mappings). Each mapping has:

1. A target field: which order detail this is (see the table below).

2. For the custom target only, a custom key box: the name to store the value under.

3. A selector type: Embed field name, JSON path or Regex capture.

4. The selector itself (placeholder: "Field name or regex").

5. An Extracted line showing what the mapping finds in the sample. "No preview" means it found nothing.

Click Add mapping to add one, and the bin icon (Remove mapping) to remove one. Every change refreshes the extracted values, and Preview refreshes them all at once.

Target fields

How mappings behave

• Fallbacks: if you add several mappings for the same target, the first one that finds a value wins. Put the most specific first.

• Values are cleaned: HTML tags are removed,  , & and similar codes become normal characters, Discord formatting (||spoiler||, **bold**, __underline__ and backticks) is stripped, and extra spaces are squashed. <strong>$49.99</strong> becomes $49.99.

• Regex mappings search the email's HTML first, then its plain-text version, then the header lines. For webhooks they search the embed's text (see below).

• Embed field name mappings look for the embed field with that name. If there's no such field, they look for a Name: value line (also Name# value or Name- value) in the text. The value runs to the end of the line or the first comma or |.

What a webhook's "text" is

For Embed field name fallbacks and Regex capture on webhooks, Shippified joins the message into lines of text in this order: the bot's username, the message content, then for each embed its author name, title, description, footer text, and each field as Name: value.

The In production panel

Under the mappings, the In production panel runs the real parser on your sample, exactly as live messages are read, with your unsaved draft tried first. It never creates or changes an order, so you can experiment freely.

The headline tells you what would happen:

Underneath is the order it would create: Status, Event, Store, Order #, Item, Total, Qty and Tracking. A dash means that detail is missing. Store shows the retailer's name (for example Target). This includes values found by the generic pass, so it's the best check of the finished result.

If the panel disappears while you type, one of your patterns isn't a valid regular expression yet. It comes back once the pattern is valid.

Save the template

Click Save template (Save changes when editing). Rules and mappings with an empty selector are dropped. While any regular expression is invalid, the button can't be clicked and "Fix the regex errors marked above before saving." appears above it (see Troubleshooting). After saving you go back to the library, and the template applies to new messages straight away.

For a webhook template, one more step is usually worth it: go to Links → Webhooks, edit the bot and choose your template (listed as "name · custom") under Parser template. The bot then always uses it. See Connect Discord monitor bots.

Worked example: a Discord bot Shippified doesn't recognise

The problem: you've connected a checkout bot called Lumen. Its orders arrive, but as "Unparsed order" or with the wrong details. This is what its webhook sends:

{
  "username": "Lumen",
  "embeds": [{
    "title": "Successful Checkout",
    "author": { "name": "Lumen Monitors" },
    "thumbnail": { "url": "https://cdn.example.com/p/earbuds.png" },
    "fields": [
      { "name": "Site", "value": "Target" },
      { "name": "Product", "value": "**Wireless Earbuds Pro**" },
      { "name": "Price", "value": "$129.99" },
      { "name": "Qty", "value": "1" },
      { "name": "Order", "value": "||912000111222||" },
      { "name": "Profile", "value": "Main 01" }
    ],
    "footer": { "text": "Lumen Monitors v3.2" }
  }]
}

1. Open the builder

   Go to Templates, make sure Webhook is selected, and click Build template. Source is already Webhook JSON.

2. Name it and choose the event

   Set Template name to Lumen checkout. This bot only posts checkouts, so set Event type to Order placed.

3. Add the sample

   Select everything in Sample payload and paste the JSON above, or click Load from Discord and pick the embed you captured.

4. Write the detection rules

   Change the starter Rule 1 to check the footer for the bot's name, then click Add rule for a second check on the title:

   • 1 — JSON path — embeds[0].footer.text — contains — Lumen

   • 2 — JSON path — embeds[0].title — regex — success(ful)? checkout

   Both should show matched, with Resolved against sample: Lumen Monitors v3.2 and Successful Checkout.

5. Map the fields

   Edit the two starter mappings and add the rest:

   • orderNumber — Embed field name — Order

   • itemSummary — Embed field name — Product

   • total — Embed field name — Price

   • store — Embed field name — Site

   • customerName — Embed field name — Profile

   • custom (key bot) — JSON path — username

   Check each Extracted value. The spoiler bars around the order number and the bold markers around the product name are gone: 912000111222 and Wireless Earbuds Pro. You don't need quantity or imageUrl: the generic pass reads the Qty field and the thumbnail.

6. Check In production

   The panel should read This template handles it, with Status ordered, Event Order placed, Store Target, the order number, item and $129.99.

7. Save and pin

   Click Save template. Then pin it: Links → Webhooks, edit the Lumen bot, set Parser template to "Lumen checkout · custom". Finally, click Re-run parsing on the Templates page to fix the orders Lumen already sent.

Worked example: an email from a retailer Shippified doesn't support

The problem: you buy from Northwind Outfitters. Their emails either don't show up as orders or show up as "Unparsed order". Here's the raw order confirmation (from Show original):

From: Northwind Outfitters <orders@mail.northwind.example>
To: you@example.com
Subject: Your Northwind order NW-448812 is confirmed

<html><body>
<h1>Thanks for your order!</h1>
<p>Order number: <strong>NW-448812</strong></p>
<p>Item: <strong>Trail Runner 2 Jacket - Size M</strong></p>
<p>Quantity: 2</p>
<p>Order total: <strong>$189.98</strong></p>
</body></html>

1. Open the email builder

   Go to Templates, select Email and click Build template. Check that Source says Email HTML / text.

2. Name it and choose the event

   Template name: Northwind: placed. Event type: Order placed.

3. Paste the sample

   Replace the starter sample with the whole raw email, headers included.

4. Filter by sender

   In Filter by sender, type @mail.northwind.example, or click Use the sample's sender: @mail.northwind.example under the box. The no-rules warning goes away.

5. Add a subject rule

   Click Add rule and fill it in:

   • Regex capture — Subject:\s*([^\n]+) — contains — is confirmed — header

   Resolved against sample: should show the whole subject line, and the badge matched. This rule stops the template from also claiming Northwind's shipping emails.

6. Map the fields with regex

   Delete the two starter mappings (they're written for the starter sample) and add:

   • orderNumber — Regex capture — Order number:\s*(NW-\d+)

   • itemSummary — Regex capture — Item:\s*([^\n<]+)

   • total — Regex capture — Order total:\s*(\$[\d,.]+)

   The HTML has <strong> tags between the labels and the values, so these patterns don't match the raw HTML. That's fine: Shippified then tries the plain-text version, where the email reads Order number: NW-448812. The Extracted values should be NW-448812, Trail Runner 2 Jacket - Size M and $189.98.

7. Check In production and save

   The panel should read This template handles it, with Qty 2 (found by the generic pass from "Quantity: 2") and no Store, because Northwind isn't a recognised retailer. Click Save template.

For the shipping email, build a second template the same way: Event type Order shipped, the same sender filter, a subject rule with contains has shipped, and mappings for orderNumber and trackingNumber (for example Tracking number:\s*([A-Z0-9]+)). Because both emails carry the same order number, the shipping email updates the order from the first one: it moves to Shipped, gets the tracking number, and its carrier is detected automatically.

JSON path cheat sheet

A JSON path is a list of names separated by dots, describing how to walk into the webhook data. [0] means "the first item in a list", [1] the second, and so on.

Rules to remember:

• A leading $. is allowed and ignored: $.embeds[0].title works too.

• Counting starts at 0.

• Each list position must follow a name (fields[2]). Two positions in a row, such as a[0][1], aren't supported, and nor are wildcards like [*].

• Names are matched exactly, including case: Title won't find title.

• JSON paths only work on webhook templates. In an email template they never find anything.

Regex cheat sheet

A regular expression (regex) is a pattern for finding text. Shippified uses the part inside the first pair of round brackets ( ), called a capture group. If there are no brackets, it uses the whole match.

Ready-made patterns:

Things Shippified does for you, and gotchas:

• Case is always ignored, so order matches Order.

• . also matches line breaks. That makes .* or .+ swallow the rest of the email. Use [^\n]+ or [^\n<]+ instead.

• ^ means the very start of the text, not the start of each line. In the header, the first line is From:, so ^Subject: never matches. Write Subject:\s*… or (?:^|\n)Subject:\s*….

• To match $ . ( ) [ ] * + ? | \ literally, put a backslash before them: \$49\.99.

• If a pattern doesn't match the raw HTML, write it against how the email reads (Label: value). Shippified tries the plain-text version automatically.

Edit a template

Click the pencil on its card. The builder opens with Editing · name at the top. Change what you need and click Save changes. Changes apply to new messages right away. Editing doesn't move a template in the newest-first order: it keeps its original place. Settings the builder doesn't show, such as a fixed store set through the API, are kept. Cancel or Library leaves without saving.

Apply changes to existing orders

Shippified keeps every email and webhook it receives. After you add or change templates, click Re-run parsing on the library page to rebuild your existing orders from those stored messages. The button shows Re-parsing… while it works, then a summary such as "Re-parsed 42 orders: 5 updated, 1 merged", plus "N removed as non-order mail" if any were removed. With nothing to rebuild, it says "No orders with stored messages yet — new mail will be re-parseable."

What re-running does:

• Rebuilds each order from its stored messages, using your current templates, bot pins and inbox template lists.

• Keeps what didn't come from messages: sale prices, fields you filled in by hand, and delivery dates, addresses, weight and dimensions from carrier tracking. A delivery confirmed by the carrier stays delivered.

• Merges orders that now share an order number.

• Removes orders whose messages now all look like non-order mail, unless you've edited them or entered a sale price.

• Skips orders with no stored messages, such as orders you added by hand.

Troubleshooting

Related