Revelator Logo API

Contracts

A contract defines how the revenue earned by part of your catalog is shared. It answers three questions:

  • Which assets does it cover? Set by its licensor and assets.
  • How much of the revenue is paid out? Set by its terms, which can vary the rate by country, DSP, delivery type, and asset type.
  • Who gets paid? Set by its payees and their shares.

The organization that pays out royalties under a contract is its payor. The payor is taken from your access token; you never send it.

Hybrid workflow: payees are managed on the V1.0 API. Every contract names at least one payee by payeeId, but payee endpoints are not yet available on the V2.0 API. Create and edit payees with POST /accounting/payee/save, and look up their IDs with Retrieving Payees on the V1.0 API. Contracts and payees are shared across both APIs, so a payeeId from the V1.0 API can be used here as-is, and contracts created here are visible to the V1.0 accounting endpoints under the same contractId.


Coverage: Licensor & Assets

A contract covers assets in one of two ways:

  • By licensor, including future assets. Set a licensor with includeFutureAssets: true. The contract covers every current and future asset of that artist, label, or client, and assets must be empty.
  • By specific assets. List the assets in assets. A licensor is optional here; when you send one, its includeFutureAssets must be false.

A contract has at most one licensor. You send it as a single licensor object, and it comes back as a licensors array holding zero or one item—the array shape is kept for compatibility with existing clients.

licensorTypelicensorId is a…Covers (with includeFutureAssets: true)
artistArtist IDEvery asset whose primary artist is the artist.
labelLabel IDEvery asset released under the label.
enterpriseClient IDEvery asset of the client.

When you list assets, each assetType must be the asset’s actual type. A release’s assetId sent as track is rejected as if the asset did not exist. Retrieve the assetId and type from the catalog endpoints—see Understanding Assets & IDs.

The licensor is not checked against the assets. When you send both a licensor and assets, the API verifies that each one exists, but not that the assets belong to the licensor. Make sure they match.

Contract Levels

contractLevel describes how specific a contract is. You don’t send it—the server derives it from the coverage every time the contract is created or updated:

CoveragecontractLevel
enterprise licensor with includeFutureAssetsenterpriseLevel
label licensor with includeFutureAssetslabelLevel
artist licensor with includeFutureAssetsartistLevel
Releases onlyreleaseLevel
Any track or video (with or without releases)trackLevel
YouTube channelsyouTubeChannelLevel
YouTube videosyouTubeVideoLevel

An asset can be covered by several contracts at once—for example, by its artist’s artistLevel contract and by a trackLevel contract that names it. The most specific contract applies, in this order: track, release, artist, label, and finally client. Artist, label, and client contracts therefore act as fallbacks for any asset that is not named on a more specific contract.

Each client has a default enterpriseLevel contract, created automatically, which covers every asset not covered by a more specific contract.

Avoid two active contracts at the same level for the same asset. The API does not prevent you from naming an asset on more than one contract, or from activating them all. But when the same asset is on two or more active contracts at the same level with conflicting terms, the royalty run cannot allocate its revenue, and it stays unallocated until you deactivate or change one of the contracts and reprocess it.


Terms

Terms set the rate: the percentage of revenue, from 0 to 100, that is paid out to the contract’s payees. The payor keeps the rest. Every contract needs at least one term.

A term can be limited to part of the revenue with four filters. Each filter is a list paired with a flag that says whether the list is an allow list or a block list:

ListFlagValues
countryIdsisCountriesIncludedCountry IDs, from GET /common/lookup/countries on the V1.0 API.
distributorStoreIdsisDistributorStoresIncludedDSP IDs, from GET /common/lookup/stores on the V1.0 API.
assetTypesisAssetTypesIncludedAsset types such as release, track, video, youTubeChannel, and youTubeVideo.
deliveryTypeIds—Delivery types. Always an allow list. See Delivery Types.
  • Flag true: the term applies only to the listed values.
  • Flag false: the term applies to everything except the listed values. With an empty list, it applies to everything.

To have a term apply to all revenue, send every flag as false and every list empty.

Send all four lists, even when empty. Each term must include countryIds, deliveryTypeIds, distributorStoreIds, and assetTypes. Omitting one is rejected with “The CountryIds field is required.” (and likewise for the others). Send [] for a list you don’t use.

Delivery Types

deliveryTypeIds limits a term to specific delivery channels. Each channel is made up of several delivery type IDs; send all the IDs of the channels you want. An empty list includes all delivery types.

ChannelDelivery type IDs
Download101, 106, 123
Subscription102, 104, 105, 107
Ad supported103, 109, 115, 118
Physical110
Rental116
Digital licensing117
UGC120

Payees

Payees split the revenue paid out under the contract. Each one has a sharePercentage from 0 to 100, and how it is applied depends on the payee’s kind:

Payee kindsharePercentage is a share of…
Standard (isCommissionPayee: false)The revenue paid out to payees, as set by the term rate.
Commission (isCommissionPayee: true)The payor’s share of the revenue—the part the payor keeps.

The shares of all standard payees must add up to exactly 100. Commission payees are not counted towards that total.

For example, with a term rate of 80, a standard payee at 100, and a commission payee at 10, the standard payee receives 80% of the revenue and the commission payee receives 10% of the remaining 20%.

List each payee once. Sending the same payeeId twice is rejected with “One or more Payees do not exist.”


Activating & Deactivating

Only active contracts are used when royalties are calculated. A contract is created inactive unless you send isActive: true.

startDate and expirationDate are for reference only. They do not activate or deactivate a contract, and they are not checked when royalties are calculated: an active contract past its expirationDate is still used. Only isActive decides.

To switch a contract on or off without changing anything else, use PATCH /royalties/v1/contracts/{contractId}. There is no endpoint to delete a contract: deactivate it instead.


Get Contract

GET /royalties/v1/contracts/{contractId}

Retrieves a single contract with its terms, assets, licensor, and payees.

Path Parameters

Parameter Description
contractId * integer

ID of the contract to retrieve. A contract that does not exist, or does not belong to your organization, returns 400 with "ContractId does not exist".

Responses

object
contractId integer
Unique ID of the contract.
startDate string (date-time)
Date the contract becomes effective.
expirationDate string (date-time)
Date the contract expires.
isActive boolean
Whether the contract is active. Only active contracts are used in royalty calculations.
name string
Display name of the contract.
payorId integer
ID of the payor—the organization that pays out royalties under the contract.
creationDate string (date-time)
When the contract was created.
isRoyaltyTokenContract boolean
Whether the contract is tied to a blockchain royalty token.
contractLevel ContractLevel
How specific the contract is, derived from its coverage. See Contract Levels above.
Examples: enterpriseLevel, labelLevel, artistLevel, releaseLevel, trackLevel, youTubeChannelLevel, youTubeVideoLevel
contractTermsId string
ID of the term. Terms are recreated, with new IDs, every time the contract is updated.
contractTermsRate number
Percentage of the revenue (0–100) paid out to the contract's payees.
isCountriesIncluded boolean
true: the term applies only to countryIds. false: it applies to all countries except countryIds.
isDistributorStoresIncluded boolean
true: the term applies only to distributorStoreIds. false: it applies to all DSPs except distributorStoreIds.
isAssetTypesIncluded boolean
true: the term applies only to assetTypes. false: it applies to all asset types except assetTypes.
countryIds integer[]
Country IDs the term includes or excludes.
deliveryTypeIds integer[]
Delivery type IDs the term applies to. Empty means all. See Delivery Types above.
distributorStoreIds integer[]
DSP IDs the term includes or excludes.
assetTypes AssetTypes[]
Asset types the term includes or excludes.
assetId integer
Asset ID.
assetType AssetTypes
Type of the asset.
Examples: release, track, video, youTubeChannel, youTubeVideo
includeFutureAssets boolean
Whether the contract covers all current and future assets of the licensor.
licensorId integer
ID of the artist, label, or client, depending on licensorType.
licensorType ContractLicensorType
Type of the licensor.
Examples: artist, label, enterprise
payeeId integer
ID of the payee.
isCommissionPayee boolean
Whether the payee is paid a commission from the payor's share instead of a share of the payout.
sharePercentage number
The payee's share (0–100). For standard payees, a share of the revenue paid out; for commission payees, a share of the payor's revenue.
GET /royalties/v1/contracts/{contractId}
curl -X GET "https://platform.revelator.com/royalties/v1/contracts/311663" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Example response 200
{
"contractId": 311663,
"startDate": "2026-01-01T00:00:00",
"expirationDate": "2028-12-31T00:00:00",
"isActive": true,
"name": "Tremolo - Release Contract",
"payorId": 132241,
"creationDate": "2026-10-26T15:42:30.02",
"isRoyaltyTokenContract": false,
"contractLevel": "releaseLevel",
"terms": [
  {
    "contractTermsId": "28d5fcbf-6a1e-4ace-602d-08df3377be9b",
    "contractTermsRate": 80.00,
    "isCountriesIncluded": false,
    "isDistributorStoresIncluded": false,
    "isAssetTypesIncluded": false,
    "countryIds": [],
    "deliveryTypeIds": [],
    "distributorStoreIds": [],
    "assetTypes": []
  },
  {
    "contractTermsId": "89415e8f-ea14-407c-602e-08df3377be9b",
    "contractTermsRate": 70.00,
    "isCountriesIncluded": true,
    "isDistributorStoresIncluded": true,
    "isAssetTypesIncluded": true,
    "countryIds": [877, 879],
    "deliveryTypeIds": [102, 104],
    "distributorStoreIds": [68, 307],
    "assetTypes": ["track"]
  }
],
"assets": [
  {
    "assetId": 1725327,
    "assetType": "release"
  }
],
"licensors": [
  {
    "includeFutureAssets": false,
    "licensorId": 496502,
    "licensorType": "artist"
  }
],
"payees": [
  {
    "payeeId": 147840,
    "isCommissionPayee": true,
    "sharePercentage": 10.00
  },
  {
    "payeeId": 246570,
    "isCommissionPayee": false,
    "sharePercentage": 100.00
  }
]
}

Get Contracts

Lists your organization’s contracts, with filters for payees, assets, licensors, levels, and status. Each item is a summary: it includes the payees, with their company name and email, but not the terms, assets, or licensor. Use GET /royalties/v1/contracts/{contractId} for the full contract.

assetType filters on the terms, not on the assets. It returns contracts that have a term whose assetTypes list contains the value. It does not look at the contract’s assets. For example, assetType=release does not return a release-level contract whose terms all have an empty assetTypes list, but assetType=youTubeChannel returns a client contract that names no assets at all if one of its terms lists youTubeChannel. To find the contracts for specific assets, use assetIds; to find contracts by how specific they are, use contractLevel.

assetIds returns the contracts that name the asset in assets. Artist, label, and client contracts that cover the asset only as a fallback are not included.

GET /royalties/v1/contracts

Retrieves a paginated list of contracts matching the given filters.

Query Parameters

Parameter Description
pageNumber integer

1-based page number. Defaults to 1; values of 0 or less are treated as 1.

pageSize integer

Items per page. Defaults to 50, maximum 204. A value of 0 or less falls back to the default.

orderByProperty string

Sort column (case-sensitive): name, contractId, creationDate, or contractLevel. Any other value is ignored. Without a valid sort column the order is not consistent between pages, so contracts can be skipped or repeated when paging—always set one when paging through results.

Examples: name, contractId, creationDate, contractLevel
orderByDescending boolean

Sort in descending order. Defaults to false.

contractIds integer[]

Return only these contracts.

payeeIds integer[]

Return contracts that include any of these payees.

searchText string

Case-insensitive search on the contract name (partial match) and contract ID.

assetIds integer[]

Return contracts that name any of these assets in assets. Contracts covering an asset only through their licensor are not returned.

assetType string

Return contracts that have a term whose assetTypes list includes this type. Matches the terms, not the contract's assets—see the note above.

Examples: release, releaseTrack, track, video, youTubeChannel, youTubeVideo
isActive boolean

Return only active (true) or inactive (false) contracts. Omit to return both.

licensorId integer

Return contracts whose licensor has this ID. Combine with licensorType to disambiguate between artist, label, and client IDs.

licensorType string

Return contracts whose licensor is of this type.

Examples: artist, label, enterprise
contractLevel string

Return contracts of this level. See Contract Levels above.

Examples: enterpriseLevel, labelLevel, artistLevel, releaseLevel, trackLevel, youTubeChannelLevel, youTubeVideoLevel
name string

Case-insensitive partial match on the contract name.

isRoyaltyTokenContract boolean

Return only royalty token contracts (true) or only other contracts (false). Omit to return both.

Responses

object
pageNumber integer
The current page number in the paginated result set (1-indexed)
pageSize integer
The number of items per page in the paginated result set
totalItemsCount integer
The total number of items available across all pages
totalPagesCount number
The total number of pages available based on the page size
contractId integer
Unique ID of the contract.
startDate string (date-time)
Date the contract becomes effective.
expirationDate string (date-time)
Date the contract expires.
isActive boolean
Whether the contract is active.
name string
Display name of the contract.
creationDate string (date-time)
When the contract was created.
isRoyaltyTokenContract boolean
Whether the contract is tied to a blockchain royalty token.
contractLevel ContractLevel
How specific the contract is. See Contract Levels above.
Examples: enterpriseLevel, labelLevel, artistLevel, releaseLevel, trackLevel, youTubeChannelLevel, youTubeVideoLevel
payeeId integer
ID of the payee.
sharePercentage number
The payee's share (0–100). See Payees above.
isCommissionPayee boolean
Whether the payee is a commission payee.
companyName string | null
The payee's company or display name.
email string | null
The payee's contact email, or null if none is set.
GET /royalties/v1/contracts
curl -X GET "https://platform.revelator.com/royalties/v1/contracts?payeeIds=246570&isActive=true&orderByProperty=creationDate&orderByDescending=true&pageSize=1" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Example response 200
{
"pageNumber": 1,
"pageSize": 1,
"totalItemsCount": 3,
"totalPagesCount": 3,
"items": [
  {
    "contractId": 311663,
    "startDate": "2026-01-01T00:00:00",
    "expirationDate": "2028-12-31T00:00:00",
    "isActive": true,
    "name": "Tremolo - Release Contract",
    "creationDate": "2026-10-26T15:42:30.02",
    "isRoyaltyTokenContract": false,
    "contractLevel": "releaseLevel",
    "payees": [
      {
        "payeeId": 147840,
        "sharePercentage": 10.00,
        "isCommissionPayee": true,
        "companyName": "!STOKED!",
        "email": "[email protected]"
      },
      {
        "payeeId": 246570,
        "sharePercentage": 100.00,
        "isCommissionPayee": false,
        "companyName": "Tremolo Music",
        "email": null
      }
    ]
  }
]
}

Create Contract

Before creating a contract, make sure its payees exist—see the hybrid workflow note at the top of this page.

The request is checked against these rules, and any violation returns 400 Bad Request:

RuleError message
Send a licensor, assets, or both.“Either ContractLicensor or ContractAssets must be provided”
When the licensor includes future assets, assets must be empty.“Assets must be empty when the licensor includes future assets.”
Otherwise, list at least one asset.“At least one asset is required if the licensor does not include future assets.”
The licensor must exist in your organization.“Licensor does not exist.”
Every asset must exist in your organization, with its actual assetType.“One or more Assets do not exist.”
Every payee must exist in your organization, listed once.“One or more Payees do not exist.”
Standard payees’ shares must add up to exactly 100.“The total payees shares must equal 100%.”
Every country, DSP, and delivery type ID in the terms must exist.“CountryId 99999 does not exist” (and likewise for the others)
Term rates must be between 0 and 100.“‘Contract Terms Rate’ must be less than or equal to ‘100’.”
expirationDate must be later than startDate.“‘Expiration Date’ must be greater than …”

Tokenized assets. An asset that is already on a royalty token contract cannot be added to another contract that names it explicitly. This check is skipped when the licensor includes future assets or is of type enterprise.

POST /royalties/v1/contracts

Creates a royalty contract. Returns the full contract and a Location header pointing to it.

Request Body *

object
startDate string (date-time)
Date the contract becomes effective, for reference only. Defaults to 1900-01-01.
expirationDate string (date-time)
Date the contract expires, for reference only. Must be later than startDate. Defaults to 2999-12-30.
isActive boolean
Whether the contract is active. Defaults to false, so send true to have the contract used in royalty calculations right away.
name * string
Display name of the contract.
isRoyaltyTokenContract boolean
Whether the contract is tied to a blockchain royalty token. Defaults to false. It can only be set on creation.
contractTermsRate * number
Percentage of the revenue (0–100) paid out to the contract's payees.
isCountriesIncluded boolean
true: apply only to countryIds. false: apply to all countries except countryIds. Defaults to false.
isDistributorStoresIncluded boolean
true: apply only to distributorStoreIds. false: apply to all DSPs except distributorStoreIds. Defaults to false.
isAssetTypesIncluded boolean
true: apply only to assetTypes. false: apply to all asset types except assetTypes. Defaults to false.
countryIds * integer[]
Country IDs to include or exclude. Retrieved from GET /common/lookup/countries on the V1.0 API. Send [] for none.
deliveryTypeIds * integer[]
Delivery type IDs to apply to. See Delivery Types above. Send [] for all.
distributorStoreIds * integer[]
DSP IDs to include or exclude. Retrieved from GET /common/lookup/stores on the V1.0 API. Send [] for none.
assetTypes * AssetTypes[]
Asset types to include or exclude. Send [] for none.
Examples: release, releaseTrack, track, video, youTubeChannel, youTubeVideo
payeeId * integer
ID of an existing payee in your organization. Payees are managed on the V1.0 API.
isCommissionPayee boolean
Whether the payee is paid a commission from the payor's share. Defaults to false.
sharePercentage * number
The payee's share (0–100). Standard payees' shares must add up to 100.
includeFutureAssets boolean
Cover all current and future assets of the licensor. When true, assets must be empty. Defaults to false.
licensorId * integer
ID of an existing artist, label, or client in your organization, matching licensorType.
licensorType * ContractLicensorType
Type of the licensor.
Examples: artist, label, enterprise
assetId * integer
ID of an existing asset in your organization.
assetType * AssetTypes
The asset's actual type. A mismatch is rejected as if the asset did not exist.
Examples: release, track, video, youTubeChannel, youTubeVideo

Responses

object
contractId integer
Unique ID of the new contract.
startDate string (date-time)
Date the contract becomes effective.
expirationDate string (date-time)
Date the contract expires.
isActive boolean
Whether the contract is active.
name string
Display name of the contract.
payorId integer
ID of the payor, taken from your access token.
creationDate string (date-time)
When the contract was created.
isRoyaltyTokenContract boolean
Whether the contract is tied to a blockchain royalty token.
contractLevel ContractLevel
How specific the contract is, derived from its coverage. See Contract Levels above.
Examples: enterpriseLevel, labelLevel, artistLevel, releaseLevel, trackLevel, youTubeChannelLevel, youTubeVideoLevel
contractTermsId string
ID assigned to the term.
contractTermsRate number
Percentage of the revenue (0–100) paid out to the contract's payees.
isCountriesIncluded boolean
Whether countryIds is an allow list (true) or a block list (false).
isDistributorStoresIncluded boolean
Whether distributorStoreIds is an allow list (true) or a block list (false).
isAssetTypesIncluded boolean
Whether assetTypes is an allow list (true) or a block list (false).
countryIds integer[]
Country IDs the term includes or excludes.
deliveryTypeIds integer[]
Delivery type IDs the term applies to. Empty means all.
distributorStoreIds integer[]
DSP IDs the term includes or excludes.
assetTypes AssetTypes[]
Asset types the term includes or excludes.
assetId integer
Asset ID.
assetType AssetTypes
Type of the asset.
includeFutureAssets boolean
Whether the contract covers all current and future assets of the licensor.
licensorId integer
ID of the artist, label, or client.
licensorType ContractLicensorType
Type of the licensor.
payeeId integer
ID of the payee.
isCommissionPayee boolean
Whether the payee is a commission payee.
sharePercentage number
The payee's share (0–100).
POST /royalties/v1/contracts
curl -X POST "https://platform.revelator.com/royalties/v1/contracts" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "name": "Tremolo - Release Contract",
  "startDate": "2026-01-01T00:00:00Z",
  "expirationDate": "2028-12-31T00:00:00Z",
  "isActive": true,
  "terms": [
    {
      "contractTermsRate": 80,
      "isCountriesIncluded": false,
      "isDistributorStoresIncluded": false,
      "isAssetTypesIncluded": false,
      "countryIds": [],
      "deliveryTypeIds": [],
      "distributorStoreIds": [],
      "assetTypes": []
    },
    {
      "contractTermsRate": 70,
      "isCountriesIncluded": true,
      "isDistributorStoresIncluded": true,
      "isAssetTypesIncluded": true,
      "countryIds": [877, 879],
      "deliveryTypeIds": [102, 104],
      "distributorStoreIds": [68, 307],
      "assetTypes": ["track"]
    }
  ],
  "payees": [
    { "payeeId": 246570, "sharePercentage": 100, "isCommissionPayee": false },
    { "payeeId": 147840, "sharePercentage": 10, "isCommissionPayee": true }
  ],
  "licensor": { "licensorId": 496502, "licensorType": "artist", "includeFutureAssets": false },
  "assets": [
    { "assetId": 1725327, "assetType": "release" }
  ]
}'
Example response 201
{
"contractId": 311663,
"startDate": "2026-01-01T00:00:00Z",
"expirationDate": "2028-12-31T00:00:00Z",
"isActive": true,
"name": "Tremolo - Release Contract",
"payorId": 132241,
"creationDate": "2026-10-26T15:42:30.0214627Z",
"isRoyaltyTokenContract": false,
"contractLevel": "releaseLevel",
"terms": [
  {
    "contractTermsId": "28d5fcbf-6a1e-4ace-602d-08df3377be9b",
    "contractTermsRate": 80.00,
    "isCountriesIncluded": false,
    "isDistributorStoresIncluded": false,
    "isAssetTypesIncluded": false,
    "countryIds": [],
    "deliveryTypeIds": [],
    "distributorStoreIds": [],
    "assetTypes": []
  },
  {
    "contractTermsId": "89415e8f-ea14-407c-602e-08df3377be9b",
    "contractTermsRate": 70.00,
    "isCountriesIncluded": true,
    "isDistributorStoresIncluded": true,
    "isAssetTypesIncluded": true,
    "countryIds": [877, 879],
    "deliveryTypeIds": [102, 104],
    "distributorStoreIds": [68, 307],
    "assetTypes": ["track"]
  }
],
"assets": [
  {
    "assetId": 1725327,
    "assetType": "release"
  }
],
"licensors": [
  {
    "includeFutureAssets": false,
    "licensorId": 496502,
    "licensorType": "artist"
  }
],
"payees": [
  {
    "payeeId": 246570,
    "isCommissionPayee": false,
    "sharePercentage": 100
  },
  {
    "payeeId": 147840,
    "isCommissionPayee": true,
    "sharePercentage": 10
  }
]
}

Update Contract

This is a full replace, not a merge. Every field you omit is reset, not left unchanged:

  • Omitting isActive deactivates the contract. Send isActive: true to keep it active.
  • Omitting startDate or expirationDate resets them to 1900-01-01 and 2999-12-30.
  • terms, payees, and assets replace the existing lists. Terms are recreated with new contractTermsId values, even if you send the existing IDs.

Read the contract first with GET /royalties/v1/contracts/{contractId}, change what you need, and send the whole contract back.

The request is validated with the same rules as Create Contract, and contractLevel is derived again from the new coverage. Two fields behave differently:

  • licensor can be replaced but not removed. Sending a new licensor replaces the current one. Sending licensor: null, or omitting it, keeps the current licensor.
  • isRoyaltyTokenContract cannot be changed. It is not part of this request and is ignored if sent.

assets is required on update: send [] when the licensor includes future assets.

PUT /royalties/v1/contracts/{contractId}

Replaces a contract's data in full and returns the updated contract.

Path Parameters

Parameter Description
contractId * integer

ID of the contract to update. A contract that does not exist, or does not belong to your organization, returns 400 with "ContractId does not exist".

Request Body *

object
startDate string (date-time)
Date the contract becomes effective, for reference only. Reset to 1900-01-01 if omitted.
expirationDate string (date-time)
Date the contract expires, for reference only. Must be later than startDate. Reset to 2999-12-30 if omitted.
isActive boolean
Whether the contract is active. Omitting it deactivates the contract.
name * string
Display name of the contract.
contractTermsRate * number
Percentage of the revenue (0–100) paid out to the contract's payees.
isCountriesIncluded boolean
true: apply only to countryIds. false: apply to all countries except countryIds. Defaults to false.
isDistributorStoresIncluded boolean
true: apply only to distributorStoreIds. false: apply to all DSPs except distributorStoreIds. Defaults to false.
isAssetTypesIncluded boolean
true: apply only to assetTypes. false: apply to all asset types except assetTypes. Defaults to false.
countryIds * integer[]
Country IDs to include or exclude. Retrieved from GET /common/lookup/countries on the V1.0 API. Send [] for none.
deliveryTypeIds * integer[]
Delivery type IDs to apply to. See Delivery Types above. Send [] for all.
distributorStoreIds * integer[]
DSP IDs to include or exclude. Retrieved from GET /common/lookup/stores on the V1.0 API. Send [] for none.
assetTypes * AssetTypes[]
Asset types to include or exclude. Send [] for none.
Examples: release, releaseTrack, track, video, youTubeChannel, youTubeVideo
payeeId * integer
ID of an existing payee in your organization. Payees are managed on the V1.0 API.
isCommissionPayee boolean
Whether the payee is paid a commission from the payor's share. Defaults to false.
sharePercentage * number
The payee's share (0–100). Standard payees' shares must add up to 100.
includeFutureAssets boolean
Cover all current and future assets of the licensor. When true, assets must be empty. Defaults to false.
licensorId * integer
ID of an existing artist, label, or client in your organization, matching licensorType.
licensorType * ContractLicensorType
Type of the licensor.
Examples: artist, label, enterprise
assetId * integer
ID of an existing asset in your organization.
assetType * AssetTypes
The asset's actual type. A mismatch is rejected as if the asset did not exist.
Examples: release, track, video, youTubeChannel, youTubeVideo

Responses

object
contractId integer
Unique ID of the contract.
startDate string (date-time)
Date the contract becomes effective.
expirationDate string (date-time)
Date the contract expires.
isActive boolean
Whether the contract is active.
name string
Display name of the contract.
payorId integer
ID of the payor, taken from your access token.
creationDate string (date-time)
When the contract was created. Not changed by updates.
isRoyaltyTokenContract boolean
Whether the contract is tied to a blockchain royalty token. Not changed by updates.
contractLevel ContractLevel
How specific the contract is, derived again from the updated coverage. See Contract Levels above.
Examples: enterpriseLevel, labelLevel, artistLevel, releaseLevel, trackLevel, youTubeChannelLevel, youTubeVideoLevel
contractTermsId string
New ID assigned to the term.
contractTermsRate number
Percentage of the revenue (0–100) paid out to the contract's payees.
isCountriesIncluded boolean
Whether countryIds is an allow list (true) or a block list (false).
isDistributorStoresIncluded boolean
Whether distributorStoreIds is an allow list (true) or a block list (false).
isAssetTypesIncluded boolean
Whether assetTypes is an allow list (true) or a block list (false).
countryIds integer[]
Country IDs the term includes or excludes.
deliveryTypeIds integer[]
Delivery type IDs the term applies to. Empty means all.
distributorStoreIds integer[]
DSP IDs the term includes or excludes.
assetTypes AssetTypes[]
Asset types the term includes or excludes.
assetId integer
Asset ID.
assetType AssetTypes
Type of the asset.
includeFutureAssets boolean
Whether the contract covers all current and future assets of the licensor.
licensorId integer
ID of the artist, label, or client.
licensorType ContractLicensorType
Type of the licensor.
payeeId integer
ID of the payee.
isCommissionPayee boolean
Whether the payee is a commission payee.
sharePercentage number
The payee's share (0–100).
PUT /royalties/v1/contracts/{contractId}
curl -X PUT "https://platform.revelator.com/royalties/v1/contracts/311663" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "name": "Tremolo - Release Contract",
  "startDate": "2026-01-01T00:00:00Z",
  "expirationDate": "2028-12-31T00:00:00Z",
  "isActive": true,
  "terms": [
    {
      "contractTermsRate": 75,
      "isCountriesIncluded": false,
      "isDistributorStoresIncluded": false,
      "isAssetTypesIncluded": false,
      "countryIds": [],
      "deliveryTypeIds": [],
      "distributorStoreIds": [],
      "assetTypes": []
    }
  ],
  "payees": [
    { "payeeId": 246570, "sharePercentage": 100, "isCommissionPayee": false }
  ],
  "licensor": { "licensorId": 496502, "licensorType": "artist", "includeFutureAssets": false },
  "assets": [
    { "assetId": 1725327, "assetType": "release" },
    { "assetId": 2911015, "assetType": "track" }
  ]
}'
Example response 200
{
"contractId": 311663,
"startDate": "2026-01-01T00:00:00",
"expirationDate": "2028-12-31T00:00:00",
"isActive": true,
"name": "Tremolo - Release Contract",
"payorId": 132241,
"creationDate": "2026-10-26T15:42:30.02",
"isRoyaltyTokenContract": false,
"contractLevel": "trackLevel",
"terms": [
  {
    "contractTermsId": "056dd571-1c31-41d5-602f-08df3377be9b",
    "contractTermsRate": 75.00,
    "isCountriesIncluded": false,
    "isDistributorStoresIncluded": false,
    "isAssetTypesIncluded": false,
    "countryIds": [],
    "deliveryTypeIds": [],
    "distributorStoreIds": [],
    "assetTypes": []
  }
],
"assets": [
  {
    "assetId": 1725327,
    "assetType": "release"
  },
  {
    "assetId": 2911015,
    "assetType": "track"
  }
],
"licensors": [
  {
    "includeFutureAssets": false,
    "licensorId": 496502,
    "licensorType": "artist"
  }
],
"payees": [
  {
    "payeeId": 246570,
    "isCommissionPayee": false,
    "sharePercentage": 100
  }
]
}

Update Contract Status

Activates or deactivates a contract without changing anything else.

A contract can only be activated when it covers something: its licensor includes future assets, or it names at least one asset. Otherwise, activation is rejected with “Cannot reactivate a contract without licensors or assets associated with it”.

PATCH /royalties/v1/contracts/{contractId}

Sets whether a contract is active.

Path Parameters

Parameter Description
contractId * integer

ID of the contract to update. A contract that does not exist, or does not belong to your organization, returns 400 with "ContractId does not exist".

Request Body *

object
isActive * boolean
The new status: true to activate, false to deactivate. An empty body ({}) is treated as false and deactivates the contract.

Responses

object
contractId integer
ID of the updated contract.
PATCH /royalties/v1/contracts/{contractId}
curl -X PATCH "https://platform.revelator.com/royalties/v1/contracts/311663" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "isActive": false
}'
Example response 200
{
"contractId": 311663
}

Get Asset Contract Statuses

Checks which assets of a release are named on a contract: the release itself, each of its tracks, and each of its videos. Use it to find the assets that still need a contract before distribution or a royalty run.

Fallback contracts are not counted. contractExists is true when the asset is named in the assets of at least one contract. An asset that reports false is still paid out under its artist, label, or client contract—see Contract Levels.

The asset’s type is returned as a numeric assetTypeId, unlike the string assetType used elsewhere on this page:

assetTypeIdAsset type
2release
4track
6video
GET /royalties/v1/contracts/AssetContractsStatuses/{releaseAssetId}

Reports, for a release and each of its tracks and videos, whether a contract names the asset.

Path Parameters

Parameter Description
releaseAssetId * integer

Asset ID of the release (not its releaseId). Must be a release in your organization—any other asset returns 400 with "The requested release does not exist".

Responses

object
assetId integer
Asset ID of the release, track, or video.
assetTypeId integer
Numeric type of the asset: 2 release, 4 track, 6 video.
Examples: 2, 4, 6
contractExists boolean
Whether at least one contract names this asset in its assets. Coverage through a licensor is not reflected.
GET /royalties/v1/contracts/AssetContractsStatuses/{releaseAssetId}
curl -X GET "https://platform.revelator.com/royalties/v1/contracts/AssetContractsStatuses/1725193" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Example response 200
{
"assetContractStatuses": [
  {
    "assetId": 2910038,
    "assetTypeId": 4,
    "contractExists": true
  },
  {
    "assetId": 4562313,
    "assetTypeId": 6,
    "contractExists": false
  },
  {
    "assetId": 1725193,
    "assetTypeId": 2,
    "contractExists": true
  }
]
}