Revelator Logo API
v1

Territories Clearances

Transition Period Note: While we transition to the new API, you must combine these endpoints with legacy endpoints (e.g., POST /content/release/retail/save) to ensure the distribution workflow is completed successfully.

Use these endpoints to define Availability Rules for a release and its tracks. These rules determine exactly where (territories) and on which platforms (DSPs) your content is live.

Default Behavior

By default, a release is distributed Worldwide to All Selected Services. Any rules you add via these endpoints act as exceptions to restrict or narrow that default availability.

Common Scenarios

Here are the most common ways to use these endpoints to solve distribution challenges.

1. Sample Clearance (Restricting a specific track)

Goal: Distribute a 5-track album worldwide, but Track 5 cannot be distributed in the US due to rights issues.

  • Release Rule: None (Defaults to Worldwide).
  • Asset Rule (Track 5): Exclude → United States (Store: All/Specific).
  • Result: Tracks 1–4 are live worldwide. Track 5 is hidden in the US but live everywhere else.

2. Regional Exclusives (Commercial Strategy)

Goal: Send the release to all DSPs worldwide, but restrict Tencent deliveries to China only.

  • Release Rule: Include → China (Scope: Tencent).
  • Result: Spotify and Apple Music receive the release worldwide. Tencent receives it only for the Chinese market.

3. Bonus Tracks (Market Specific)

Goal: Deliver a “Japan Bonus Track” only to Deezer in Japan.

  • Release Rule: None.
  • Asset Rule (Bonus Track): Include → Japan (Scope: Deezer).
  • Result: Standard tracks are worldwide. The bonus track appears only on Deezer in Japan.

Availability Logic & Constraints

To ensure your request is accepted, you must adhere to the following logic hierarchy.

1. The Subset Rule (Track vs. Release)

Rule: A track can never be more available than the release it belongs to. Track-level rules can only further restrict availability; they cannot expand it beyond the release’s boundaries.

  • ❌ Invalid: Release is set to “United Kingdom Only”, but you try to set Track 1 to “France”.
  • ✅ Valid: Release is set to “Worldwide”, and you set Track 1 to “Exclude United States”.

2. The Specificity Rule (Store Priority)

Rule: If you define a rule for a specific DSP (e.g., Spotify), it overrides any general “All Stores” rules for that specific DSP.

  • Scenario: You set “All Stores” to Worldwide, but set “Spotify” to “United Kingdom Only”.
  • Result: Spotify shows the release in the UK only. All other stores show it Worldwide.

3. The Singularity Rule (One Rule Per Context)

Rule: You cannot define multiple rules for the same Asset + Store combination.

  • ❌ Invalid: Sending one rule saying “Spotify: Exclude Japan” and another rule saying “Spotify: Exclude Korea” for the same track.
  • ✅ Valid: Sending a single rule: “Spotify: Exclude Japan, Korea”.

4. YouTube Rights Consistency

Rule: You must maintain consistency between YouTube Music (13) and YouTube Content ID (307). If you define a territory rule (Include or Exclude) for YouTube Music, you must define a corresponding rule for YouTube Content ID and vice versa.

  • Logic: Any geographic restriction applied to the commercial delivery (YouTube Music) must be reflected in the rights management policy (Content ID).
  • Example: If you set a rule for YouTube Music to Include: Japan, you must also create a rule for YouTube Content ID to Include: Japan.

Get Territories Clearances

GET /supply-chain/v1/releases/{releaseId}/territories-clearances

Retrieves the current availability rules for a release and its tracks.

Path Parameters

Parameter Description
releaseId * integer

-

Responses

object
distributorStoreId integer | null
mode TerritoryClearanceMode
enum
Values: Include, Exclude
countryIds integer[]
assetId integer
assetType AssetTypes
enum
Values: Track
mode TerritoryClearanceMode
enum
Values: Include, Exclude
distributorStoreId integer | null
countryIds integer[]
GET /supply-chain/v1/releases/{releaseId}/territories-clearances 
curl -X GET "https://platform.revelator.com/supply-chain/v1/releases/824453/territories-clearances" -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Example response 200 
{
  "release": [],
  "assets": [
      {
          "assetId": 4546107,
          "assetType": "track",
          "mode": "include",
          "distributorStoreId": 7,
          "countryIds": [
              246
          ]
      }
  ]
}

Set Territories Clearances

PUT /supply-chain/v1/releases/{releaseId}/territories-clearances

Sets the availability rules for the release. Note that this replaces the existing configuration.

Path Parameters

Parameter Description
releaseId * integer

ID of the release for which you want to set territories.

Request Body *

object
distributorStoreId integer
ID of the store (DSP) to apply this rule to.
mode TerritoryClearanceMode
enum
Availability logic.
Values: Include, Exclude
countryIds integer[]
Array of numeric country IDs to include or exclude.
assetId integer
The Asset ID of the track.
assetType AssetTypes
enum
Type of the asset.
Values: Track
mode TerritoryClearanceMode
enum
Availability logic.
Values: Include, Exclude
distributorStoreId integer
ID of the store (DSP) to apply this rule to.
countryIds integer[]
Array of numeric country IDs to include or exclude.

Responses

boolean
PUT /supply-chain/v1/releases/{releaseId}/territories-clearances 
curl -X PUT https://platform.revelator.com/supply-chain/v1/releases/824453/territories-clearances \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "release": [],
  "assets": [
      {
          "assetId": 4546107,
          "assetType": "track",
          "mode": "include",
          "distributorStoreId": 7,
          "countryIds": [
              246
          ]
      }
  ]
}'
Example response 200 
true