Skip to main content

Notification Architecture Overview

This document gives an overview of the notification architecture and how it works.

Introduction​

Medusa provides a Notification API to mainly handle sending and resending notifications when an event occurs. For example, sending an email to the customer when they place an order.

The Notification architecture is made up of two main components: the Notification Provider and the Notification. Simply put, the Notification Provider handles the sending and resending of a Notification.

Notification Provider​

A Notification Provider is a provider that handles sending and resending of notifications. You can either create and integrate your own provider or install a Notification Provider through a third-party plugin.

An example of a notification provider is SendGrid. When an order is placed, the SendGrid plugin sends an email to the customer.

How Notification Provider is Created​

A Notification Provider is essentially a Medusa Service with a unique identifier, and it extends the NotificationServiceCopy to Clipboard provided by the medusa-interfacesCopy to Clipboard package. It can be created as part of a Plugin, or it can be created just as a Service file in your Medusa backend.

As a developer, you mainly work with the Notification Provider when integrating a third-party service that handles notifications in Medusa.

When you run your Medusa backend, the Notification Provider is registered on your backend if it isn’t already. This means that it will be inserted into the notification_providerCopy to Clipboard table in your database.

NotificationProvider Entity Overview​

The NotificationProviderCopy to Clipboard entity only has 2 attributes: idCopy to Clipboard and is_installedCopy to Clipboard.

idCopy to Clipboard is the value of the static property identifierCopy to Clipboard defined inside the notification Service class.

is_installedCopy to Clipboard indicates whether the Notification Provider is installed or not. When you install a Notification Provider, the value of this attribute is trueCopy to Clipboard.

If you installed a Notification provider and then removed the Service files or plugin that registered the Notification Provider, the Notification Provider remains in your database, but the value of the is_installedCopy to Clipboard field changes to falseCopy to Clipboard.

Notification​

A notification is a form of an alert sent to the customers or users to inform them of an action that has occurred. For example, if an order is placed, the notification, in this case, can be an email that confirms their order and lists the order details.

Notifications can take on other forms such as an SMS or a Slack message.

How Notification is Created​

Notifications are created in the NotificationServiceCopy to Clipboard class in Medusa’s core after the Notification has been handled by the Notification Provider.

The data and additional details that the Notification Provider returns to the NotificationServiceCopy to Clipboard is used to fill some of the attributes of the Notification in the database.

A Notification also represents a resent notification. So, when a notification is resent, a new one is created that references the original Notification as a parent. This Notification is also created by the NotificationServiceCopy to Clipboard class.

Notification Entity Overview​

The two most important properties in the NotificationCopy to Clipboard entity are the toCopy to Clipboard and dataCopy to Clipboard properties.

The toCopy to Clipboard property is a string that represents the receiver of the Notification. For example, if the Notification was sent to an email address, the toCopy to Clipboard property holds the email address the Notification was sent to.

The toCopy to Clipboard property can alternatively be a phone number or a chat username. It depends on the Notification Provider and how it sends the Notification.

The dataCopy to Clipboard property is an object that holds all the data necessary to send the Notification. For example, in the case of an order confirmation Notification, it can hold data related to the order.

The dataCopy to Clipboard property is useful when a notification is resent later. The same dataCopy to Clipboard can be used to resend the notification.

In the case of resent notifications, the resent notification has a parent_idCopy to Clipboard set to the ID of the original Notification. The value of the parent_idCopy to Clipboard property in the original Notification is nullCopy to Clipboard.

The NotificationCopy to Clipboard entity has some properties that determine the context of this Notification. This includes the event_nameCopy to Clipboard property which is the event that triggered the sending of this notification.

Additionally, the resource_typeCopy to Clipboard property is used to determine what resource this event is associated with. For example, if the event_nameCopy to Clipboard is order.placedCopy to Clipboard, the resource_typeCopy to Clipboard is orderCopy to Clipboard.

You can also access the specific resource using the resource_idCopy to Clipboard property, which is the ID of the resource. So, in case of the order.placedCopy to Clipboard event, the resource_idCopy to Clipboard is the ID of the order that was created.

The NotificationCopy to Clipboard entity also includes properties related to the receiver of the Notification. In case the receiver is a customer, the customer_idCopy to Clipboard property is used to identify which customer.

Automating Flows with Notifications​

With Medusa you can create notifications as a reaction to a wide spectrum of events, allowing you to automate communication and processes.

An example of a flow that can be implemented using Medusa's Notification API is automated return flows:

  • A customer requests a return by sending a POSTCopy to Clipboard request to the /store/returnsCopy to Clipboard endpoint.
  • The Notification Provider listens to the order.return_requestedCopy to Clipboard event and sends an email to the customer with a return invoice and return label generated by the Fulfillment Provider.
  • The customer returns the items triggering the return.recievedCopy to Clipboard event.
  • The Notification Provider listens to the return.receivedCopy to Clipboard event and sends an email to the customer with confirmation that their items have been received and that a refund has been issued.

See Also​