About recurring service contract entity relationships
A Recurring Service type contract can have one or more associated Services (ContractService) or Service Bundles (ContractServiceBundle). The REST API presents four additional entities related to ContractService or ContractServiceBundle entities: ContractServiceAdjustment, ContractServiceBundleAdjustment, ContractServiceUnit, and ContractServiceBundleUnit.
NOTE The ContractService and ContractServiceBundle entities perform the same function for Services and Service Bundles associated with a contract. This is true for ContractServiceAdjustments and ContractServiceBundleAdjustments, and for ContractServiceUnits and ContractServiceBundleUnits.
The ContractService entity describes the association between an Autotask Service and a Recurring Service type Contract. It can specify an adjusted price for the service for that contract.
For example, the Autotask implementation has a service named Desktop Maintenance with a standard monthly cost of $20 per unit. A Desktop Maintenance service unit covers one workstation. When you add Desktop Maintenance to a Recurring Service Contract, the ContractService entity associates the Desktop Maintenance service with the contract and, if applicable, specifies an adjusted price for that contract. It does not specify how many units of the service the contract includes.
NOTE The ContractService entity is not required to add a Service to a Recurring Service contract. When the REST API creates a ContractServiceAdjustment, it looks for the appropriate ContractService and, if it does not find it, the API creates one.
Once the Desktop Maintenance service is associated with a Recurring Service contract, the ContractServiceAdjustment entity describes how many units of the Desktop Maintenance service should be added to or removed from the Recurring Service contract and specifies an effective date. There can be multiple ContractServiceAdjustments for a ContractService entity over the life of the contract as units are added or removed from the contract.
For example, if the customer wants Desktop Maintenance for each of their ten workstations, a ContractServiceAdjustment sets the number of Desktop Maintenance service units for the Recurring Service contract to ten, effective at the contract start date. If the customer later wants to cover two more workstations, the ContractServiceAdjustment entity specifies an adjustment of plus two units and designates the date that the service becomes effective for the two additional workstations.
A ContractServiceUnit entity returns the information needed for billing for services added to a recurring service contract. It describes how many units of a Service were associated with a contract for a specific date range. The start and end dates for the date range represent one of two events: a contract period type break (for example, a Monthly type contract period has a period break date at the end of each month) or an adjustment to the number of units associated with the contract.
For example, the Customer’s Recurring Service contract has a Period type of monthly and begins on January 1. The Desktop Monthly service is associated with the contract and has ten units of the service added with an effective date equal to the contract start date. One ServiceContractUnit with ten Desktop Maintenance service units generates for January 1 through January 31, another for February 1 through February 28, and so on for the duration of the contract OR until the number of units changes.
If two additional units are added with an effective date of March 1, the only change for the ContractServiceUnit for March 1 through March 31 will be the number of units. If the effective date is within the month, for example, on March 10, one ContractServiceUnit is generated with a date range of March 1 through March 9 for ten units of the service. Another ServiceContractUnit generates for March 10 through March 31 for twelve units of the service. The next ServiceContractUnit will represent April 1 through April 30 with twelve units of service, unless the number of units changes in April.
