API Changelog

​

Documentation

​

API reference expanded

​

Improvements

​

Recoupment tracking, balance carry-forward, and downloadable PDF statements

• Revenue, expense, and dues ledgers, plus a payments view of what’s owed and what’s been paid
• Automatic recoupment tracking, with unrecouped balances carried forward period to period
• PDF statement generation with a per-split breakdown
• Statement-ready notifications

​

Improvements

​

Search, pagination, and MusicBrainz-assisted setup on Publishing endpoints

• Analytics filters on publishing endpoints for narrowing by date, work, or writer
• Pagination added to the claims-inbox endpoint for large catalogs
• Search and facet filters added to the writer and work list endpoints (e.g. GET /writer/writers now takes search, affiliatedPRO, and writerRole)
• Reconciliation now accepts manual statement adjustment entries
• The setup wizard can pull known work/writer data from MusicBrainz during onboarding

​

New Features

​

Catalog import from connected DSP/streaming provider accounts

• Search connected provider accounts and pull in matching tracks, releases, and metadata
• Fetch jobs run asynchronously so large catalogs don’t block other work
• Imported items land in a staging area — nothing touches your live catalog until you confirm
• Already-imported items are recognized and skipped on re-run

​

New Features

​

Branded, white-label exports for reports and catalog data

• Analytics exports (PDF/Excel) carry your label’s letterhead, logo, and chart colors
• Per-card export pulls a single chart or table without generating a full report
• New catalog export templates for labels, splits, and releases

​

New Features

​

AI Release Builder — media upload (cover art / audio / documents)

• Cover art upload via chat — attach a JPEG or PNG directly in the Ask Roy widget; it attaches to the draft immediately. Cover art is required to pass submission checks. A cover that is at least 1500×1500 px is automatically upscaled to 3000×3000 to meet the delivery minimum; smaller images are flagged.
• Per-track audio — attach audio files one at a time; Roy shows a track picker so each file goes to the right track. Duration and bitrate are read from the file automatically.
• PDF release documents — any PDF you attach is added as a release document.
• After attaching files, say “done” (or send { confirm: true } via REST) to move on to validation and review.

Start build → create draft
  → SUSPEND: upload media (cover art required + audio/docs optional)
  → user: "done" → resume { confirm: true }
      → validate (artwork-missing check clears)
          → SUSPEND: review findings
              → user confirms → submit → under_review ✓

​

New Features

​

Guided Release Builder (Ask Roy)

• Metadata completeness — release date, main genre, explicit flag, language, copyright
• ISRC / UPC — format validity + duplicate detection across your catalog
• Artwork & delivery readiness — cover art (≥ 3000×3000) and DDEX/DSP territories
• Split coverage — splits total 100% per track

// POST /ai/release-builder  →  { status, message, data }
{
  "status": "success",
  "message": "Release builder started",
  "data": {
    "runId": "…",
    "status": "suspended",
    "suspendPayload": {
      "releaseId": "…",
      "blocking": true,
      "findings": [
        { "rule": "release-date-required", "severity": "block", "field": "releaseDate" }
      ]
    }
  }
}

​

Improvements

​

Compare mode, saved views, and a unified royalty analytics view

• Flexible period selector with an uncapped all-time chart
• Compare mode to line up two periods, sources, or catalogs
• Saved views for reusable filter/date-range combinations
• A consolidated royalty view spanning master, publishing, and neighbouring rights

​

New Features

​

Webhooks for release & delivery events

• Subscribe to release and DDEX delivery events (submitted, delivered, failed, and more)
• Configure and manage webhook endpoints from Settings → API & Developer
• Near-real-time delivery instead of polling
• A reliability fix shipped July 6 resolved a case where some events weren’t being delivered

​

New Features

​

Publishing module: works, writers, registrations, DMP import & PRO connect

• Create and link works to recordings, with writer and share detail
• Register works with PROs through a guided CWR workflow
• Import existing publishing data from Django Music Publisher instead of re-entering it
• Connect your tenant to the PROs you work with
• A guided bootstrap wizard gets a catalog publishing-ready from a blank state

​

Improvements

​

Broader ERN coverage, takedown/re-deliver, and JosPlay

• Takedown and re-deliver actions available directly via the delivery API, no support ticket needed
• Upgraded ERN messaging from 4.2 to 4.3 for wider DSP/aggregator compatibility
• JosPlay added as a supported aggregator delivery destination

​

New Features

​

Delivery readiness checklist and bulk retry

• Readiness checklist flags missing metadata, artwork, rights info, and more before you attempt delivery
• Bulk retry re-attempts multiple failed deliveries in a single request
• Powers both the dashboard checklist and the bulk-retry action

​

New Features

​

Merlin neighbouring rights: pool-report approvals and invoice reconciliation

• Pool-report cluster approval, bulk or individual
• Invoice scanner matches incoming Merlin invoices against expected payouts
• Paid-status reconciliation flags invoices as paid, unpaid, or mismatched
• Full invoice history available via the Invoices API

​

New Features

​

Claims & disputes inbox for publishing

• Lists every open claim or dispute tied to your catalog
• Bulk resolve for closing out multiple claims at once
• Evidence attachment on a dispute
• Dispute state tracking (open, under review, resolved)

​

New Features

​

Publishing statement reconciliation & payouts

• Match statements against registered works and writer splits
• Surface mismatches where expected shares don’t match what’s reported
• Track payout status per writer and per work
• Drill into any statement line for the underlying work/writer breakdown

​

Improvements

​

DDEX & FUGA delivery pipeline rebuild

• Guided onboarding for connecting DDEX/FUGA delivery
• Centralized, per-label delivery preferences
• CSV import with live preview for bulk catalog loading before delivery
• Remote-folder browser for picking source files from connected storage
• Retry-all re-sends every failed delivery in one action
• Backend fixes for FLAC/WAV packaging and editable delivery metadata

​

New Features

​

Time-based royalty splits

• Temporal-succession splits: define who gets paid what before and after a given date
• Split fields for physical-sale-specific royalties on catalogs with physical distribution
• A rebuilt 1:1 conditions model for clearer, more reliable split configuration

​

Improvements

​

Per-source fees, multi-currency routing, and duplicate detection

• Fee rate and currency configurable per royalty source, applied automatically during processing
• Multi-currency routing sends mixed-currency statement lines to the right place without manual conversion
• Format and duplicate detection catches re-uploaded or malformed files before they land in your totals
• The Source Creator wizard now guides setup with a data-class picker, column mapping, and automatic decimal-format detection

​

New Features

​

Exchange rate management

• Bulk import of historical exchange-rate data
• Live exchange rates on demand
• Date-picker lookup for the rate used on any given statement period

​

New Features

​

Ask Roy: query your real catalog and royalty data

• Natural-language questions about earnings, releases, splits, or catalog status, answered from your own account data
• Guided, step-by-step help for common workflows
• Upload a royalty statement or sales file and Roy auto-detects the format before you map anything

​

New Features

​

Summary Endpoints

{
  "message": "success",
  "summary": {
    "total": 150,
    "byStatus": { "Live": 120, "Taken Down": 15, "Scheduled": 10, "Pending": 5 },
    "byFormat": { "Single": 80, "EP": 45, "Album": 25 },
    "byType": { "Audio": 140, "Video": 10 },
    "revenue": { "totalCount": 5000000, "totalRoyalty": 45000.50 }
  }
}

• Role-based scoping: Regular users see only data for their associated artists
• Parallel aggregation: All queries run concurrently for optimal performance
• Consistent format: All endpoints return { message, summary } structure

​

New Features

​

Royalty Source Filtering Enhancement

• Name: includeAll
• Type: String enum ("true" | "false")
• Default: "true" (maintains backward compatibility)
• Location: Query parameter

• includeAll=true (default): Returns all active public sources (backward compatible)
• includeAll=false: Returns only tenant-associated sources (more secure, filters to sources your organization has configured)

// Get only your tenant's configured sources
const response = await fetch('https://api.royalti.io/file/sources?includeAll=false', {
  headers: { 'Authorization': `Bearer ${token}` }
});

​

Security Improvements

​

Pattern Creator Admin Authentication

• Non-admin users can no longer access pattern creator endpoints
• Pattern creator is now properly secured as an admin-only feature

​

Deprecated Endpoints

​

Pattern Creator Sources Endpoint Removed

- // Old approach
- const sources = await fetch('/pattern-creator/sources');

+ // New approach
+ const sources = await fetch('/sources/admin');

​

Improvements

• Reduced code duplication by 70% through introduction of shared RoyaltySourceService
• Enhanced service layer architecture for better maintainability
• Improved Swagger documentation accuracy across all source-related endpoints
• Updated integration guides with new parameter documentation

​

New Documentation

​

Default Settings API

• GET /defaultsettings/{entityType}/{entityId} - Retrieve default settings
• GET /defaultsettings/settings/{settingId} - Get single setting by ID
• POST /defaultsettings/{entityType}/{entityId} - Create default settings
• PUT /defaultsettings/{entityType}/{entityId}/{settingId} - Update default settings
• DELETE /defaultsettings/{entityType}/{entityId}/{settingId} - Delete default settings
• POST /defaultsettings/clone - Clone settings between entities

• GET /defaultsettings/templates - Browse reusable templates
• GET /defaultsettings/templates/popular - Get most-used templates
• POST /defaultsettings/templates - Create configuration templates
• PUT /defaultsettings/templates/{templateId} - Update template
• DELETE /defaultsettings/templates/{templateId} - Delete template
• POST /defaultsettings/templates/{templateId}/apply - Apply template to entity

• POST /defaultsettings/preview/resolve - Preview inheritance chain
• POST /defaultsettings/preview/asset - Preview asset defaults
• POST /defaultsettings/preview/product - Preview product defaults
• POST /defaultsettings/preview/release - Preview release defaults

• Hierarchical inheritance chain (User → Artist → Label → Catalog → Tenant)
• Four settings categories: Content, Business, DDEX, and Validation
• Template system for reusable configurations
• Preview endpoints for testing before applying
• Advanced use cases and best practices
• Complete code examples in Node.js, Python, and cURL

• Inheritance Chain: Settings cascade from tenant-wide defaults down to user-specific overrides
• Categories: Organize settings by content metadata, business info, DDEX configuration, and validation rules
• Templates: Create and share reusable configuration presets
• Preview System: Test how defaults will be applied without modifying data
• Clone Operation: Duplicate settings between entities for consistency

​

New Features

​

Webhook Delivery System

• Configure webhook endpoints per workspace with custom headers and authentication
• Automatic retry with exponential backoff for failed deliveries
• Monitor webhook health and delivery status in real-time
• Secure webhook delivery with signature verification and rate limiting
• Support for multiple event types: payments, royalty processing, asset changes, releases, and billing events

​

Enhanced Notification System

• Multi-channel notification support (email, SMS, push, in-app)
• Customizable notification templates for different event types
• User-level notification preferences
• Real-time event routing and delivery

​

Improvements

• Enhanced webhook delivery retry logic for better reliability
• Improved notification routing performance
• Better error handling and status reporting for webhook endpoints
• Updated integration guides with webhook examples

​

New Endpoints

• GET /accounting/{id}/stats - Get detailed accounting statistics
• POST /ddex/ern/generate - Generate ERN messages for digital distribution
• GET /royalties/analytics/artist - Advanced artist revenue analytics

​

Breaking Changes

​

Improvements

• Enhanced error messages for validation failures
• Improved performance for bulk operations (up to 50% faster)
• Better caching strategies for frequently accessed data
• Added pagination support to all list endpoints

​

Bug Fixes

• Fixed issue with split calculations not totaling 100% in edge cases
• Resolved timezone handling for international date fields
• Corrected DDEX message validation for special characters

​

Improvements

• Optimized database queries for artist and asset endpoints
• Enhanced webhook delivery retry logic
• Improved file upload validation

​

Bug Fixes

• Fixed duplicate entries in royalty processing
• Resolved authentication token refresh issues
• Corrected calculation errors in temporal splits

​

New Endpoints

• POST /splits/validate - Validate split configurations before saving
• GET /releases/{id}/analytics - Get release performance metrics
• POST /notifications/preferences - Configure notification settings

​

Improvements

• Added multi-currency support for payments
• Enhanced DDEX provider configuration options
• Improved royalty file pattern recognition

​

Bug Fixes

• Fixed edge case in split succession calculations
• Resolved issues with large file uploads (>100MB)
• Corrected artist merge functionality

​

New Endpoints

• GET /accounting/transactions/summary - Get transaction summaries
• POST /artist/bulk - Create artists in bulk
• GET /revenue/analytics/country - Geographic revenue breakdown

​

Improvements

• Added BigQuery integration for advanced analytics
• Enhanced file processing queue performance
• Improved error handling across all endpoints