Guides

Notifications

API Reference

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:

EventDescriptionDefault Recipient
INVOICE_APPROVAL_NEEDEDAn invoice is created and needs approvalThe designated approver(s) of the invoice
INVOICE_APPROVEDAn invoice is approvedInvoice Creator
INVOICE_REJECTEDAn invoice is rejectedInvoice Creator
INVOICE_SCHEDULEDAn invoice is scheduled for paymentNone
INVOICE_PENDINGAn invoice payment has initiatedNone
INVOICE_PAIDAn invoice is marked as paidInvoice Creator
INVOICE_CANCELEDAn invoice is marked as canceledNone
INVOICE_CREATEDA new invoice is created by any means (email, upload, etc.)None
INVOICE_EMAILEDA new invoice is emailed to the email inboxNone
INVOICE_FAILEDAn invoice payment failedInvoice 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

1curl -X POST \
2     --url "https://api.mercoa.com/entity/:entityId/notification-policy/INVOICE_APPROVED" \
3     --header "Content-Type: application/json" \
4     --header "Authorization: Bearer <token>" \
5     --header "Accept: application/json" \
6     --data '
7{
8  "additionalRoles": [
9    "admin"
10  ]
11}
12 '

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

1curl -X POST \
2     --url "https://api.mercoa.com/entity/:entityId/notification-policy/INVOICE_APPROVED" \
3     --header "Content-Type: application/json" \
4     --header "Authorization: Bearer <token>" \
5     --header "Accept: application/json" \
6     --data '
7{
8  "disabled": true
9}
10 '

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

1curl -X POST \
2     --url "https://api.mercoa.com/entity/:entityId/user/:userId/notification-policy/INVOICE_APPROVED" \
3     --header "Content-Type: application/json" \
4     --header "Authorization: Bearer <token>" \
5     --header "Accept: application/json" \
6     --data '
7{
8  "disabled": true
9}
10 '

Viewing Notifications for a User

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

Customizing Notifications

Currently, 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.

Built with