Building a Custom Music Delivery Platform on the Revelator API

Music distribution has never been more accessible. Platforms like DistroKid, TuneCore, and CD Baby democratized access to DSPs (Digital Service Providers) for independent artists. But for companies operating as distributors - managing multiple labels, complex territory restrictions, and custom royalty splits - the generic UI and rigid workflows of consumer-facing tools quickly become a bottleneck.

Why Distributors Outgrow Off-the-Shelf Platforms

The friction points are predictable:

This is where the build-vs-buy decision becomes real.

The Two Paths: Frontend-Only vs. Full Stack

Distributors who've outgrown their current setup face a fundamental architectural choice:

This article focuses on Option A: what it looks like in practice, where it excels, and where it hits structural limits.

What the Revelator API Actually Offers

Revelator positions itself as an "end-to-end operating system" for independent music businesses. Unlike consumer-facing distributors, it's B2B infrastructure - designed for labels, aggregators, and distributors who want to run their own branded operation.

The API is RESTful, JSON-based, and covers five core modules:

Catalog Management

• Create and edit releases via POST /content/release/save
• Upload audio (WAV/FLAC, minimum 16-bit, 44.1 kHz stereo) and cover art (minimum 1400x1400px JPG/RGB)
• Manage ISRCs (International Standard Recording Codes), UPCs (Universal Product Codes), and external DSP artist IDs
• Support for multi-disc releases and localized metadata

Distribution

• Pre-delivery validation: POST /distribution/release/{releaseId}/validate
• Set DSP targets, release dates, and territories per release
• Queue releases for delivery: POST /distribution/release/addtoqueue
• Track delivery status (statuses range from -20 to 100; 50+ means delivered)
• Takedown support: POST /distribution/release/takedown
• Webhook callbacks for delivery status updates

Rights and Royalties

• Contract definition with configurable splits and recoupables
• DSP statement import and reconciliation
• Multi-currency payout automation via Tipalti and PayPal

Analytics

• Streaming and revenue data queryable by track, release, region, or DSP
• Playlist performance tracking
• CSV export and raw data sync

Account Management

• Parent-child account hierarchy (your enterprise is the parent; each label or artist is a child)
• Full visibility into child account assets
• Mandatory approval step before content reaches DSPs

Architecture of the Hybrid Solution

The hybrid approach layers your custom platform on top of Revelator's delivery infrastructure:

What You Build

What Revelator Handles

Quick Example: Creating a Release via Revelator API

Here's a minimal example of how your backend would create and distribute a release through Revelator's API:

import httpx

REVELATOR_API = "https://api.revelator.com"

# 1. Authenticate
auth = httpx.post(f"{REVELATOR_API}/partner/account/login", json={
    "email": "your@email.com",
    "password": "your-password"
})
token = auth.json()["token"]
headers = {"Authorization": f"Bearer {token}"}

# 2. Create a release
release = httpx.post(f"{REVELATOR_API}/content/release/save", headers=headers, json={
    "title": "Delilah - Summer Version",
    "releaseType": "Single",
    "artists": [
        {"name": "MIKOLAS", "role": "MainArtist"},
        {"name": "Mark Neve", "role": "MainArtist"}
    ],
    "genre": "Pop",
    "releaseDate": "2026-04-01",
    "territories": {
        "include": "Worldwide",
        "exclude": ["JP", "DE", "AT", "CH", "NL", "AU", "NZ"]
    }
})
release_id = release.json()["id"]

# 3. Validate before delivery
validation = httpx.post(
    f"{REVELATOR_API}/distribution/release/{release_id}/validate",
    headers=headers
)

# 4. Queue for delivery to DSPs
if validation.json()["valid"]:
    httpx.post(f"{REVELATOR_API}/distribution/release/addtoqueue",
        headers=headers,
        json={"releaseId": release_id}
    )

DDEX as the Backbone

Under the hood, every delivery to a DSP is a DDEX ERN message - an XML package describing the release, its resources (audio, artwork), and the commercial terms (deals) under which DSPs can exploit the content.

An ERN message has three critical sections:

ResourceList

Defines the audio files, cover art, and their metadata. Each sound recording includes an ISRC, title, artist credits, and territory-specific details:

<SoundRecording>
  <SoundRecordingId>
    <ISRC>SKXXX2500001</ISRC>
  </SoundRecordingId>
  <ResourceReference>A1</ResourceReference>
  <SoundRecordingDetailsByTerritory>
    <TerritoryCode>Worldwide</TerritoryCode>
    <Title TitleType="FormalTitle">
      <TitleText>Delilah</TitleText>
    </Title>
    <DisplayArtist>
      <PartyName><FullName>MIKOLAS</FullName></PartyName>
      <ArtistRole>MainArtist</ArtistRole>
    </DisplayArtist>
  </SoundRecordingDetailsByTerritory>
</SoundRecording>

ReleaseList

Defines the product - the album or single - and links it to its component resources:

<Release>
  <ReleaseId><ICPN>0123456789012</ICPN></ReleaseId>
  <ReleaseReference>R0</ReleaseReference>
  <ReleaseType>Album</ReleaseType>
  <ReleaseDetailsByTerritory>
    <TerritoryCode>Worldwide</TerritoryCode>
    <DisplayArtistName>MIKOLAS</DisplayArtistName>
    <Title TitleType="FormalTitle">
      <TitleText>ONE</TitleText>
    </Title>
  </ReleaseDetailsByTerritory>
</Release>

DealList

The only section that grants commercial rights. This is where territory restrictions live:

<ReleaseDeal>
  <DealReleaseReference>R0</DealReleaseReference>
  <Deal>
    <DealTerms>
      <TerritoryCode>Worldwide</TerritoryCode>
      <ExcludedTerritoryCode>JP</ExcludedTerritoryCode>
      <CommercialModelType>SubscriptionModel</CommercialModelType>
      <Usage>
        <UseType>OnDemandStream</UseType>
      </Usage>
      <ValidityPeriod>
        <StartDate>2026-03-15</StartDate>
      </ValidityPeriod>
    </DealTerms>
  </Deal>
</ReleaseDeal>

Territory Restrictions in Practice

When a distributor has agreements with partners who hold rights in specific regions, individual tracks must be excluded from those territories. This requires consistent territory entries across three XML sections:

1. SoundRecordingDetailsByTerritory in ResourceList
2. ReleaseDetailsByTerritory in ReleaseList
3. DealTerms in DealList

Platforms like Revelator handle this at the release level through their UI, but track-level territory restrictions within an album are where the friction begins. This is exactly the kind of limitation that pushes distributors toward a custom frontend - you model the territory logic in your own system and push the correct per-track restrictions through the API.

Real-World Gotchas

Having worked with distributors who use Revelator as their delivery backbone, here are the practical challenges we've encountered:

2. Full Object Re-submission

There is no PATCH support for releases. Editing a release requires re-submitting the full release object. If you omit files, they are auto-deleted. This means your backend must always maintain the complete release state.

3. Breaking API Changes

Revelator's API has had several breaking changes in 2025-2026:

Your integration layer needs resilience against schema drift.

4. DSP-Specific DDEX Interpretation

Even when Revelator generates valid ERN XML, each DSP interprets certain elements differently. Spotify's ingestion engine, Apple's Content Provider system, and Amazon's pipeline each have proprietary extensions and quirks. When delivery fails, debugging requires understanding both the DDEX standard and the specific DSP's interpretation.

5. Locked Distribution States

Tracks in certain distribution statuses (-10, -11, -20, -21) become read-only. If you need to modify metadata on a locked track, you may need to initiate a takedown and redeliver, adding complexity to your workflow engine.

When Does Option A Become a Dead End?

The hybrid approach works well when:

• Your catalog is under 50,000 releases
• You have fewer than 30 DSP targets
• Territory complexity is moderate (album-level restrictions, not per-track-per-DSP)
• Royalty reporting needs are standard (DSP-level aggregates, not sub-publishing splits)

It starts breaking down when:

The Hybrid-to-Independent Migration Path

The smartest architecture for Option A anticipates Option B:

1. Own your metadata. Never treat Revelator as the source of truth. Your database is canonical; Revelator is a sync target.
2. Abstract the delivery layer. Build an internal delivery interface that Revelator implements today but could be swapped for direct DSP integrations tomorrow.
3. Build your own rights engine from day one. Territory restrictions, split sheets, and rights ownership are your core IP. Never delegate this logic to the platform.
4. Invest in DDEX competency. Understanding ERN generation and validation - even if Revelator handles it today - is essential knowledge for the eventual transition.

Conclusion

For distributors with direct DSP contracts who are hitting the limits of their current platform, the hybrid approach - custom frontend on Revelator's API - is the fastest path to operational control without the multi-year investment of going fully independent.

The key is to build it with migration in mind. Own your metadata, abstract your delivery layer, and invest in DDEX expertise. When the time comes to replace the backend, you'll be swapping a component rather than rebuilding a platform.

Need Help Deciding?

At MusicTech Lab, we've helped distributors navigate both paths - from fixing DDEX validation issues and territory restrictions within existing Revelator workflows, to designing the architecture for independent delivery pipelines. If you're at this decision point, get in touch.

Resources

• Revelator API Documentation
• DDEX ERN Knowledge Base
• MTL DDEX Validator
• DDEX Open Source Projects Review
• Introduction to Generating DDEX Files Using Python