Use the /contract/save
resource to add or edit contracts.
This endpoint requires a token for the parent account.
This endpoint can be used to trigger the creation (or modification) of a contract in the parent account as the result of a user action. General creation of contracts is not an activity appropriate for child account users.
A default contract and payee are automatically created upon account creation; the contract automatically inherits all assets in the account (that are not explicitly covered by a more specific contract), and the default payee is named as the only payee.
Unless otherwise stated, the Revelator API does not support partial updates. When editing an object, the existing values of any omitted parameters will be deleted or overwritten, according to the designated behavior for a null value for that parameter. Consequently, we recommend you always query the object you want to edit and modify the JSON object to avoid partial update problems.
/accounting/contract/save
Parameter | Type | Description |
---|---|---|
name required | string | The name of the contract. |
contractId optional | integer | The ID of an existing contract to edit.
|
startDate required | string | The date from which the contract is effective, in the ISO format YYYY-MM-DD .This date is for reference only and is not enforced when calculating royalties. |
expirationDate required | string | The date the contract becomes ineffective, in the ISO format YYYY-MM-DD . If the contract is “in perpetuity”, please specify 2099-12-31 .This date is for reference only and is not enforced when calculating royalties. |
isActive optional | boolean | Indicates whether the contract is active. Inactive contracts are not used for royalty calculations. Defaults to false when omitted. |
contractPayees required | array of objects | An array of objects, where each object represents a payee and details their royalty information. The sum of sharePercentage for all non-comission payees in the contract must equal 100 . See Contract Payee Object |
contractLicensors required | array including one object* | An array where the single object represents a licensor (artist or label) and provides information for which of the licensor’s assets should be subject to the contract. *Although contractLicensors is an array, it should contain only one object. For additional licensors, please create a separate contract. See Contract Licensor Object |
contractReleases required | array of objects | An array of objects specifying releases explicitly included in the contract. Each object must contain a releaseId : {"releaseId": <integer>} .
includeFutureAssets :contractTracks array. |
contractTracks required | array of objects | An array of objects specifying individual tracks explicitly included in the contract. Each object must contain a tracId : {"trackId": <integer>} .
includeFutureAssets and contractReleases : |
contractTerms required | array of objects | Specifies the terms for the contract. See Contract Terms Object |
payMechanicals optional | boolean |
|
mechanicalsTypeId optional 1 | integer | Rate type for mechanicals:
payMechanicals is true. |
mechanicalsSalesPercentage optional 2 | integer | Sales percent. 2Mandatory when mechanicalsTypeId is 1 . |
mechanicalsFixedPennyRate optional 3 | integer | Penny rate. 3Mandatory when mechanicalsTypeId is 2 . |
mechanicalsIsFullRate optional 4 | boolean | Rate basis:
mechanicalsTypeId is 3 . |
mechanicalsRatePercentage optional 4 | integer | Rate percent. 4Mandatory when mechanicalsTypeId is 3 . |
Parameter | Type | Description |
---|---|---|
sharePercentage optional | integer |
0 |
startingBalance optional | integer | The payee’s starting balance. Defaults to 0 for new payees. Defaults to the current value for existing payees. Cannot be changed for existing payees; the request will fail if the provided value does not match the current value. |
isCommissionPayee optional | boolean |
|
payee required | object | Details of the payee. See Payee Object |
permission optional | object | The permissions the payee has in their payee portal. This parameter sets permissions for the payee to log into the Revelator UI. It is not relevant for most API use cases, and is never relevant when the payee already has a user/child account that was created with the signup resource. |
Parameter | Type | Description |
---|---|---|
payeeId optional | integer | ID for an existing payee to associate with the contract.
Note: You should never create a new payee for a user for whom you have already created a child account. |
companyName required | string | The name of the payee. If omitted, defaults to the name of the associated contact . |
contactId optional | integer | The ID for an existing contact.
|
contact required | object | Contact information for the payee. |
contact.contactId optional | integer | The ID for an existing contact.
|
contact.name optional | string | The name of the contact. Defaults to the companyName . |
contact.email optional | string | The contact’s email address. This email is used for sending statement notifications when automatic email notifications are enabled. |
currencyCode optional | string | The currency code for the payee’s currency. Defaults to the parent account’s currency code. Look up currency codes using the GET /common/lookup/currencies resource. |
paymentProviderId optional | integer |
|
paymentUserId optional | string | The PayPal email address for the payee. Only necessary when using the PayPal integration for paying the payee. |
Parameter | Type | Description |
---|---|---|
id optional | UUID | The ID for an existing contract licensor entity. Not relevant for new contracts. Should be provided when editing existing releases. |
licensorType required | integer | The type of licensor that will be used to specify the assets to include in the contract.
licensorType = 1 ), only assets where the artist is the primary artist on the release level can be specified. Therefore, compilations cannot be directly specified for artist licensors. Additionally, when includeFutureAssets is true , only the primary artist on the asset is considered; other contributors are ignored, including contributors with the role “primary”. |
licensorId required | string | The ID of the licensor. Either an artistId or labelId , corresponding to the licensorType . |
includeFutureAssets optional | boolean |
|
Parameter | Type | Description |
---|---|---|
contractTermsId optional | UUID | The ID for an existing contract terms entity. Not relevant for new contracts. Should be provided when editing existing releases. |
contractTermsRate optional | integer | The percent of the revenue being paid out to payees. Defaults to 0 . |
contractTermsRateTypeId required | integer |
|
isCountriesIncluded optional | boolean |
|
isDistributorStoresIncluded optional | boolean |
|
countries optional | array of integers | IDs for the countries included or excluded from the contract. See isCountriesIncluded . Look up country IDs using the GET /common/lookup/countries resource. |
distributorStores optional | array of integers | IDs for the services included or excluded from the contract. See isDistributorStoresIncluded . Look up DSP IDs using the GET /common/lookup/stores resource. Provide an access token to retrieve only the DSPs enabled for a specific account. |
releaseTypes optional | array of integers | Types of releases to include in the contract terms:
|
deliveryTypes optional | array of integers | Delivery channels to include in the contract terms. Each integer in the array is an ID that represents a delivery type; each channel includes multiple delivery types.
|