Line items

The line item object and the allowed CRUD operations on the related resource endpoint

Line items can be of different types (anything that can have a cost or add a discount and contribute to changing the total order amount):

• skus

• bundles

• shipments

• payment_methods

• gift_cards

• adjustments

• any valid promotion type (e.g. fixed_amount_promotions, percentage_discount_promotions, etc.)

Create a line item if you want to add an SKU or bundle to an order. Other types of line items are automatically created (e.g. to add a shipping cost to the order or apply a discount). The sum of all line item amounts makes the order's total, split into subtotal, taxes, and discount. The order object includes all the data you need. No calculation is required on your application.

Updating quantity

When creating a new line item, set the _update_quantity attribute to true if you want to update the line item quantity (if present) instead of creating a new line item for the same SKU.

Overriding amounts

A line item's unit_amount_cents and options_amount_cents can be assigned a value that differs from the one defined in the market's price list of the associated order or for the SKU option of the associated SKU. To do that, you must use integration API credentials, otherwise the API will return an error.

Sometimes, you can decide not to manage prices within Commerce Layer but use an external service. When adding a line item to an order, set the _external_price attribute to true if you want the line item price to be provided by your external endpoint, instead of Commerce Layer.

If you want to apply a custom shipping cost policy you can set to 0 the unit amount of some of the line items of type shipments. To do that, leverage the dedicated attribute at the market level.

Reserving the stock

You can temporarily reserve the stock associated with a line item of type skus or bundles by setting the _reserve_stock attribute to true. This way, the necessary stock reservations are created and the stock is reserved until their expiration date. If the order isn't placed before the expiration date or the line item is removed, the corresponding reserved stock is released. Once the order is placed the stock is reserved until the order is approved or cancelled. The default stock reservation expiration date (1 hour) can be changed at the inventory model level. Any time you patch a line item passing the _reserve_stock attribute, the expiration date of the associated existing stock reservations is updated.

Stock reservations act on the whole line item quantity. If the available stock is split between different stock locations, multiple stock reservations are created.

For security reasons, only integrations are allowed to change the _reserve_stock attribute of a line item.

Choosing line items that generate subscriptions

Line items that have the frequency attribute populated (with one of the frequency values available for the associated market, as set at the subscription model level) will be used to generate the recurring orders involved in the order subscription process, according to the subscription model's strategy.