Create a cost definition

POST /rights/v1/costDefinitions

Purpose

This POST call enables creating a cost definition with or without amortizations.

Mandatory fields

A costDefinitionId, which is the external reference, is not mandatory for creating a cost definition.

It is mandatory to indicate the owner of the cost. In WHATS'ON, the owner can be a right group or a contract entry. For now, only right group owners are allowed. Therefore, the following 3 fields need to be provided:

contractId
contentId
exploitationRightId

Other mandatory fields are:

costModel: This is the model of the cost in WHATS'ON. Currently, only Flat fee cost is supported.
currency: This should be filled with the API reference of the drop-down value corresponding to the currency. To get all available values, use the GET call for currency.
amount: This can be a rounded number or with decimals. When defining decimals, only periods are allowed, no commas.
financialStockPartition: This is only mandatory when the owner of the cost is part of a contract that has a status that puts it into financial stock. When this is the case, an error will be thrown and the field should be filled with the API reference of the partition. To get all possible values, use the designated GET call, see Retrieve cost-related drop-down.
costChannel: This is only mandatory when the WHATS'ON Return on investment module is active and the value cannot be inherited from the contract. This should be filled with the API reference of the drop-down value corresponding to the cost channel. To get all available values, use the GET call for cost channels, see Retrieve cost-related drop-down.

Optional fields

costGroup: This should be filled with the API reference of the drop-down value corresponding to the cost group. To get all available keys, use the GET call for cost groups, see Retrieve cost-related drop-down. If it is not filled, it will be set to the default value of the drop-down list.
exchangeRate: This can only to be filled if the currency is not the default currency. In that case, this cost is considered as hedged. When the currency is the default one, it will be ignored.
creditor: This can only be passed when the cost group differs from Distributor. If not, an error will be thrown. If it is different, the external reference of an existing company should be given. If it is left empty, the distributor of the contract will be entered.
costChannel: see above
financialStockPartition: see above
numberOfEpisodes: If this is not filled, the actual number of episodes of the series will be entered in the field Expected number of episodes. When it is filled, it cannot be lower than the number of episodes in the exploitation right group.
remarks: This is a regular text field

Amortizations

The fields above can be used to create a basic cost definition. It is also possible to create a cost definition with amortizations.

Available fields

amortizationDefinition: This is mandatory when amortizations are provided.
amortizationType: This is mandatory when an amortization definition is added. This should be filled with the ID of the amortization type. To get those IDs, use the GET call for supported amortization definitions, see Retrieve cost-related drop-down. Only 4 types are supported right now:
- Amortization per run in percentage
- Nominal amortization per run
- Straight-line amortization
- No amortizations

Amortization per run in percentage

Example:

    "amortizationDefinition": {
        "amortizationType": "Run based percentage",
        "amortizationRule": "80/19/1"
    }

amortizationRule: This should be filled with the API reference of the drop-down value corresponding to the rule. To get all available values, use the GET call for amortization rules, see Retrieve cost-related drop-down.
- If an unknown or empty amortization rule is sent, an error is thrown.
- When the amortization rule is not sent, and an amortization lookup table is set in the site preferences, then a rule will be entered based on the lookup table. If none is set, an error is thrown.

Nominal amortization per run

Example:

    "amortizationDefinition": {
        "amortizationType": "Run based value",
        "numberOfRuns": "2",
        "values": [
                "200","200"
            ],
        "amortizations": [
           {
                "amount": "1500",
                "runNumber": "1",
                "episodeNumber": "1"
           },
           {
                "amount": "500",
                "runNumber": "2",
                "episodeNumber": "2"
           }
        ]

numberOfRuns: This is mandatory for this amortization type. It should represent the number of runs on which an amortization should be created.
values: This is mandatory for this amortization type.
- There should be as many values in the array as there are number of runs. If not, an error is thrown.
- The total amount of the values should not be higher than the total amount of the cost. If not, an error should be thrown.
amortizations: This is optional for this amortization type. This cannot be passed without the previous fields or an error is thrown. If no table with amortizations is communicated, WHATS'ON will generate an amortization table automatically based on the passed definition.
- runNumber: This is optional. It is the run number for which an amount to be amortized should be communicated. A run number cannot be used more than once.
- amount: This is mandatory when a run number is specified. It is the amount of the nominal amortization for a specific run, for a specific episode. The sum cannot be higher than the cost.
- episodeNumber: This is optional. It is the episode number for which the amortization should be defined. This should only be added for series or else no amortizations will be created. There should be as many amortizations as there are runs x episode numbers.
  - For example, if there are 10 episodes and 1 run should be amortized, then there should be 10 amortizations.

Straight-line amortization

Example:

    "amortizationDefinition": {
        "amortizationType": "Straight line",
        "startDate": "2021-02-05",
        "endDate": "2022-02-05",
        "frequency": "monthly",
        "monthDay": "30"
        }

startDate: This is mandatory and has to be in the format YYYY-MM-DD.
endDate: This is mandatory and has to be in the format YYYY-MM-DD.
frequency: This is mandatory and can one of the following values:
- daily
- weekly: when this is chosen, the field weekDay also becomes mandatory and can have the values Monday, Tuesday, Wednesday, ...
- monthly: when this is chosen, the field monthDay also becomes mandatory and can have the values 1, 2, 3... and lastDay. The last day of the month will then be rounded based on the selected month. For example, entering 31 for February will become 28 or 29.
- quarterly: when this is chosen, the field quarterMonth also becomes mandatory and can have the values first, second or third. The monthDay also becomes mandatory, see above.

No amortizations

Example:

    "amortizationDefinition": {
        "amortizationType": "noDepreciations"
        }

Complete call without amortizations

POST /rights/v1/costDefinitions/

{
    "owner": {
        "exploitationRightId": "<string>"
    },
    "contractEntry": {
    "contractId": "string",
    "contentId": "string"
    },
    "costDefinitionId": "<string>",
    "costModel": "<string>",
    "costGroup": "<string>",
    "cost": {
        "amount": "<double>",
        "currency": "<string>",
        "exchangeRate": "<double>"
    },
    "costChannel": "<string>",
    "creditor": "<string>",
    "remarks": "<string>",
    "financialStockPartition": "<string>",
    "numberOfEpisodes": "<integer>"
}

Complete cost definition call with amortizations

{
    "owner": {
        "exploitationRightId": "<string>"
    },
    "contractEntry": {
    "contractId": "string",
    "contentId": "string"
    },
    "costDefinitionId": "<string>",
    "costModel": "<string>",
    "costGroup": "<string>",
    "cost": {
        "amount": "<double>",
        "currency": "<string>",
        "exchangeRate": "<double>"
    },
    "costChannel": "<string>",
    "creditor": "<string>",
    "remarks": "<string>",
    "financialStockPartition": "<string>",
    "numberOfEpisodes": "<integer>",
    "amortizationDefinition": {
        "amortizationType": "<string>",
        "numberOfRuns": "<integer>",
        "values": [
                "<integer>", "<integer>"
            ],
        "amortizations": [
            {
               "amount": "<double>",
               "runNumber": "<integer>",
               "episodeNumber": "<integer>"
            },
            {
               "amount": "<double>",
               "runNumber": "<integer>",
               "episodeNumber": "<integer>"
            }
        ]
    }
}

Response

{
    "timestamp": "2021-01-08T13:22:07Z",
    "concept": "CostDefinition",
    "costDefinitionId": "4683260000"
}