An order line item (i.e., a line item within an order,) is the record of one buyer's commitment to purchase one or more identical items from the same listing. In the API, this is also sometimes called a transaction for historical reasons. Many API elements still use that term — the Transaction API object contains the information for one order line item.
Order line items are created when one of the following occurs:
- A buyer wins an auction.
- A buyer uses Buy It Now to commit to purchasing an auction item at the Buy It Now price before any bids are placed.
- A buyer commits to purchase a quantity of 1 or more of an identical item from a fixed-price listing.
- A seller accepts the buyer's Best Offer or counteroffer price.
A single order line item can contain multiple quantity of an identical item purchased at the same time in the same listing. In a multiple-variation listing, the items must be the same variation. When a buyer increases the quantity of a selected item in the shopping cart, a single order line item will be created when the buyer commits to the purchase. However, if a buyer selects an item from a listing, commits to purchase it, then returns to the same listing and selects the identical item to add to the order, the two items will be considered separate order line items.
If a seller offers multiple quantity of a specific item within a fixed-price listing, and multiple buyers purchase those items, that listing will spawn multiple order line items (i.e., one from each buyer).
If a buyer purchases items from different listings by the same seller before paying for them, the seller can group the purchases into the same order which can form the basis for an invoice and each purchase is reflected by an order line item within that order.
Auction listings result in only one order line item, and this occurs either at the end of the listing with a winning bidder, or when the buyer uses the Buy It Now option.
Checkout
Checkout encompasses the period of time between creation of the order line item and the shipping of the item. During the checkout flow, interactions between the seller and the buyer affect data values for the corresponding order line item. For instance, the CheckoutStatus container in order retrieval and order line item retrieval calls has fields that indicate the current status of the order line item:
- Checkout is complete (paid for)
- Checkout is incomplete (not paid for)
The base amount of the order line item is shown in the Transaction.TransactionPrice field and the shipping and handling costs are shown in the Transaction.ActualShippingCost and Transaction.ActualHandlingCost fields.
An order line item is represented by the Transaction object. To retrieve order line item data for a particular listing, call GetItemTransactions. This call can result in the return of zero or multiple order line items.
To retrieve all single and multiple order line items for a seller's account, call GetOrders.
For additional information, refer to Combined invoice.
For additional information pertaining to the retrieval of orders and sale completion, refer to Complete the sale.