Notifications are sent to users when an event occurs in the system related to them. Notifications are sent to users via email.

Notification Types

Notifications are sent for the following events:

Event	Description	Default Recipient
INVOICE_APPROVAL_NEEDED	An invoice is created and needs approval	The designated approver(s) of the invoice
INVOICE_APPROVED	An invoice is approved	Invoice Creator
INVOICE_REJECTED	An invoice is rejected	Invoice Creator
INVOICE_SCHEDULED	An invoice is scheduled for payment	None
INVOICE_PENDING	An invoice payment has initiated	None
INVOICE_PAID	An invoice is marked as paid	Invoice Creator
INVOICE_CANCELED	An invoice is marked as canceled	None
INVOICE_CREATED	A new invoice is created by any means (email, upload, etc.)	None
INVOICE_EMAILED	A new invoice is emailed to the email inbox	None
INVOICE_FAILED	An invoice payment failed	Invoice Creator

Changing Notification Recipients

The default recipients for each notification type can be changed by updating the policy for that notification type. You can also do this using the Admin Dashboard

For example, to change the recipients of the INVOICE_APPROVED notification type to always notify any user with the role admin or bookkeeper

POST

/entity/:entityId/notification-policy/:notificationType

1 from mercoa import Mercoa
2 from mercoa.entity_types import NotificationPolicyRequest
3 
4 client = Mercoa(
5     token="YOUR_TOKEN",
6 )
7 client.entity.notification_policy.update(
8     entity_id="ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
9     notification_type="INVOICE_APPROVED",
10     request=NotificationPolicyRequest(
11         disabled=False,
12         additional_roles=["admin", "bookkeeper"],
13     ),
14 )

Disabling Notifications

To disable notifications for a notification type, set disabled to true in the request body. You can also do this using the Admin Dashboard

POST

/entity/:entityId/notification-policy/:notificationType

1 from mercoa import Mercoa
2 from mercoa.entity_types import NotificationPolicyRequest
3 
4 client = Mercoa(
5     token="YOUR_TOKEN",
6 )
7 client.entity.notification_policy.update(
8     entity_id="ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
9     notification_type="INVOICE_APPROVED",
10     request=NotificationPolicyRequest(
11         disabled=True,
12         additional_roles=[],
13     ),
14 )

Per-User Notification Customizations

Disabling Notifications for a Specific User

To disable notifications for a specific user, set disabled to true in the request body. You can also do this using the Admin Dashboard

POST

/entity/:entityId/user/:userId/notification-policy/:notificationType

1 from mercoa import Mercoa
2 from mercoa.entity_types import UserNotificationPolicyRequest
3 
4 client = Mercoa(
5     token="YOUR_TOKEN",
6 )
7 client.entity.user.notification_policy.update(
8     entity_id="ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
9     user_id="user_e24fc81c-c5ee-47e8-af42-4fe29d895506",
10     notification_type="INVOICE_APPROVED",
11     request=UserNotificationPolicyRequest(
12         disabled=True,
13     ),
14 )

Enable Daily Digest Email

If you want to send a dialy email with all the notifications grouped into a single email, you can enable digest for the user

POST

/entity/:entityId/user/:userId/notification-policy/:notificationType

1 from mercoa import Mercoa
2 from mercoa.entity_types import UserNotificationPolicyRequest
3 
4 client = Mercoa(
5     token="YOUR_TOKEN",
6 )
7 client.entity.user.notification_policy.update(
8     entity_id="ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
9     user_id="user_e24fc81c-c5ee-47e8-af42-4fe29d895506",
10     notification_type="INVOICE_APPROVAL_NEEDED",
11     request=UserNotificationPolicyRequest(
12         digest=True,
13     ),
14 )

Enable Individual Notification Emails

If you want to send an email for each notification, you can enable immediate for the user

POST

/entity/:entityId/user/:userId/notification-policy/:notificationType

1 from mercoa import Mercoa
2 from mercoa.entity_types import UserNotificationPolicyRequest
3 
4 client = Mercoa(
5     token="YOUR_TOKEN",
6 )
7 client.entity.user.notification_policy.update(
8     entity_id="ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
9     user_id="user_e24fc81c-c5ee-47e8-af42-4fe29d895506",
10     notification_type="INVOICE_APPROVED",
11     request=UserNotificationPolicyRequest(
12         disabled=True,
13     ),
14 )

You can enable both digest and immediate notifications at the same time!

Viewing Notifications for a User

To view notifications for a user, use the get all notifications endpoint.

GET

/entity/:entityId/user/:userId/notifications

1 from mercoa import Mercoa
2 
3 client = Mercoa(
4     token="YOUR_TOKEN",
5 )
6 client.entity.user.notifications.find(
7     entity_id="ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
8     user_id="user_e24fc81c-c5ee-47e8-af42-4fe29d895506",
9 )

Customizing Notifications

You can customize the link that is included in the notification email. The default link will open up an standalone web page that displays the Mercoa inbox and invoice. You can customize this link to point to your own website or application.

You can use the Admin Dashboard to customize the link, or you can use the update notification configuration endpoint to customize the link for a specific notification type.

If you want to customize the email template, please reach out to the Mercoa team!