Carts and Orders overview

Ask about this Page
Copy for AI
View as Markdown

Overview of the concepts related to Carts, Orders, and the overall checkout process.

Learn more about how to implement a custom checkout flow in our self-paced Implement a custom checkout module.

General concepts

This section covers key concepts and structures that apply to both Carts and Orders. Understanding these fundamentals is essential for effectively managing the checkout process and related resources.

Line Items

A Line Item is a snapshot of a Product Variant at the time it is added to a Cart.
For how the snapshot is created and when it is updated, see Carts and Orders APIs overview.

Carts containing Line Items that reference deleted Product Variants cannot be used to create Orders.

Custom Line Items

A Custom Line Item is a generic item not associated with a Product Variant. It can be used for selling services or virtual goods that do not require inventory tracking, such as additional fees or vouchers.
You add Custom Line Items to a Cart in the same way as Line Items. However, Line Item price selection doesn't apply to Custom Line Items; instead, you control the price and taxes of the item.
The monetary value of a Custom Line Item can be negative; therefore, it can be used for discounts applied by vouchers. Furthermore, Custom Line Items can be used to implement more complex cart logic through Cart Predicates.
For how inventory tracking applies to Custom Line Items, see Carts and Orders APIs overview.

Store-specific and global Customers

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 their 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.
For more information, see Global versus Store-specific Customers.

Guest checkout

To offer checkout functionality without requiring a visitor to sign in or create an account, you can create an anonymous session. For how anonymous sessions are linked to Carts and other resources, see Carts and Orders APIs overview.
A visitor can have multiple active Carts associated with their account, but they aren't signed in. In this case, if the visitor starts shopping with an anonymous Cart and later signs in to their account, the default behavior is to attempt to merge the items into their most recently modified active Cart, in a process called a Cart merge.

An anonymous Cart is persistent by default until it is merged with a customer's Cart.

A customer's Cart is persistent by default with no time limit.

For more information about transferring resources to a Customer during sign-up or sign-in, see Customer authentication.

Carts

Carts hold Product Variants that are referred to as Line Items once added to the Cart, and Custom Line Items. During checkout, a Cart is ordered.
Carts that can be updated and ordered have the Active state and are known as active Carts. Customers can have more than one active Cart.
For how to retrieve active Carts with the API, see Carts and Orders APIs overview.

Freeze a Cart

To prevent a Cart from being modified by changes to prices and, in specific cases, discounts, you can freeze it. This is useful during checkout to ensure the customer pays the price seen in their cart, even if prices or promotions change before order placement.
For the freeze strategies and how frozen Carts behave, see Carts and Orders APIs overview.

Lock a Cart

To prevent all updates to a Cart, you can lock it. Locking is distinct from freezing, which only blocks updates that affect the Cart's total price.
Use locking for assisted selling scenarios where a support agent needs exclusive access to a Cart while they perform updates. For how locking works with the API, see Carts and Orders APIs overview.

Merge a Cart

When a visitor starts shopping while signed out, you create an anonymous Cart to hold their items. If they later sign in to an account that already has an active Cart, you can merge the anonymous Cart into the existing active Cart. This ensures that they don't lose their selected items. You can trigger this merge automatically during sign-up or sign-in, or manually at any other time.

After a Cart merge, the resulting Cart depends on the selected merge mode. Depending on the scenario, the anonymous Cart may become the new active Cart, or its contents may be merged into the existing active Cart. Carts that are no longer active are not deleted and remain available for inspection, but may be read-only depending on their state.

For merge eligibility, merge methods, and merge modes, see Carts and Orders APIs overview.

Lifetime

During its lifetime, a Cart is kept as it was the last time when actions were performed on it. It contains Line Items and Custom Line Items with prices that were valid at the time of the last Cart update and Cart Discounts that were active at that time.
For how the lifetime of a Cart is set and when its prices are updated, see Carts and Orders APIs overview.

Price precision

For how prices and taxes are rounded, see Carts and Orders APIs overview.

Cash or denomination rounding

In some countries, prices must be rounded to the nearest 5 or 10 units since smaller coin denominations have been withdrawn from circulation. For example:

  • In Hungary, offline cash payments are rounded to the nearest 5 forints while online prices can use any amount.
  • In Switzerland, both offline and online prices are rounded to the nearest 5 centimes. Amounts ending in 1, 2, 6, or 7 round down, and amounts ending in 3, 4, 8, or 9 round up—for example, CHF 10.42 is rounded to CHF 10.40 and CHF 10.43 is rounded to CHF 10.45.
Cash rounding is not applied to Cart Discount results. For how cash rounding is applied to Cart totals, see Carts and Orders APIs overview.

Taxes

Tax rate selection

A Cart cannot calculate taxes for the items in it until the shipping address is set.

For how Tax Rates are matched to the shipping address, see Carts and Orders APIs overview.

Inventory

For details on managing inventory, including information about inventory modes, quantity enforcement, and consistency guarantees, see the Inventory overview.

Orders

An Order is a snapshot of a transaction between a customer and a business. It serves as a durable record of the transaction and includes details such as the selected items, pricing, customer information, shipping and billing addresses, selected shipping methods, payment information, and order state. While it does not inherently manage the full post-purchase lifecycle (such as fulfillment, returns, or refunds), it acts as the foundation upon which those processes can be built or integrated.

Create an Order

To create an Order, you use one of the following methods: from a Cart, from a Quote, or by using Order Import.

From a Cart

This is the most common method for creating an Order, used for typical customer purchases during checkout.

The following information is copied to the Order:

  • Line Items and Custom Line Items (with prices and any associated Custom Fields)
  • Shipping and billing addresses
  • Customer information
  • Custom Fields (Cart-level)
  • Selected Shipping Method
  • Payment information
  • Discount Codes
  • Direct Discounts
  • Direct Discount coexistence setting
  • Tax settings
  • Inventory Mode
  • Origin
  • Refused Gift Line Items
  • Cart reference
  • Any associated Store or Business Unit
For the endpoints that create an Order from a Cart, see Carts and Orders APIs overview.

From a Quote

This method creates an Order based on the agreed-upon terms of a Quote and is commonly used in B2B scenarios or when price negotiations are required. The Order includes the negotiated prices, quantities, and any other specific conditions outlined in the Quote.

The Quote transitions through different states during the negotiation process. To create an Order from a Quote, the Quote must have the Pending state.
For what Quotes are, see Quotes overview. For the endpoints that create an Order from a Quote, see Carts and Orders APIs overview.

Using Order Import

This method lets you import existing Orders from external systems or other Projects. This is useful when you need to migrate from a legacy system or consolidate Orders from different sources.

Order Import requires that you provide all necessary Order data in a specific format. This data must adhere to the Order model.

For the endpoint that imports Orders, see Carts and Orders APIs overview.

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.

To update the Order, you have two options: direct updates or Order Edits. The option you choose depends on whether a financial change to the purchase agreement is required.
If, for instance, a customer provides an incorrect shipping address by mistake, a change is required to ensure the goods can be delivered to the customer. A direct update action is available to change the shipping address for such cases. However, if the proposed change to the shipping address results in changes to the applicable taxes of the Order items, a direct update to the Order is not possible. In this case, because a financial change will occur, you must use an Order Edit instead, which ensures the amendment is traceable for audit purposes.
To learn about which update actions are available for each method, see Overview of update actions for Cart, Order, and Order Edit.

Non-financial changes

Use the Order update actions to directly modify an Order when no financial change occurs.

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

Financial changes

Use Order Edits when you need to update an Order that results in a financial change.

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.

For how Order Edits work with the API, see Carts and Orders APIs overview.
Shipping addresses, including country and state, are used to identify applicable Shipping Methods and shipping rates for an Order. You can update shipping addresses using direct updates or Order Edits, however, reevaluation of Shipping Methods and shipping rates is only triggered when changes are initiated through an Order Edit.

Payments

A Payment holds information about the payment service provider (PSP), the payment method used, any related transactions, and the current state of the Payment.

If you are using Checkout for your checkout solution, the Checkout Payment Intents API lets you request the PSP to perform actions throughout the financial process, such as payment capture, refund, and authorization cancellation.

Payment Methods

A Payment Method is designed to simplify integration with external Payment Service Providers (PSPs). It holds information about the PSP and the actual method used.

For how to work with Carts, Orders, and Payments with the API, see Carts and Orders APIs overview.