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
licensorwithincludeFutureAssets: true. The contract covers every current and future asset of that artist, label, or client, andassetsmust be empty. - By specific assets. List the assets in
assets. Alicensoris optional here; when you send one, itsincludeFutureAssetsmust befalse.
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.
licensorType | licensorId is a… | Covers (with includeFutureAssets: true) |
|---|---|---|
artist | Artist ID | Every asset whose primary artist is the artist. |
label | Label ID | Every asset released under the label. |
enterprise | Client ID | Every 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:
| Coverage | contractLevel |
|---|---|
enterprise licensor with includeFutureAssets | enterpriseLevel |
label licensor with includeFutureAssets | labelLevel |
artist licensor with includeFutureAssets | artistLevel |
| Releases only | releaseLevel |
| Any track or video (with or without releases) | trackLevel |
| YouTube channels | youTubeChannelLevel |
| YouTube videos | youTubeVideoLevel |
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:
| List | Flag | Values |
|---|---|---|
countryIds | isCountriesIncluded | Country IDs, from GET /common/lookup/countries on the V1.0 API. |
distributorStoreIds | isDistributorStoresIncluded | DSP IDs, from GET /common/lookup/stores on the V1.0 API. |
assetTypes | isAssetTypesIncluded | Asset 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.
| Channel | Delivery type IDs |
|---|---|
| Download | 101, 106, 123 |
| Subscription | 102, 104, 105, 107 |
| Ad supported | 103, 109, 115, 118 |
| Physical | 110 |
| Rental | 116 |
| Digital licensing | 117 |
| UGC | 120 |
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 kind | sharePercentage 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
/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 |
Responses
object contractId integer startDate string (date-time) expirationDate string (date-time) isActive boolean name string payorId integer creationDate string (date-time) isRoyaltyTokenContract boolean contractLevel ContractLevel enterpriseLevel, labelLevel, artistLevel, releaseLevel, trackLevel, youTubeChannelLevel, youTubeVideoLevel terms ContractTermDetailsModel[] contractTermsId string contractTermsRate number 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[] deliveryTypeIds integer[] distributorStoreIds integer[] assetTypes AssetTypes[] assets ContractAssetDetailsModel[] assetId integer assetType AssetTypes release, track, video, youTubeChannel, youTubeVideo licensors ContractLicensorDetailsModel[] includeFutureAssets boolean licensorId integer licensorType. licensorType ContractLicensorType artist, label, enterprise payees ContractPayeeDetailsModel[] payeeId integer isCommissionPayee boolean sharePercentage number /royalties/v1/contracts/{contractId} curl -X GET "https://platform.revelator.com/royalties/v1/contracts/311663" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" 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
}
]
} {
"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.
/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): Examples: name, contractId, creationDate, contractLevel |
orderByDescending boolean | Sort in descending order. Defaults to |
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 |
assetType string | Return contracts that have a term whose Examples: release, releaseTrack, track, video, youTubeChannel, youTubeVideo |
isActive boolean | Return only active ( |
licensorId integer | Return contracts whose licensor has this ID. Combine with |
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 ( |
Responses
object pageNumber integer pageSize integer totalItemsCount integer totalPagesCount number items ContractListModel[] contractId integer startDate string (date-time) expirationDate string (date-time) isActive boolean name string creationDate string (date-time) isRoyaltyTokenContract boolean contractLevel ContractLevel enterpriseLevel, labelLevel, artistLevel, releaseLevel, trackLevel, youTubeChannelLevel, youTubeVideoLevel payees ContractPayeeListModel[] payeeId integer sharePercentage number isCommissionPayee boolean companyName string | null email string | null null if none is set./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" 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
}
]
}
]
} {
"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:
| Rule | Error 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.
/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) 1900-01-01. expirationDate string (date-time) startDate. Defaults to 2999-12-30. isActive boolean false, so send true to have the contract used in royalty calculations right away. name * string isRoyaltyTokenContract boolean false. It can only be set on creation. terms * ContractTermDetailsModel[] contractTermsRate * number 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[] [] for none. deliveryTypeIds * integer[] [] for all. distributorStoreIds * integer[] [] for none. assetTypes * AssetTypes[] [] for none.release, releaseTrack, track, video, youTubeChannel, youTubeVideo payees * ContractPayeeDetailsModel[] payeeId * integer isCommissionPayee boolean false. sharePercentage * number licensor ContractLicensorDetailsModel assets is sent. See Coverage above. includeFutureAssets boolean true, assets must be empty. Defaults to false. licensorId * integer licensorType. licensorType * ContractLicensorType artist, label, enterprise assets ContractAssetDetailsModel[] assetId * integer assetType * AssetTypes release, track, video, youTubeChannel, youTubeVideo Responses
object contractId integer startDate string (date-time) expirationDate string (date-time) isActive boolean name string payorId integer creationDate string (date-time) isRoyaltyTokenContract boolean contractLevel ContractLevel enterpriseLevel, labelLevel, artistLevel, releaseLevel, trackLevel, youTubeChannelLevel, youTubeVideoLevel terms ContractTermDetailsModel[] contractTermsId string contractTermsRate number isCountriesIncluded boolean countryIds is an allow list (true) or a block list (false). isDistributorStoresIncluded boolean distributorStoreIds is an allow list (true) or a block list (false). isAssetTypesIncluded boolean assetTypes is an allow list (true) or a block list (false). countryIds integer[] deliveryTypeIds integer[] distributorStoreIds integer[] assetTypes AssetTypes[] assets ContractAssetDetailsModel[] assetId integer assetType AssetTypes licensors ContractLicensorDetailsModel[] licensor, returned as an array of zero or one item. includeFutureAssets boolean licensorId integer licensorType ContractLicensorType payees ContractPayeeDetailsModel[] payeeId integer isCommissionPayee boolean sharePercentage number /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" }
]
}' 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
}
]
} {
"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
isActivedeactivates the contract. SendisActive: trueto keep it active. - Omitting
startDateorexpirationDateresets them to1900-01-01and2999-12-30. terms,payees, andassetsreplace the existing lists. Terms are recreated with newcontractTermsIdvalues, 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:
licensorcan be replaced but not removed. Sending a new licensor replaces the current one. Sendinglicensor: null, or omitting it, keeps the current licensor.isRoyaltyTokenContractcannot 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.
/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 |
Request Body *
object startDate string (date-time) 1900-01-01 if omitted. expirationDate string (date-time) startDate. Reset to 2999-12-30 if omitted. isActive boolean name * string terms * ContractTermDetailsModel[] contractTermsRate * number 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[] [] for none. deliveryTypeIds * integer[] [] for all. distributorStoreIds * integer[] [] for none. assetTypes * AssetTypes[] [] for none.release, releaseTrack, track, video, youTubeChannel, youTubeVideo payees * ContractPayeeDetailsModel[] payeeId * integer isCommissionPayee boolean false. sharePercentage * number licensor ContractLicensorDetailsModel null or omitted keeps the current licensor—it cannot be removed. includeFutureAssets boolean true, assets must be empty. Defaults to false. licensorId * integer licensorType. licensorType * ContractLicensorType artist, label, enterprise assets * ContractAssetDetailsModel[] [] when the licensor includes future assets. assetId * integer assetType * AssetTypes release, track, video, youTubeChannel, youTubeVideo Responses
object contractId integer startDate string (date-time) expirationDate string (date-time) isActive boolean name string payorId integer creationDate string (date-time) isRoyaltyTokenContract boolean contractLevel ContractLevel enterpriseLevel, labelLevel, artistLevel, releaseLevel, trackLevel, youTubeChannelLevel, youTubeVideoLevel terms ContractTermDetailsModel[] contractTermsId string contractTermsRate number isCountriesIncluded boolean countryIds is an allow list (true) or a block list (false). isDistributorStoresIncluded boolean distributorStoreIds is an allow list (true) or a block list (false). isAssetTypesIncluded boolean assetTypes is an allow list (true) or a block list (false). countryIds integer[] deliveryTypeIds integer[] distributorStoreIds integer[] assetTypes AssetTypes[] assets ContractAssetDetailsModel[] assetId integer assetType AssetTypes licensors ContractLicensorDetailsModel[] includeFutureAssets boolean licensorId integer licensorType ContractLicensorType payees ContractPayeeDetailsModel[] payeeId integer isCommissionPayee boolean sharePercentage number /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" }
]
}' 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
}
]
} {
"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”.
/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 |
Request Body *
object isActive * boolean true to activate, false to deactivate. An empty body ({}) is treated as false and deactivates the contract.Responses
object contractId integer /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
}' 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
} {
"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:
assetTypeId | Asset type |
|---|---|
2 | release |
4 | track |
6 | video |
/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 |
Responses
object assetContractStatuses GetAssetContractStatusesResponseDetail[] assetId integer assetTypeId integer 2 release, 4 track, 6 video.2, 4, 6 contractExists boolean assets. Coverage through a licensor is not reflected./royalties/v1/contracts/AssetContractsStatuses/{releaseAssetId} curl -X GET "https://platform.revelator.com/royalties/v1/contracts/AssetContractsStatuses/1725193" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" 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
}
]
} {
"assetContractStatuses": [
{
"assetId": 2910038,
"assetTypeId": 4,
"contractExists": true
},
{
"assetId": 4562313,
"assetTypeId": 6,
"contractExists": false
},
{
"assetId": 1725193,
"assetTypeId": 2,
"contractExists": true
}
]
}