Notification System Guide - Royalti.io API

Overview
Why Use Notifications?
Notification Channels
Notification Types
User & Collaboration Events
Catalog Management Events
Financial Events
Quick Start
Notification Structure
Field Descriptions
API Endpoints
Get Notifications
Get Unread Count
Mark Notification as Read
Mark All Notifications as Read
Notification Preferences
Get Notification Preferences
Update Notification Preferences
Preference Configuration
Available Channels
Notification Batching
Integration Patterns
Real-Time Notification Display
Notification List Component
Preference Management UI
Best Practices
Troubleshooting
Notifications Not Appearing
Missing Notification Preferences
High Unread Count
FAQ
Support & Resources

Overview

The Royalti.io notification system keeps users informed about important events across your workspace through multiple delivery channels. This guide covers how to retrieve, manage, and customize notification preferences for your users.

Why Use Notifications?

Stay Informed: Get real-time updates about critical events in your workspace
Multi-Channel Delivery: Receive notifications via in-app, email, and push notifications
Customizable: Control which events trigger notifications and through which channels
Centralized: All notifications are accessible through a unified API
Actionable: Notifications link directly to relevant resources for quick action

Notification Channels

Royalti.io supports three notification channels:

Channel	Description	Use Case
`IN_APP`	In-app notifications displayed in the Royalti dashboard	Real-time updates while users are actively working
`EMAIL`	Email notifications sent to user’s registered email address	Important updates that require user attention
`PUSH`	Push notifications sent to mobile devices	Urgent updates when users are away from the dashboard

Users can customize which channels they want to receive for each notification type through their preferences.

Notification Types

Royalti.io generates notifications for events across multiple categories:

User & Collaboration Events

Event Type	Description	Default Channels
`USER_CREATED`	New user added to workspace	IN_APP, EMAIL
`USER_UPDATED`	User profile or permissions modified	IN_APP
`USER_DELETED`	User removed from workspace	IN_APP, EMAIL
`USER_INVITATION_SENT`	User invited to workspace	EMAIL
`USER_ADDED_TO_SPLIT`	User added to revenue split	IN_APP, EMAIL
`USER_REMOVED_FROM_SPLIT`	User removed from revenue split	IN_APP, EMAIL

Catalog Management Events

Event Type	Description	Default Channels
`ARTIST_CREATED`	New artist profile created	IN_APP
`ARTIST_UPDATED`	Artist profile modified	IN_APP
`ARTIST_DELETED`	Artist profile removed	IN_APP
`ASSET_CREATED`	New asset (track) added	IN_APP
`ASSET_UPDATED`	Asset modified	IN_APP
`ASSET_DELETED`	Asset removed	IN_APP
`PRODUCT_CREATED`	New product (album/release) created	IN_APP
`PRODUCT_UPDATED`	Product modified	IN_APP
`PRODUCT_DELETED`	Product removed	IN_APP

Financial Events

Event Type	Description	Default Channels
`PAYMENT_REQUEST_SENT`	Payment request created	IN_APP, EMAIL
`PAYMENT_REQUEST_APPROVED`	Payment request approved	IN_APP, EMAIL
`PAYMENT_REQUEST_REJECTED`	Payment request rejected	IN_APP, EMAIL
`PAYMENT_MADE_PROCESSING`	Payment being processed	IN_APP
`PAYMENT_MADE_COMPLETED`	Payment successfully completed	IN_APP, EMAIL
`PAYMENT_MADE_FAILED`	Payment failed	IN_APP, EMAIL
`PAYMENT_DELETED`	Payment record deleted	IN_APP
`REVENUE_CREATED`	Revenue entry created	IN_APP
`REVENUE_UPDATED`	Revenue entry modified	IN_APP
`REVENUE_DELETED`	Revenue entry deleted	IN_APP
`EXPENSE_CREATED`	Expense entry created	IN_APP
`EXPENSE_UPDATED`	Expense entry modified	IN_APP
`EXPENSE_DELETED`	Expense entry deleted	IN_APP

Quick Start

Get Notifications

Retrieve notifications for the authenticated user:

curl -X GET "https://server26-dot-royalti-project.uc.r.appspot.com/notifications?page=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "status": "success",
  "message": "Notifications retrieved successfully",
  "data": {
    "notifications": [
      {
        "id": "dd12f9bc-3ed5-453e-a929-69b6d5267f4b",
        "type": "ASSET_CREATED",
        "title": "Track Created",
        "content": "Track \"Midnight City\" has been created.",
        "resourceType": "Asset",
        "resourceId": "0b13028e-74a9-4d1d-bb9f-12cef06ff236",
        "actionUrl": "/assets/0b13028e-74a9-4d1d-bb9f-12cef06ff236",
        "isRead": false,
        "isImportant": false,
        "createdAt": "2025-08-21T11:42:37.717Z"
      }
    ],
    "total": 34,
    "page": 1,
    "pageSize": 20,
    "totalPages": 2
  }
}

Check Unread Count

Get the count of unread notifications:

curl -X GET "https://server26-dot-royalti-project.uc.r.appspot.com/notifications/unread/count" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "status": "success",
  "message": "Unread notification count retrieved successfully",
  "data": {
    "count": 5
  }
}

Mark as Read

Mark a specific notification as read:

curl -X PATCH "https://server26-dot-royalti-project.uc.r.appspot.com/notifications/dd12f9bc-3ed5-453e-a929-69b6d5267f4b/read" \
  -H "Authorization: Bearer YOUR_TOKEN"

Or mark all notifications as read:

curl -X PATCH "https://server26-dot-royalti-project.uc.r.appspot.com/notifications/mark-all-read" \
  -H "Authorization: Bearer YOUR_TOKEN"

Configure Preferences

Customize notification preferences:

curl -X PUT "https://server26-dot-royalti-project.uc.r.appspot.com/notifications/preferences" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "preferences": [
      {
        "notificationType": "PAYMENT_MADE_COMPLETED",
        "channels": ["EMAIL", "IN_APP", "PUSH"],
        "isEnabled": true
      },
      {
        "notificationType": "ASSET_CREATED",
        "channels": ["IN_APP"],
        "isEnabled": true
      }
    ]
  }'

Notification Structure

All notifications follow a standardized structure:

{
  "id": "dd12f9bc-3ed5-453e-a929-69b6d5267f4b",
  "type": "PAYMENT_MADE_COMPLETED",
  "title": "Payment Completed",
  "content": "Payment of $1,500.00 to Artist Name has been completed successfully.",
  "resourceType": "payment",
  "resourceId": "pay_123abc",
  "actionUrl": "/payments/pay_123abc",
  "isRead": false,
  "isImportant": true,
  "isArchived": false,
  "metadata": {
    "amount": 1500.00,
    "currency": "USD",
    "recipientName": "Artist Name",
    "method": "stripe"
  },
  "expiresAt": null,
  "TenantId": 2,
  "TenantUserId": "c75c54e3-b6e0-4b89-b443-928727b9a931",
  "createdAt": "2025-01-22T14:30:00.000Z",
  "updatedAt": "2025-01-22T14:30:00.000Z"
}

Field Descriptions

Field	Type	Description
`id`	string (UUID)	Unique notification identifier
`type`	string	Notification type from NotificationType enum
`title`	string	Short notification title
`content`	string	Detailed notification message
`resourceType`	string	Type of resource the notification relates to
`resourceId`	string	ID of the related resource
`actionUrl`	string	URL to navigate to when notification is clicked
`isRead`	boolean	Whether the notification has been read
`isImportant`	boolean	Whether the notification is marked as important
`isArchived`	boolean	Whether the notification is archived
`metadata`	object	Additional event-specific data
`expiresAt`	ISO 8601	When the notification expires (null for no expiration)
`TenantId`	integer	Workspace ID
`TenantUserId`	string (UUID)	User ID the notification is for
`createdAt`	ISO 8601	When the notification was created
`updatedAt`	ISO 8601	When the notification was last updated

API Endpoints

Get Notifications

Retrieve paginated notifications with optional filtering. Endpoint: GET /notifications Query Parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number
`pageSize`	integer	20	Number of items per page
`isRead`	boolean	-	Filter by read status
`isArchived`	boolean	-	Filter by archived status
`type`	string	-	Filter by notification type

Example:

# Get unread notifications
curl -X GET "https://server26-dot-royalti-project.uc.r.appspot.com/notifications?isRead=false&page=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get payment notifications
curl -X GET "https://server26-dot-royalti-project.uc.r.appspot.com/notifications?type=PAYMENT_MADE_COMPLETED" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Unread Count

Get the count of unread notifications for quick badge display. Endpoint: GET /notifications/unread/count Example:

curl -X GET "https://server26-dot-royalti-project.uc.r.appspot.com/notifications/unread/count" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "status": "success",
  "message": "Unread notification count retrieved successfully",
  "data": {
    "count": 12
  }
}

Mark Notification as Read

Mark a specific notification as read. Endpoint: PATCH /notifications/{notificationId}/read Path Parameters:

Parameter	Type	Required	Description
`notificationId`	string (UUID)	Yes	ID of the notification

Example:

curl -X PATCH "https://server26-dot-royalti-project.uc.r.appspot.com/notifications/dd12f9bc-3ed5-453e-a929-69b6d5267f4b/read" \
  -H "Authorization: Bearer YOUR_TOKEN"

Mark All Notifications as Read

Mark all notifications as read for the authenticated user. Endpoint: PATCH /notifications/mark-all-read Example:

curl -X PATCH "https://server26-dot-royalti-project.uc.r.appspot.com/notifications/mark-all-read" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "status": "success",
  "message": "All notifications marked as read"
}

Notification Preferences

Users can customize which notifications they receive and through which channels.

Get Notification Preferences

Retrieve the current notification preferences for the authenticated user. Endpoint: GET /notifications/preferences Example:

curl -X GET "https://server26-dot-royalti-project.uc.r.appspot.com/notifications/preferences" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "status": "success",
  "message": "Notification preferences retrieved successfully",
  "data": {
    "preferences": [
      {
        "id": "65fdcd80-cada-4c76-83ec-70d8e895774d",
        "notificationType": "PAYMENT_MADE_COMPLETED",
        "channels": ["EMAIL", "IN_APP", "PUSH"],
        "isEnabled": true,
        "createdAt": "2025-05-27T19:55:02.423Z",
        "updatedAt": "2025-05-27T19:55:02.423Z"
      },
      {
        "id": "9e522898-358c-4208-9f7d-94bac43b7cf4",
        "notificationType": "ASSET_CREATED",
        "channels": ["IN_APP"],
        "isEnabled": true,
        "createdAt": "2025-05-27T21:17:56.973Z",
        "updatedAt": "2025-05-27T21:17:56.973Z"
      }
    ]
  }
}

Update Notification Preferences

Customize which notifications to receive and through which channels. Endpoint: PUT /notifications/preferences Request Body:

{
  "preferences": [
    {
      "notificationType": "PAYMENT_MADE_COMPLETED",
      "channels": ["EMAIL", "IN_APP", "PUSH"],
      "isEnabled": true
    },
    {
      "notificationType": "PAYMENT_MADE_FAILED",
      "channels": ["EMAIL", "PUSH"],
      "isEnabled": true
    },
    {
      "notificationType": "ASSET_CREATED",
      "channels": ["IN_APP"],
      "isEnabled": false
    }
  ]
}

Example:

curl -X PUT "https://server26-dot-royalti-project.uc.r.appspot.com/notifications/preferences" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "preferences": [
      {
        "notificationType": "PAYMENT_MADE_COMPLETED",
        "channels": ["EMAIL", "IN_APP", "PUSH"],
        "isEnabled": true
      },
      {
        "notificationType": "ASSET_CREATED",
        "channels": ["IN_APP"],
        "isEnabled": false
      }
    ]
  }'

Response:

{
  "status": "success",
  "message": "Notification preferences updated successfully",
  "data": {
    "preferences": [
      {
        "id": "65fdcd80-cada-4c76-83ec-70d8e895774d",
        "notificationType": "PAYMENT_MADE_COMPLETED",
        "channels": ["EMAIL", "IN_APP", "PUSH"],
        "isEnabled": true,
        "createdAt": "2025-05-27T19:55:02.423Z",
        "updatedAt": "2025-01-22T15:30:00.000Z"
      }
    ]
  }
}

Preference Configuration

Available Channels

Channel	Description	Delivery Time
`EMAIL`	Email to registered address	Immediate or batched (hourly aggregation)
`IN_APP`	In-app notification in dashboard	Real-time
`PUSH`	Push notification to mobile device	Real-time

Notification Batching

Some notification types support batching to reduce email volume:

Immediate: Critical notifications (payments, failures) are sent immediately
Hourly Aggregation: Non-critical notifications (asset created, updates) are batched and sent hourly
Daily Cleanup: Expired notifications are automatically removed

Integration Patterns

Real-Time Notification Display

Implement a notification bell with unread count:

async function updateNotificationBell() {
  const response = await fetch(
    'https://server26-dot-royalti-project.uc.r.appspot.com/notifications/unread/count',
    {
      headers: {
        'Authorization': `Bearer ${token}`
      }
    }
  );

  const { data } = await response.json();

  // Update UI badge
  document.getElementById('notification-badge').textContent = data.count;
  document.getElementById('notification-badge').style.display =
    data.count > 0 ? 'block' : 'none';
}

// Poll every 30 seconds
setInterval(updateNotificationBell, 30000);

Notification List Component

Fetch and display notifications with pagination:

async function loadNotifications(page = 1) {
  const response = await fetch(
    `https://server26-dot-royalti-project.uc.r.appspot.com/notifications?page=${page}&pageSize=10&isRead=false`,
    {
      headers: {
        'Authorization': `Bearer ${token}`
      }
    }
  );

  const { data } = await response.json();

  data.notifications.forEach(notification => {
    renderNotification(notification);
  });

  // Handle pagination
  renderPagination(data.page, data.totalPages);
}

function renderNotification(notification) {
  const item = document.createElement('div');
  item.className = notification.isImportant ? 'notification important' : 'notification';
  item.innerHTML = `
    <h4>${notification.title}</h4>
    <p>${notification.content}</p>
    <small>${new Date(notification.createdAt).toLocaleString()}</small>
    ${notification.actionUrl ? `<a href="${notification.actionUrl}">View</a>` : ''}
  `;

  item.addEventListener('click', () => markAsRead(notification.id));

  document.getElementById('notification-list').appendChild(item);
}

async function markAsRead(notificationId) {
  await fetch(
    `https://server26-dot-royalti-project.uc.r.appspot.com/notifications/${notificationId}/read`,
    {
      method: 'PATCH',
      headers: {
        'Authorization': `Bearer ${token}`
      }
    }
  );

  // Refresh notification list
  loadNotifications();
}

Preference Management UI

Allow users to customize notification preferences:

async function loadPreferences() {
  const response = await fetch(
    'https://server26-dot-royalti-project.uc.r.appspot.com/notifications/preferences',
    {
      headers: {
        'Authorization': `Bearer ${token}`
      }
    }
  );

  const { data } = await response.json();

  data.preferences.forEach(pref => {
    renderPreferenceControl(pref);
  });
}

async function updatePreference(notificationType, channels, isEnabled) {
  const response = await fetch(
    'https://server26-dot-royalti-project.uc.r.appspot.com/notifications/preferences',
    {
      method: 'PUT',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        preferences: [
          {
            notificationType,
            channels,
            isEnabled
          }
        ]
      })
    }
  );

  const result = await response.json();
  console.log('Preferences updated:', result);
}

Best Practices

✅ User Experience

Display unread count prominently in your UI (bell icon with badge)
Mark notifications as read when user views them
Provide action links to relevant resources when applicable
Group similar notifications to reduce clutter
Auto-refresh notification count periodically (every 30-60 seconds)
Show timestamps in user-friendly format (e.g., “5 minutes ago”)
Highlight important notifications with visual indicators
Allow bulk actions (mark all as read, archive, etc.)

✅ Performance Optimization

Use pagination to limit the number of notifications loaded at once
Cache unread count to reduce API calls
Implement lazy loading for notification details
Batch preference updates when changing multiple settings
Use WebSockets or polling for real-time updates (if available)

✅ Preference Management

Provide granular controls for each notification type
Set sensible defaults based on notification importance
Allow channel-specific preferences (email vs. in-app vs. push)
Explain notification types so users understand what they’re opting into
Respect user preferences immediately - no delay in applying changes

⚠️ Common Pitfalls

Don’t overwhelm users with too many notifications
Don’t ignore unread status - always mark as read when viewed
Don’t hardcode notification types - use the API to get available types
Don’t skip error handling - API calls may fail
Don’t forget to implement pagination - notification lists can grow large

Troubleshooting

Notifications Not Appearing

✅ Checklist:

Check notification preferences - is the event type enabled?
Verify the user has the correct permissions
Check if notifications are filtered by isRead or isArchived
Ensure the tenant ID matches the authenticated user’s workspace
Check the API response for errors

Missing Notification Preferences

✅ Solutions:

Preferences are created on-demand when first updated
Default preferences are used if none are set
Call GET /notifications/preferences to see current state
Update preferences with PUT /notifications/preferences

High Unread Count

✅ Management:

Implement “Mark all as read” functionality
Allow users to archive old notifications
Set expiration dates for less important notifications
Encourage users to customize preferences to reduce noise

FAQ

Can I receive notifications for events from other users in my workspace?

Yes, notifications are workspace-scoped. When events occur in your workspace (e.g., a teammate creates an asset), all relevant users receive notifications based on their preferences and permissions.

How long are notifications stored?

Notifications are stored indefinitely unless they have an expiresAt date. Expired notifications are automatically removed by the daily cleanup job at 2 AM UTC.

Can I disable all notifications?

Yes, you can disable notifications by setting isEnabled: false for each notification type in your preferences. Alternatively, you can choose to only enable the IN_APP channel and manage notifications within the dashboard.

Are notifications sent in real-time?

In-app and push notifications are sent in real-time. Email notifications for non-critical events may be batched and sent hourly to reduce email volume. Critical notifications (payments, failures) are always sent immediately.

Can I get notifications for specific artists or products only?

Currently, notifications are workspace-level and cannot be filtered by specific resources. You can control notification types and channels, but not individual resources. This feature may be added in future updates.

What happens if notification delivery fails?

Failed notifications are automatically retried based on the channel’s retry strategy. If all retry attempts fail, the notification is logged for debugging but the in-app notification remains accessible through the API.

Can I customize notification templates?

Notification templates are currently managed by Royalti.io and cannot be customized per workspace. However, you can control which notifications you receive through your preferences.

Support & Resources

API Documentation:

Notifications API Reference - Complete API documentation

Related Guides:

User Management - Managing workspace users
Webhook Integration - Real-time event notifications to external systems

External Resources:

Support Portal - Get help from our support team
Status Page - Check system status and uptime

Last Updated: January 2025 Version: 1.0

FUGA Integration Guide Webhook Integration Guide

⌘I

Getting Started

Guides

Changelog

Accounting

Artist

Asset

Auth

Checklists

Ddex

Default Settings

Expense

File

Integration

Label

Notifications

Payment Requests

Payment Settings

Payments

Product

Release

Revenue

Royalties

Sources

Splits

User

Vertofx

Webhooks

​Overview

​Why Use Notifications?

​Notification Channels

​Notification Types

​User & Collaboration Events

​Catalog Management Events

​Financial Events

​Quick Start

​Notification Structure

​Field Descriptions

​API Endpoints

​Get Notifications

​Get Unread Count

​Mark Notification as Read

​Mark All Notifications as Read

​Notification Preferences

​Get Notification Preferences

​Update Notification Preferences

​Preference Configuration

​Available Channels

​Notification Batching

​Integration Patterns

​Real-Time Notification Display

​Notification List Component

​Preference Management UI

​Best Practices

​Troubleshooting

​Notifications Not Appearing

​Missing Notification Preferences

​High Unread Count

​FAQ

​Support & Resources

Overview

Why Use Notifications?

Notification Channels

Notification Types

User & Collaboration Events

Catalog Management Events

Financial Events

Quick Start

Notification Structure

Field Descriptions

API Endpoints

Get Notifications

Get Unread Count

Mark Notification as Read

Mark All Notifications as Read

Notification Preferences

Get Notification Preferences

Update Notification Preferences

Preference Configuration

Available Channels

Notification Batching

Integration Patterns

Real-Time Notification Display

Notification List Component

Preference Management UI

Best Practices

Troubleshooting

Notifications Not Appearing

Missing Notification Preferences

High Unread Count

FAQ

Support & Resources