Overview
The Royalti.io API provides comprehensive functionality for delivering music products to Digital Service Providers (DSPs) like Spotify, Apple Music, YouTube Music, and more. This guide covers the complete delivery workflow, from preparation to monitoring.Key Features
- Multi-Provider Delivery - Deliver to multiple DSPs simultaneously
- Real-Time Validation - Pre-flight checks before delivery
- Batch Operations - Process up to 100 products at once
- Status Monitoring - Track delivery progress and logs
- Automatic Retry - Built-in retry logic for failed deliveries
- Legacy Support - Backward-compatible endpoints maintained
Delivery Methods
The API provides two sets of delivery endpoints:New RESTful API (Recommended)
Modern, REST-compliant endpoints for product delivery with full CRUD operations:/product/delivery-providers- Get available providers/product/{id}/deliveries- Manage deliveries/product/batch-delivery- Batch operations
Legacy API (Deprecated)
Maintained for backward compatibility:/product/{id}/delivery- Trigger delivery/product/{id}/delivery/status- Get status
Prerequisites
Before delivering a product, ensure:- Product has a valid UPC - Required for all deliveries
- Assets have ISRCs - Required for track-level metadata
- Metadata is complete - Provider-specific requirements vary
- Provider is configured - Tenant must have access to the provider
Quick Start
1
Check Available Providers
Retrieve the list of providers available to your workspace:
- cURL
- Node.js
- Python
Note the
requiredFields for each provider - you’ll need these for validation.2
Validate Your Product
Before delivering, validate your product meets provider requirements:
- cURL
- Node.js
- Python
3
Initiate Delivery
Once validation passes, initiate delivery to one or more DSPs:Parameters:
- cURL
- Node.js
- Python
providers(required): Array of provider IDs or single provider stringautoDeliver(optional): Set tofalsefor validation only (default:true)settings(optional): Custom DDEX settings to override product defaults
4
Monitor Delivery Progress
Track delivery status and progress:Query Parameters:
- cURL
- Node.js
- Python
provider- Filter by specific providerstatus- Filter by delivery statusdeliveryId- Get specific delivery
Understanding Delivery Providers
Each provider has specific requirements and capabilities. Use the/product/delivery-providers endpoint to discover what’s available.
Response Example:
Provider Information
- id: Unique identifier for API calls
- name: Human-readable display name
- messageType: Format used (ERN, MEAD, CSV)
- deliveryMethod: Transport protocol (SFTP, FTP, API, HTTP)
- requiredFields: Mandatory metadata fields
- requiredAssets: Minimum asset requirements
Delivery Status Lifecycle
Deliveries progress through the following statuses: Status Definitions:pending- Queued, not yet startedprocessing- Actively being delivereddelivered- Successfully completedfailed- Delivery failed, can be retriederror- System error occurredrejected- Provider rejected the deliverycancelled- Manually cancelledretry- Scheduled for retry
Monitoring Delivery Status
Track delivery progress with detailed logs and status information:- cURL
- Node.js
- Python
Handling Failed Deliveries
If a delivery fails, you can retry it with the retry endpoint:- cURL
- Node.js
- Python
- Delivery must be in retryable status (
failed,error,rejected,cancelled) - Cannot exceed maximum retry attempts (default: 3)
Cancelling Deliveries
Cancel a pending or in-progress delivery:- cURL
- Node.js
- Python
pending- Not yet startedretry- Scheduled for retryprocessing- Currently in progress
Batch Delivery
Deliver multiple products to the same provider efficiently:- cURL
- Node.js
- Python
- Maximum 100 products per batch
- All products must have UPC codes
- All products delivered to same provider
Common Use Cases
Single Product, Multiple Providers
Deliver one product to multiple DSPs:Validation Only (Dry-Run)
Check if product is ready without delivering:Custom DDEX Settings
Override default settings for specific delivery:Troubleshooting
Product must have a UPC to be delivered
Product must have a UPC to be delivered
Error:
400 Bad Request - Product must have a UPC to be deliveredCause: The product doesn’t have a UPC assigned, which is required for all DSP deliveries.Solution: Add a UPC to your product before attempting delivery:Provider not available for tenant
Provider not available for tenant
Error:
Provider 'xyz-provider' not available for tenantCause: The provider you’re trying to use isn’t configured for your workspace, or the provider ID is incorrect.Solution:- Check available providers for your workspace:
- Verify you’re using the correct provider ID from the response
- Contact support if you need access to a specific provider
Missing required field errors
Missing required field errors
Error: Validation fails with missing field messagesExample:Solution: The validation response includes specific field suggestions. Update your product with the missing data:
Product not found
Product not found
Error:
404 Not Found - Product not foundCause: The product ID doesn’t exist or doesn’t belong to your workspace.Solution:- Verify the product ID is correct
- Check the product exists in your workspace:
- Ensure you’re using the correct API token for your workspace
Delivery stuck in processing
Delivery stuck in processing
Issue: Delivery status remains “processing” for extended periodCause: Large files, slow provider connections, or provider-side delays.Solution:
- Check delivery logs for detailed progress:
- Typical delivery times:
- Small releases (1-5 tracks): 5-15 minutes
- Albums (6-20 tracks): 15-45 minutes
- Large catalogs: 1-3 hours
- If stuck for more than expected time, contact support with the delivery ID
Maximum retry attempts reached
Maximum retry attempts reached
Error:
400 Bad Request - Delivery has reached maximum retry attempts (3)Cause: The delivery has failed 3 times and can’t be retried automatically.Solution:- Review delivery logs to understand why it’s failing:
- Fix the underlying issue (usually metadata or file problems)
- Create a new delivery instead of retrying:
Best Practices
Always Validate First
Run validation before delivery to catch issues early and avoid failed deliveries. This saves time and API quota.
Monitor Progress
Poll delivery status regularly to track progress and handle failures promptly. Set up webhooks for real-time notifications.
Use Batch Delivery
For multiple products, use batch delivery to reduce API calls and improve efficiency. Process up to 100 products at once.
Handle Retries
Implement automatic retry logic for transient failures with exponential backoff. Don’t retry immediately on failure.
Complete Integration Example
Here’s a full workflow example with error handling and monitoring:- Node.js
- Python
Related Resources
API Reference
Complete API endpoint documentation
DDEX Integration
Learn about DDEX message generation
Asset DDEX Setup
Prepare assets for DDEX delivery
Release Management
Automated product delivery via releases
Support
Need help with product delivery?- Check the API Reference for complete endpoint documentation
- Review DDEX provider requirements
- Contact support at api@royalti.io