Rights

Creating/Editing Contracts

Use the /contract/save resource to add or edit contracts.

Contract Types

↓

The Revelator system provides various contract types, each with a different scheme for specifying which assets are governed by the contract.

• Account Level. Inherits all assets in an account. This is the default contract that is automatically created upon signup.

• Label Level. Inherits all assets under a specified label. The contract licensor object has licensorType set to label and allFutureAssets set to true.

• Artist Level. Inherits all assets for a specified artist; this includes both full releases and individual tracks. The contract licensor object has licensorType set to artist and allFutureAssets set to true.

  Only the primary artist on the asset is used for contract allocation. Contributing artists are ignored, including contributors with the role “primary”.

• Release Level. Includes releases (with all of their tracks) where all the releases are associated with either the same artist or the same label . The contract licensor object has licensorType set to either label or artist and allFutureAssets set to false.

• Track Level. Includes specific tracks (with or without other full releases) where all of the releases and tracks are associated with either the same artist or the same label. The contract licensor object has licensorType set to either label or artist and allFutureAssets set to false.

  When you create track level contracts, you must ensure that every track and the release itself is named on a contract. This means a minimum of 3 contracts for the release: a contract for the special track(s), a contract for the other track(s), and a contract for the release as a whole. The contract for the release itself should name every payee, and you must manually calculate and provide their prorated share of the release for each payee. (The release level contract is relevant when the whole release is downloaded.)

  Note that even though track level contracts support including full releases, we do not recommend that you include the release itself on a contract when some but not all of the tracks are on a track specific contract. This would complicate the processes of calculating the prorated shares.

Assets will always be subject to the most specific contract that includes the asset. In other words, a track level contract will take precedence over a release level contract, a release level contract will take precedence over an artist level contract, etc.

POST /accounting/contract/save

Request Body

Parameter	Type	Description
name required	string	Name of the contract.
contractId optional	integer	Id of the existing contract to edit. When set to 0, creates a new contract. (Default) Inline with the general behavior of this API, patching is not supported. Existing values for omitted parameters will be deleted or overwritten.
contractTypeId required	integer	1 - specifies a Distribution Agreement.
startDate required	string	Date from which the contract is effective, in the format YYYY-MM-DD. This date is for reference only is not enforced when calculating royalties.
expirationDate required	string	Date the contract becomes ineffective, in the format YYYY-MM-DD. If your contract is “in perpetuity”, please indicate 2099-12-31. This date is for reference only is not enforced when calculating royalties.
isActive optional	boolean	Whether the contract is active. Inactive contracts are not used for royalty calculations. Always set as true for new contracts. Defaults to false when editing existing contracts.
contractPayees required	array of objects	Each object represents a payee and details their royalty information. The sum of every non-comission payee’s sharePercentage must equal 100. See Contract Payee Object
contractLicensors required	array including one object*	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, the array should include only one object. For additional licensors, please create a separate contract. See Contract Licensor Object
contractReleases optional	array of objects	Specifies which releases should be included in the contract when only some of the licensors assets are included in the contract. Each object in the array includes a release ID: {"releaseid": <integer>} When all of the licensors assets are included in the contract (includeFutureAssets is true) this parameter is not relevant. When a release is included in this array, every track in the release will automatically be subject to the contract. The release’s individual tracks should not additionally be included in the contractTracks array.
contractTracks optional	array of objects	Specifies which tracks should be included in the contract when only some of the licensors assets are included in the contract, and only when some of the tracks on releases are included in the contract. Each object in the array includes a track ID: {"trackid": <integer>} When all of the licensor’s assets are included in the contract (includeFutureAssets is true) or only complete releases are included in the contract, this parameter is not relevant.
contractTerms required	array of objects	Specifies terms for the contract. See Contract Terms Object
payMechanicals optional	boolean	true - to pay digital mechanicals. Additional attributes are required. false - to not pay digital mechanicals (Default)
mechanicalsTypeId optional 1	integer	Rate type for mechanicals: 1 - % of Sales 2 - Penny Rate 3 - Copyright Law 1Mandatory when 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: true - Full false - Minimum 4Mandatory when mechanicalsTypeId is 3.
mechanicalsRatePercentage optional 4	integer	Rate percent. 4Mandatory when mechanicalsTypeId is 3.

Contract Payee Object

Parameter	Type	Description
sharePercentage optional	integer	For standard payees (non-commission), the percent of the payee revenue that will go to this payee. For commission payees, the percent of the payor revenue that will go to this payee. Defaults to 0
startingBalance optional	integer	The payee’s startingBalance. 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	true - the payee is a commission payee, and will be paid from the payor’s share of the revenue. false - the payee is a standard payee (Default)
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.

Payee Object

Parameter	Type	Description
payeeId optional	integer	ID for an existing payee to associate with the contract. When set to 0, creates a new payee. (Default) A default payee (and default contract) is automatically created upon account creation. you should never create a new payee for a user for whom you have already created a child account.
companyName required	string	Name of the payee. When omitted, defaults to the name of the contact.
contact required	object	Contact information for the payee.
contact.contactId optional	integer	ID for an existing contact. When set to 0, creates a new contact **(Default) **
contact.name optional	string	Name of the contact. Defaults to the companyName.
contact.email optional	string	Contact’s email address. This email is used for sending statement notifications when automatic email notifications are enabled.
currencyCode optional	integer	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	2 - paypal Only necessary when using the Paypal integration for paying the payee.
paymentUserId optional	string	Paypal email address for the payee. Only necessary when using the Paypal integration for paying the payee.

Contract Licensor Object

Parameter	Type	Description
id optional	GUID	ID for an existing contract licensor entity. Not relevant for new contracts. Should be provided when editing existing releases.
licensorType required	integer	Type of licensor that will be used to specify the assets to include in the contract. 1 - artist* 2 - label * For artist licensors, you can only specify assets where the artist is the primary artist on the release level. Therefore, compilations cannot be specified for artist licensors. Additionally, when includeFutureAssets is true, only the primary artist on the asset is considered; contributors are ignored, including contributors with the role “primary”.
licensorId required	string	ID of the licensor. Either an artistId or labelId, according to the licensorType.
includeFutureAssets optional	boolean	true - to include all of the licensor’s current and future assets. When this is true for a licensor, none of the licensor’s assets should be included in the contractReleases or contractTracks arrays. false - to not include all of the licensor’s current and future assets (Default)

Contract Terms Object

Parameter	Type	Description
contractTermsId optional	GUID	ID for an existing contract terms entity. Not relevant for new contracts. Should be provided when editing existing releases.
contractTermsRate optional	integer	Percent of the revenue being paid out to payees. Defaults to 0.
contractTermsRateTypeId required	integer	1 - to calculate the payout with retail 2 - to calculate the payout with wholesale
isCountriesIncluded optional	boolean	true - the countries array provides the only territories included in the contract false - the countries array provides the only territories excluded by the contract, and all other countries are included (Default) To include all territories in the contract, set isCountriesIncluded to false and leave countries empty.
isDistributorStoresIncluded optional	boolean	true - the distributorStores array provides the only services included in the contract false - the distributorStores array provides the only DSPs excluded by the contract, and all other DSPs are included (Default) To include all DSPs in the contract, set isDistributorStoresIncluded to false and leave distributorStores empty.
countries optional	array of integers	IDs for the countries included or excluded from the contract. See isCountriesIncluded. Lookup 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: 1 - Album 2 - Single 4 - EP An empty array will cause all types to be included for the contract. (Default)
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. Download: 101,106, 123 Subscription: 102,104,105,107 Ad supported: 103, 115, 109, 118 Physical: 110 Rental: 116 Digital Licensing: 117 UGC: 120 An empty array will cause all types to be included for the contract. (Default)

Example

Request

{
  "contractId": 0,
  "name": "string",
  "contractTypeId": 0,
  "startDate": "2021-10-26T18:19:07.921Z",
  "expirationDate": "2021-10-26T18:19:07.921Z",
  "mechanicalsTypeId": 0,
  "mechanicalsSalesPercentage": 0,
  "mechanicalsIsFullRate": true,
  "mechanicalsRatePercentage": 0,
  "mechanicalsFixedPennyRate": 0,
  "payMechanicals": true,
  "isActive": true,
  "contractTerms": [
    {
      "contractTermsId": "00000000-0000-0000-0000-000000000000",
      "contractTermsRateTypeId": 0,
      "contractTermsRate": 0,
      "isCountriesIncluded": true,
      "isDistributorStoresIncluded": true,
      "countries": [
        0
      ],
      "deliveryTypes": [
        0
      ],
      "releaseTypes": [
        0
      ],
      "distributorStores": [
        0
      ]
    }
  ],
  "contractReleases": [
    {
      "releaseId": 0,
    }
  ],
  "contractTracks": [
    {
      "trackId": 0
    }
  ],
  "contractLicensors": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "licensorType": "Artist",
      "licensorId": 0,
      "includeFutureAssets": true
    }
  ],
  "contractPayees": [
    {
      "sharePercentage": 0,
      "startingBalance": 0,
      "isCommissionPayee": true,
      "permission": {
        "enterpriseId": 0,
        "enterpriseName": "string",
        "labelId": 0,
        "publisherId": 0,
        "artistId": 0,
        "payeeId": 0,
        "imageId": "00000000-0000-0000-0000-000000000000",
        "name": "string",
        "permissionsAccountId": "00000000-0000-0000-0000-000000000000",
        "isOwner": true,
        "readOnlyContent": true,
        "readOnlyContracts": true,
        "readOnlyFinance": true,
        "readOnlyDistribution": true,
        "readOnlyPromote": true,
        "readOnlyDaily": true,
        "permissionRolesId": 0,
        "isActive": true,
        "email": "string"
      },
      "payee": {
        "paymentProviderId": 0,
        "paymentUserId": "string",
        "currencyCode": "string",
        "contact": {
          "contactId": 0,
          "name": "string",
          "currencyCode": "string",
          "email": "string"
          },
        "payeeId": 0,
        "companyName": "string"
      }
    }
  ]
}