OpportunityLineItem

Supported Calls

create(), update(), delete(), query(), retrieve(), getDeleted(), getUpdated(), describeSObjects(), upsert()

Special Access Rules

The user must have the “Edit” permissions on Opportunity records in order to create() or update() opportunity line items on an opportunity.

Fields

Field	Field Type	Field Properties	Description
CurrencyIsoCode	picklist	Filter Restricted picklist	Available only for organizations with the multicurrency feature enabled. Contains the ISO code for any currency allowed by the organization. If the organization has multicurrency enabled, and a Pricebook2 is specified on the parent opportunity (i.e., the Pricebook2Id field is not blank on the opportunity referenced by this object’s OpportunityId), then the value of this field must match the currency of the CurrencyIsoCode field on the PricebookEntry objects that are associated with this object.
Description	string	Create Filter Nillable Update	Text description of the opportunity line item. Limit: 255 characters.
HasQuantitySchedule	boolean	Defaulted on create Filter	Read-only. Indicates whether a quantity schedule has been created for this object (`true`) or not (`false`).
HasRevenueSchedule	boolean	Defaulted on create Filter	Read-only. Indicates whether a revenue schedule has been created for this object (`true`) or not (`false`). If this object has a revenue schedule, the Quantity and TotalPrice fields cannot be updated. In addition, the Quantity field cannot be updated if this object has a quantity schedule. The API ignores any attempt to update these fields. The `update()` call will not be rejected but the updated values will be ignored.
IsDeleted	boolean	Defaulted on create Filter	Indicates whether the record has been moved to the Recycle Bin (`true`) or not (`false`). Label is Deleted. This flag is only set to `true` when the parent opportunity is deleted, and is set to `false` again if the opportunity is undeleted. Deleting an OpportunityLineItem directly via the API completely removes it, and it cannot be undeleted.
ListPrice	currency	Filter Nillable	Corresponds to the UnitPrice on the PricebookEntry that is associated with this line item, which can be in the standard pricebook or a custom pricebook. A client application can use this information to show whether the unit price (or sales price) of the line item differs from the pricebook entry list price.
OpportunityId	reference	Create Filter	Required. ID of the associated Opportunity.
PriceBookEntryId	reference	Create Filter Nillable	Required. ID of the associated PricebookEntry. Exists only for those organizations that have Products enabled as a feature. You can specify values for either this field or ProductId, but not both. For this reason, both fields are declared nillable.
ProductId	reference	Create Filter Nillable	ID of the associated Product object. This field has been deprecated as of version 3.0 and is only provided for backward compatibility. The Product object is unavailable beginning with version 8.0. Use the PriceBookEntryId field instead, specifying the ID of the PricebookEntry object.
Quantity	double	Create Filter Update	Read-only if this record has a quantity schedule, a revenue schedule, or both a quantity and a revenue schedule.
ServiceDate	date	Create Filter Nillable Update	Date when the product revenue will be recognized and the product quantity will be shipped. Whether this value is used by customizable forecasting depends upon the Forecast Date setting for the organization: Opportunity Close Date—ServiceDate is ignored. Product Date—ServiceDate is used if not null. Schedule Date—ServiceDate is used if not null and there are no revenue schedules present for this line item, that is, there are no OpportunityLineItemSchedule objects with a field Type value of Revenue that are children of this object.
SortOrder	int	Filter Nillable	Number indicating the sort order selected by the user. Client applications can use this to match the sort order in Salesforce.
TotalPrice	currency	Create Defaulted on create Filter Nillable Update	This field is deprecated but exists in order to provide backward compatibility. It represents the total price of the OpportunityLineItem. If you do not specify UnitPrice, this field is required. In a given `update()` call, you can change either this value or the UnitPrice, but not both at the same time. This field is nillable, but you cannot set both TotalPrice and UnitPrice to null in the same `update()` call. To insert the TotalPrice for an opportunity line item via the API (given only a unit price and the quantity), calculate this field as the unit price multiplied by the quantity. This field is read-only if the opportunity line item has a revenue schedule. If the opportunity line item does not have a schedule or only has quantity schedule, this field can be updated.
UnitPrice	currency	Create Defaulted on create Filter Nillable Update	This field or TotalPrice is required, you cannot specify both. The unit price for this opportunity line item. In the Salesforce user interface, this field’s value is calculated by dividing the total price of the opportunity line item by the quantity listed for that line item. Label is Sales Price.

Usage

An Opportunity can have OpportunityLineItems only if the Opportunity has a Pricebook2. An OpportunityLineItem must correspond to a Product2 that is listed in the opportunity's Pricebook2. For information about inserting OpportunityLineItem for an opportunity that does not have an associated Pricebook2 or any existing line items, see Effects on Opportunities.

This object is defined only for those organizations that have products enabled as a feature. If the organization does not have the products feature, this object does not appear in the describeGlobal() call, and you cannot use describeSObjects() or query() with the OpportunityLineItem object.

For a visual diagram of the relationships between OpportunityLineItem and other objects, see Product and Schedule Objects.

Note

If multicurrency option has been enabled, the CurrencyIsoCode field will be present. It cannot be modified, and is always set to the value of the CurrencyIsoCode of the parent Opportunity. For more information about CurrencyIsoCode fields, see Currency Field Type.

Effects on Opportunities

Opportunities that have associated OpportunityLineItems are affected in the following ways:

Creating an OpportunityLineItem increments the Opportunity Amount value by the TotalPrice of the OpportunityLineItem. Additionally, inserting an OpportunityLineItem increments the ExpectedRevenue on the opportunity by the TotalPrice times the opportunity Probability.
The Opportunity Amount becomes a read-only field when the opportunity has line items. The API ignores any attempt to update this field on an opportunity with line items. The update() call will not be rejected, but the updated value will be ignored.
You cannot update the PricebookId field or the CurrencyIsoCode field on the opportunity if line items exist. The API rejects any attempt to update these fields on an opportunity with line items.
When you create() or update() an OpportunityLineItem, the API verifies that the line item corresponds to a PricebookEntry in the Pricebook2 that is associated with the opportunity. If the opportunity does not have an associated Pricebook2, the API automatically sets the pricebook on the opportunity if the line item corresponds to a PricebookEntry in an active Pricebook2, and if the PricebookEntry has a CurrencyIsoCode field that matches the CurrencyIsoCode field of the opportunity. If the Pricebook2 is not active or the CurrencyIsoCode fields do not match, an error is returned.
The Opportunity HasOpportunityLineItem field is set to true when an OpportunityLineItem is inserted for that Opportunity.