Overview of the concepts related to Carts, Orders, and the overall checkout process.
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
Carts containing Line Items that reference deleted Product Variants cannot be used to create Orders.
Custom Line Items
Store-specific and global Customers
Guest checkout
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.
Carts
Freeze a Cart
Lock a Cart
Merge a Cart
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.
Lifetime
Price precision
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.
Taxes
Tax rate selection
A Cart cannot calculate taxes for the items in it until the shipping address is set.
Inventory
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
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.
Pending state.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.
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.
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
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.
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.
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.