Print this page

Inserting Opportunity Product Schedules (OpportunityLineItemSchedule) via the API

Knowledge Article Number 000199644
Description It is not possible to directly specify an Opportunity Product's (OpportunityLineItem) Schedule's type as either "Divide Amount into multiple installments" or "Repeat Amount for each installment" via the API.  These attributes are implied based on how the OpportunityLineItemSchedule insert file is prepared.
 
It's important to understand the following Opportunity Product schedule (OpportunityLineItemSchedule) behaviors:
  • The Product being set as an Opportunity Product must be enabled for scheduling before you'll be able to insert OpportunityLineItemSchedules in relation to it.  You can follow the steps for Enabling Schedules for all products via the Schedule Setup section or set field visibility and add the Revenue Scheduling Enabled and Quantity Scheduling Enabled fields to your Product page layouts to update them and enable scheduling.
  • If the Product is not enabled you'll encounter an error, "Field Integrity Exception: Unknown (scheduling Not Enabled On Product)" via the API or if you attempt to set a default schedule on a Product via the user interface (UI) you may encounter an "Error: Scheduling is not enabled for this type."
  • The Schedule Type "Divide" splits the amount into multiple installments occurring every week, month, or other period.  "Repeat" repeats the entire amount every week, month, or other period for multiple installments.
  • Default schedules are not applied to Opportunity Product's inserted via the API.  Subsequent inserts are required to apply a Product's default schedule so it's important to note the following default schedule behaviors:
- If you have established default schedules for products they're only applied when user's add the product to an opportunity or quote via the UI.  After Opportunity Products (OpportunityLineItems) are added users can modify the schedules.

- Default schedules use the Opportunity Product's standard Date field as the start date for the schedule's installments.  If the date field is left blank the installment dates begin with the opportunity Close Date.  The default revenue schedule uses the Opportunity Product's total price (Sales Price * Quantity) as the revenue.  Check out Default Product schedule behavior with examples for more detail on how default schedules work.
 

See Also:
Products, Price Books, and Schedules Overview
Enabling Schedules
Product, Price Book, Price Book Entry, and Schedule Fields
SOAP API Developer's Guide - OpportunityLineItemSchedule
Resolution
When establishing Opportunity Product Schedules via the UI selections entered in the available fields provide the attributes that determine exactly how many OpportunityProductSchedule records are automatically created in relation to the Opportunity Product and what data is input into their corresponding fields.

Establishing Schedules UI
 
- The Number of Installments for a Opportunity Product's schedule determines the number of rows you'll need to create in your OpportunityLineItemSchedule insert file.
For the example above, there would be 5 OpportunityLineItem rows in your file.  If your product has both a quantity and revenue schedule with differing installment values the number of rows would be equal to the larger number of installments between the two types.
 
- The Schedule Date for each row is set by adding the Installment Period (Daily, Weekly, Monthly, Quarterly, Yearly) incrementally to the Start Date for the number of installments you've chosen.
For the example above, the first row's Start Date would be 9/1/2014, the second would be 10/1/2014 on through to 1/1/2015 for row 5.
 
Note
If setting both quantity and revenue schedules on insert, the quantity schedule should be used to calculate the total revenue.

Quantity Repeat: Total revenue = ((Quantity * Number of Installments) * Sales Price) and quantity for each schedule row = the quantity set when creating the Opportunity Product populated for the number of installments specified.
Quantity Divide: Total revenue = (Quantity * Sales price) and quantity for each schedule row = (Quantity / Number of Installments) populated for the number of installments specified.

The revenue schedule should then be determined and applied based on the total revenue from above:

Revenue Repeat: Revenue values = Total revenue populated for the number of installments specified.
Revenue Divide: Revenue values = (Total revenue / Number of Installments) populated for the number of installments specified.

It is not possible to set both Quantity and Revenue schedules to repeat.
 
Examples of Quantity schedule types for Opportunity Products totaling a quantity of 100, selections for adding each in the UI, and sample .csv files for illustration.
 
Quantity Schedule Type of Divide amount into multiple installments
Start Date: 9/1/2014
Quantity: 100 (This should be the total amount of Opportunity Products desired)
Schedule Type: Divide Amount into multiple installments
Installment Period: Monthly
Number of Installments: 5
 
Quantity Divide result in UI
 
In this example you'd end up with the following .csv:
 
Description,OpportunityLineItemId,Quantity,Revenue,ScheduleDate,Type
CommentHere,Opportunity Product Id Here(OpportunitylineItemId),20,,2014-09-01,Quantity
CommentHere,Opportunity Product Id Here(OpportunitylineItemId),20,,2014-10-01,Quantity
CommentHere,Opportunity Product Id Here(OpportunitylineItemId),20,,2014-11-01,Quantity
CommentHere,Opportunity Product Id Here(OpportunitylineItemId),20,,2014-12-01,Quantity
CommentHere,Opportunity Product Id Here(OpportunitylineItemId),20,,2015-01-01,Quantity
 
- To determine the Quantity value for each row divide your desired total Opportunity Product's quantity by the number of installments (100/5 = 20).
 
Quantity Schedule Type of Repeat Amount for each installment
Start Date: 9/1/2014
Quantity: 20 (This should be the total Opportunity Products desired divided by the number of installments)
Schedule Type: Repeat Amount for each installment
Installment Period: Monthly
Number of Installments: 5
 
Quantity Repeat result in UI
 
In this example you'd end up with the following .csv:
 
Description,OpportunityLineItemId,Quantity,Revenue,ScheduleDate,Type
CommentHere,Opportunity Product Id Here(OpportunitylineItemId),20,,2014-09-01,Quantity
CommentHere,Opportunity Product Id Here(OpportunitylineItemId),20,,2014-10-01,Quantity
CommentHere,Opportunity Product Id Here(OpportunitylineItemId),20,,2014-11-01,Quantity
CommentHere,Opportunity Product Id Here(OpportunitylineItemId),20,,2014-12-01,Quantity
CommentHere,Opportunity Product Id Here(OpportunitylineItemId),20,,2015-01-01,Quantity
 
- Since this example repeats the amount (quantity) for each OpportunityLineItemSchedule row, the Quantity for all rows/installments should total the desired overall Opportunity Product count.
 
Examples of Revenue schedule types for Opportunity Products with a Total Price of $100, selections for adding each in the UI, and sample .csv file for illustration.
 
Revenue Schedule Type of Divide amount for each installment
Start Date: 9/1/2014
Revenue: 100 (This should be the total amount of Revenue from the Opportunity Products desired)
Schedule Type: Divide Amount for each installment
Installment Period: Monthly
Number of Installments: 5

Revenue Divide result in UI
 
In this example you'd end up with the following .csv:
 
Description,OpportunityLineItemId,Quantity,Revenue,ScheduleDate,Type
CommentHere,Opportunity Product Id Here(OpportunitylineItemId),,20,2014-09-01,Revenue
CommentHere,Opportunity Product Id Here(OpportunitylineItemId),,20,2014-10-01,Revenue
CommentHere,Opportunity Product Id Here(OpportunitylineItemId),,20,2014-11-01,Revenue
CommentHere,Opportunity Product Id Here(OpportunitylineItemId),,20,2014-12-01,Revenue
CommentHere,Opportunity Product Id Here(OpportunitylineItemId),,20,2015-01-01,Revenue
 
- To determine the Revenue value for each row divide your desired total Opportunity Product's revenue by the number of installments (100/5 = 20).
 
Revenue Schedule Type of Repeat amount for each installment
Start Date: 9/1/2014
Revenue: 20 (This should be the total Opportunity Product's revenue that's desired divided by the number of installments)
Schedule Type: Repeat Amount for each installment
Installment Period: Monthly
Number of Installments: 5
 
Revenue Repeat result in UI
 
In this example you'd end up with the following .csv:
 
Description,OpportunityLineItemId,Quantity,Revenue,ScheduleDate,Type
CommentHere,Opportunity Product Id Here(OpportunitylineItemId),,20,2014-09-01,Revenue
CommentHere,Opportunity Product Id Here(OpportunitylineItemId),,20,2014-10-01,Revenue
CommentHere,Opportunity Product Id Here(OpportunitylineItemId),,20,2014-11-01,Revenue
CommentHere,Opportunity Product Id Here(OpportunitylineItemId),,20,2014-12-01,Revenue
CommentHere,Opportunity Product Id Here(OpportunitylineItemId),,20,2015-01-01,Revenue
 
- Since this example repeats the amount (revenue) for each OpportunityLineItemSchedule row, the Revenue for all rows should total the desired Total Price on the Opportunity Product.

Example of Quantity and Revenue Schedule type with quantity of 100 and total revenue of $100

Quantity & Revenue Schedule Type of Divide amount into multiple installments
Start Date: 9/1/2014
Quantity: 5 (This should be the total amount of Opportunity Products desired)
Revenue: 100.00 (This should be the total amount of Revenue from the Opportunity Products desired)
Schedule Types: Divide Amount into multiple installments
Installment Period: Monthly
Number of Installments: 5

Quantity & Revenue divide result in UI

In this example you'd end up with the following .csv:
 
Description,OpportunityLineItemId,Quantity,Revenue,ScheduleDate,Type
CommentHere,Opportunity Product Id Here(OpportunitylineItemId),20,20,2014-09-01,Both
CommentHere,Opportunity Product Id Here(OpportunitylineItemId),20,20,2014-10-01,Both
CommentHere,Opportunity Product Id Here(OpportunitylineItemId),20,20,2014-11-01,Both
CommentHere,Opportunity Product Id Here(OpportunitylineItemId),20,20,2014-12-01,Both
CommentHere,Opportunity Product Id Here(OpportunitylineItemId),20,20,2015-01-01,Both

- The same principals behind quantity and revenue scheduling individually apply when combining them.  Since this example uses divide as the schedule type to determine the Quantity value for each row divide your desired total Opportunity Product's quantity by the number of installments (100/5 = 20) and to determine the Revenue value for each row divide your desired total Opportunity Product's revenue by the number of installments (100/5 = 20).




promote demote