Notifications

Notifications are transactional emails to inform customers and admins about events that have occurred in your store. They are triggered when a record is modified and specific conditions are met, rendered using Liquid templates, and delivered via Sendgrid. You can use your own account by activating the Sendgrid integration and providing your own API key.

Notification configurations are available at the /:notifications model endpoint, and you can see notifications the system has sent at the /notifications collection endpoint.

// List configurations of all standard and custom notifications
const notificationConfigs = await swell.get('/:notifications', { limit: 50 })
console.log(notificationConfigs) // { count: 31, page_count: 1, results: [...] }

// List all notifications that have been sent
const notifications = await swell.get('/notifications', { limit: 100 })
console.log(notifications) // { count: 1428, page_count: 15, results: [...] }

Swell has standard notifications for common ecommerce flows like order and shipping confirmations, subscription lifecycle events, abandoned carts, and gift card purchases. You can edit the templates for these, as well as create custom notifications to suit your particular needs.

The /:notifications model endpoint is used to configure all notifications, from what triggers the notification to the template that renders its content. Only name and model are required, however you will likely use most of the properties below when creating a fully functioning notification.

Name

Used to reference the notification in code. Must be slug format.

Label

The label is displayed on the list of notifications in the admin dashboard. It can be anything you like, but should succinctly identify the context and intention for the notification.

Method

Only email is supported at this time. Additional methods such as SMS will be available in future.

Model

Notifications can be triggered by records in any database collection. Whenever a record of the specified model is created, updated, or deleted, the value of conditions , new, and repeat will be evaluated to determine whether to send the notification.

Enabled

Controls whether the notification is currently active. This can also be toggled in the dashboard under Settings > Notifications.

Admin

Indicates whether notification is for admin users. If true, the notification will be sent to all admin users with notifications enabled. Additionally, it will be shown under the “Admin” heading in the dashboard under Settings > Notifications, rather than the associated model name.

Contact

The path on the record where the intended recipient’s email is stored. Use dot notation to reference nested fields. This field is ignored if admin is true.

From, CC, BCC, Replyto

By default, email notifications will appear to be from your store name and support email as specified in Settings > General. Use these fields if you wish to specify the from, CC, BCC, or reply-to addresses. You can use template operators for inserting variables and logic, for example dynamically setting a reply-to email using a value from the record.

Subject

The subject line for the email. You can use template operators for inserting variables and logic.

Conditions

Conditions can define a set of criteria that must be met for a notification to be sent. The syntax for this object is the same as the `where` filter query, and supports comparison, evaluation, and logical operators. Setting conditions: false means the notification will never be triggered automatically.

// Password reset
...
"conditions": {
  // The body of the API request for the record
  "$data": {
    // contains a $notify property with the value "password-reset"
    "$notify": "password-reset",
    // contains a password_reset_url property with any value
    "password_reset_url": {
      "$exists": true
    }
  }
},
...

// Subscription invoice
...
"conditions": {
  // The body of the API request for the record
  // contains a $notify property with the value "invoice"
  "$data": {
    "$notify": "invoice"
  },
  // The grand_total field on the record is greater than 0
  "grand_total": {
    "$gt": 0
  }
},
...

// Giftcard fulfillment
...
"conditions": {
  // The send_email field on the record is not null
  "send_email": {
    "$ne": null
  }
},
...

Repeat

When a record associated with a notification is modified, Swell first checks whether the notification has been sent before. Depending on the notification’s purpose, it should be sent only once, or every time the conditions are met. If repeat is true, it will be triggered every time the conditions are met for a given record. If repeat is false or not specified, it will only be triggered once per record.

New

When true, the notification conditions will only be evaluated when a record is created, and repeat will have no effect.

Delay

If you want the system to wait before sending a notification, you can specify a delay time in minutes.

Fields

A list of content fields which can be edited by admin users in the dashboard. These values are available in the template context along with the record object which triggered the notification. You can also utilize record fields within content fields, as shown in the example below.

// Order confirmation
...
"fields": [
  {
    "id": "prep_note",
    "label": "Preparation note",
    "type": "long_text",
    "default": "We're getting your order ready and we'll notify you when it's {% if shipping.pickup %}available for pickup{% else %}shipped{% endif %}."
  },
]
...

// Shipment confirmation
...
"fields": [
  {
    "id": "shipped_note",
    "label": "Shipped note",
    "type": "short_text",
    "default": "Your shipment is on the way"
  },
]
...

// Password reset
...
"fields": [
  {
    "id": "reset_note",
    "label": "Reset note",
    "type": "long_text",
    "default": "Use the following link to reset your password for {{ store.name }}. If you didn't request this action, you may safely ignore this email."
  },
]
...

Content

The represents the template for the email body, either as plain text or HTML. If creating a notification via API, this must be provided as a string. Once created, Swell stores this as a file.

Query

When a notification is triggered, the associated record is fetched with a GET request. The query object can contain query parameters to modify this request, which is useful if you need to expand other objects referenced in the record.

// Subscription invoice
...
"query": {
  "expand": [
    // Customer account referenced in the subscription
    "account",
    // Product and variant referenced in the subscription
    "product",
    "variant",
    // Products and variants referenced in the subscription items
    "items.product", 
    "items.variant"
  ]
},
...

// Shipment confirmation
...
"query": {
  "expand": [
    // Customer account referenced in the order
    "account",
    // Shipments referenced in the order, 
    // plus products and variants referenced in the shipment items
    "shipments",
    "shipments.items.product",
    "shipments.items.variant"
  ]
},
...

// Abandoned cart recovery
...
"query": {
  "expand": [
    // Customer account referenced in the cart
    "account",
    // Products, variants, and bundles referenced in the subscription items
    "items.product",
    "items.variant",
    "items.bundle_items.product",
    "items.bundle_items.variant"
  ]
},
...

Sample

These are dummy data values used in the dashboard when previewing templates. The object structure should match the record as defined by the target model, so that the field paths for the template variables are the same.

$Locale

Swell supports multiple languages in notifications, and this object contains field values for each locale, if these have been set.

Notification templates are used to render the message content, either in plain text or HTML. Templates support Liquid syntax, with some additional operators unique to Swell.

Objects and variables are rendered when enclosed in double curly braces {{ and }}. Nested values can be accessed using dot notation.

Record data

Fields on the record that triggered the notification can be accessed using the field ID, without any prefix. For example, if the notification is associated with the orders model, the shipping city could be rendered with {{ shipping.city }}.

Content fields

If the notification configuration has fields defined, values can be accessed using content.<field_id>. For example, if the notification has a field with the ID welcome_note, the value could be rendered in the template with {{ content.welcome_note }}.

Store settings

The store object contains settings for the store, such as name, contact email, logo, and locales. These values can be accessed using store.<field_id>.

Liquid has various tags and operators for working with data in templates. For a more detailed overview, see this introduction to Liquid guide.

Assigning variables

Variables can be assigned anywhere in your template (including loops) to make the code more readable.

{% assign logo_width = store.logo_width %}

Controlling flow

The tags if, unless, elsif, else, case, and when can be used for conditional rendering.

// Display the store logo if it exists, otherwise show the store name
{% if store.logo.file.url %}
  {% if store.logo_width > 0 %}
    {% assign logo_width = store.logo_width %}
  {% else %}
    {% assign logo_width = 200 %}
  {% endif %}
  {% assign logo_width_img = logo_width | times: 2 %}
  <img src="{{ store.logo | img_url: 'padded=true&width=' | append: logo_width_img }}" aria-hidden="true" width="{{ logo_width }}">
{% else %}
  <div>{{ store.name }}</div>
{% endif %}

Iterating over arrays

The for tag can iterate over arrays, hashes, and ranges of integers. Many data structures in Swell involve arrays, so it’s likely you’ll need to loop through items to render certain content.

{% for item in shipment.items %}
  {{ item.description }}
{% endfor %}

Formatting output

Filters can alter the rendered output and apply consistent formatting. Some filters take parameters as an argument.

{{ date_created | date: '%b %d, %Y' }}

Notifications can be viewed and tested directly from the Swell dashboard, in Settings > Notifications. You can also send test notifications using the backend API using one of the approaches below.

The notification configuration supports sample data objects to use when testing, while live data from actual events is utilized when the system automatically triggers notifications. The sample data object must match the structure of the model the notification is associated with.

Manually trigger a notification via API

To trigger a notification for testing purposes and override certain values, you can make a POST request to the /notifications endpoint with the following properties.

{
  "template": "orders.receipt", // Model and notification name
  "record_id": "62b9f39d8b9a9a00133b7784", // ID of record to send notification for
  "to": "person@dmail.com", // Optional recipient override
  "from": "admin@coolstore.com", // Optional sender override
  "subject": "TEST for order {{ number }}", // Optional subject override
  "test": true // Optional flag to use sample data
}

Update a record and trigger notification via API

It’s often that case that a notification is triggered by making a change to an existing record. Using the $notify property, you can update a record and trigger an associated notification with a single API request.

// Update record and send notification
await request.put('/subscriptions/{id}', {
  id: "145000197b2bbf62b1e30767",
  ...updatedFieldData,
  $notify: "my-subscription-notification-name",
});

// Update record, override grand_total field in template, and send notification
await request.put('/subscriptions/{id}', {
  id: "145000197b2bbf62b1e30767",
  ...updatedFieldData,
  $notify: {
    id: "my-subscription-notification-name",
    data: {
      grand_total: 999999,
    }
  }  
});