Carts and Orders overview

Line Items and Custom Line Items

A Line Item is a snapshot of a Product Variant at the time it is added to a Cart. A Custom Line Item is a generic item not associated to any Product Variant. As such, they can be used for selling services or virtual goods that do not require any tracking of inventory, like additional fees or vouchers.

Line Items

• The current projection is used.
• If the Cart is bound to a Store, the following additional checks and projections are performed:
  • For Stores with active Product Selections, the selected Product Variant must be included in at least one of the active Product Selections.
  • The selected Product Variant must be available in a Store.
  • All LocalizedStrings are filtered by the locales defined in the Store. If the API cannot find a matching locale in the Store languages, the first locale found in the Project settings is used as a fallback.
  • All Prices are filtered according to the Product distribution Channels defined in the Store. Prices without a Channel are also included.
  • All ProductVariantAvailabilities are filtered according to the Inventory supply Channel defined in the Store. Inventory entries without a Channel are also included.

Custom Line Items

Stores

If a Customer is assigned to one or more Stores, they are considered a Store-specific Customer. Store-specific Customers can only be associated with Carts and Orders in the assigned Stores. In contrast, global Customers are not assigned to any Stores and can be associated with Carts and Orders either in specific Stores or without a Store.

Cart price precision

• Prices with TypedMoney can be cent-precision or high-precision.
• When calculating net and gross prices, prices with decimals are rounded. If the fraction of centAmount is exactly 0.5, the RoundingMode defined by taxRoundingMode is applied to the Cart's price.
• If the tax is not included in the price (includedInPrice=false on the TaxRate), the tax portions are derived from the net prices. If the tax is included in the price (includedInPrice=true on the TaxRate), then the tax portions are derived from the gross prices. This only applies when the Platform TaxMode is used.
• If the prices are discounted and if tax is included in the price (includedInPrice=true on the TaxRate), the discount is applied to the gross price of a Line Item or Cart. If includedInPrice=false, the discount is applied to the net price of a Line Item or Cart.
• When prices are discounted with relative discounts, they are always rounded in favor of the customer with the half-down rounding.
• If a Line Item's priceMode is ExternalPrice and uses high-precision money, the totalPrice of the Line Item is calculated by multiplying the price by the quantity and then rounded by using the HalfEven rounding mode.

Cart tax rate selection

• If shippingAddress.country and TaxRate.country are an exact match, and no state properties are present, the TaxRate applies to the Cart.
• If shippingAddress.country and TaxRate.country are an exact match, but only one of shippingAddress.state or TaxRate.state is present, the Tax Rate does not apply to the Cart.
• If shippingAddress.country and TaxRate.country are an exact match, and shippingAddress.state and TaxRate.state are an exact match, the Tax Rate applies to the Cart.
• If shippingAddress.country and TaxRate.country are present, and shippingAddress.state and TaxRate.state are present, but there is a mismatch of either country or state, the Tax Rate does not apply to the Cart.

Cart tax calculation

Tax mode

• External: you are responsible for explicitly setting the Tax Rates for Line Items and Custom Line Items. With this tax mode, you must specify whether tax is included in the price for Line Items or Custom Line Items. This mode is suitable when you want Composable Commerce to handle the tax calculations based on the provided Tax Rates.
• ExternalAmount: you are responsible for providing the exact tax amounts for Line Item and Custom Line Items, and explicitly setting the taxedPrice of the Cart using Set Cart Total Tax. This mode is suitable when you want full control over the tax calculation. For more information about how to set tax amounts, see ExternalAmount TaxMode.

Tax calculation mode

Due to the principle of rounding on every calculation step, this slight difference in when to apply tax can have a considerable effect on the Cart total.

Composable Commerce offers two tax calculation modes to support different use cases:

• The LineItemLevel TaxCalculationMode enforces tax calculation after multiplying the individual item price by the quantity.
• The UnitPriceLevel mode calculates the taxed price before multiplying by the quantity.

The following example demonstrates the differences in the Cart total depending on the different tax calculation modes. Let's assume:

• A tax of 19% is included in the price for all Line Items.
• The Cart's TaxRoundingMode is HalfEven.
• The Cart's price precision is two decimals.

As seen from the example, if a Line Item has a quantity of 1, the two modes have no impact on the total net value of a Line Item (see Line Item #1, 4, and 6). However, if the quantity is more than 1, the two modes calculate the total net value of a Line Item with a difference of several cents (see Line Item #2, 3, and 5).

Depending on the specific Line Item values, the chosen mode can give a greater or lesser net value (see Line Item #2 compared to #3). A difference of 6 cents is accumulated in the Cart total. The connection to rounding is especially clear with Line Item #5.

Cart updates

• removes any Line Items that are invalid due to deleted Products, Product Variants, or Prices.

• removes any Line Items that are invalid due to an inactive StandalonePrice.
  When a Product is unpublished, any associated Line Items already present in a Cart remain unaffected and can still be ordered. To prevent this, do the following:

  • If the Product uses Embedded Prices, remove them from the unpublished Product.
  • If the Product uses Standalone Prices, inactivate or delete the Standalone Prices.
• updates any LineItem price field if the result of the Line Item price selection has changed because of a Product update,
• updates the ShippingInfo, in particular, the price and shippingMethodState fields,
• updates the discounts, which may affect the LineItem or CustomLineItem totalPrice fields and ShippingInfo discountedPrice field,
  • if a Cart Discount becomes invalid due to deactivation, expiration, or the predicate no longer matches the Cart's content, the discount is removed.
  • if a Cart Discount becomes active and applicable (since the last update), the discount is added.
  • if a Discount Code becomes invalid due to usage limits, deactivation, expiration, or the predicate no longer matches the Cart's content, the discount is removed.
• updates the Cart totalPrice field,
• updates the Tax Rates, in particular, the taxedPrice field,
• updates the LineItem productKey.

Frozen Carts

Restrictions of frozen carts:

• Cart Discounts that become active or are created after cart freeze are not applied.
• Cart Discounts and Product Discounts that expire after cart freeze remain applied.
• New Discount Codes can still be added to the cart, but their DiscountCodeState is of DoesNotMatchCart.
• Regardless of a cart freeze, Cart Discounts that are deleted or that become invalid due to Cart Predicates not matching, are removed from the cart.
• Regardless of a cart freeze, Cart Discounts and Discount Codes that become inactive, are removed from the cart.
• Regardless of a cart freeze, Discount Codes that become invalid due to Cart Predicates not matching, remain present on the cart with the DiscountCodeState of DoesNotMatchCart.
• Update actions that could change the price of items in the cart are not accepted. Find the list of restricted update actions on the Frozen value for CartState.
• All other update actions are still supported and applied. The API still performs the validations in the cart ensuring the cart is convertible to an Order, and reports errors if such a validation fails.

During Order creation, if a Frozen Cart contains a Discount that must be removed (according to the previously mentioned restrictions), the Order creation process fails.

Update an Order

An Order is a legally binding purchase agreement between the Merchant and the customer; therefore, changes to it should be carefully considered.

Make non-financial changes

For example, changes to:

• Order number, State, or locale
• Customer's email address or billing address
• Shipping information, such as addresses, that do not require recalculation of the Shipping Method and shipping rates
• Payment information
• Deliveries and returns
• Any other change that does not affect the Order total

Make financial changes

For example, changes to:

• Line Items and Custom Line Items (such as quantity)
• Shipping information, such as addresses, that require recalculation of the Shipping Method and shipping rates
• Discounts
• Any other change that affects the Order total

In addition to any updates that financially impact the Order, you can also update non-financial properties within the same Order Edit. For example, you can update a Customer's email address alongside any changes that affect the total price of the Order.

Overview of update actions for Cart, Order, and Order Edit

on LineItem

on CustomLineItem

on Billing Address

on Shipping Address

on ItemShipping Address

on ShippingMethod

on Shipping

on Delivery

on Delivery Address

on Parcel

on ReturnItem